NAME

MKDoc::Core::ResourceFinder - Inheritable resources module.

SUMMARY

There's more to a web application than just code. Typically you also want to have also config files, some images (i.e logos, buttons, etc), some CSS files, some templates, etc.

Those things need to have a URI and they also need to be accessible from within your program.

Ideally you want to be able to:

Bundle those files with your CPAN distribution.

Serve those files 'out of the box' when installing a new site.

Have an easy mechanism to override those files.

MKDoc::Core::ResourceFinder is a module providing helper functions in order to achieve this goal.

Any MKDoc::Core product can bundle resource files anywhere in lib/MKDoc/resources. It means that the files will be installed somewhere in @INC/MKDoc/resources.

The MKDoc::Core::Plugin::Resources will serve the files so that a request to /.resources/foo/bar.txt serves the right @INC/MKDoc/resources/foo/bar.txt file.

However, those files are mainly 'factory default', shipped so that you can have something working immediately. You certainly almost always want to redefine them either on a server-wide basis, or even on a per-site basis.

In order to accomplish this, the MKDoc::Core::ResourceFinder looks for resources in:

<SITE_DIR>/resources

<MKDOC_DIR>/resources

@INC/resources

Furthermore, whenever it sees a file which is called "<filename>.deleted" it will consider that the file is not there, even if it's defined later on.

API

MKDoc::Core::ResourceFinder::list ($some_directory);

Reads the content of multiple directories (<SITE_DIR>/resources, <MKDOC_DIR>/resources, @INC) and merges it in a single list. Returns the merged list.

Use this instead of readdir().

MKDoc::Core::ResourceFinder::rel2abs ($something);

Searches for $something in multiple directories, and returns the full path if found. Returns undef otherwise.