# Associated Files Plugin for [DocPad](http://docpad.org)

This plugin streamlines finding associated files for a particular document in [DocPad](https://docpad.org), which is useful for: - getting images for a gallery - getting downloads for an article - etc. etc. ## Install ```bash docpad install associatedfiles ``` ## Usage The way it works is by looking into `src/files/associated-files/#{document.associatedFilesPath or document.basename}` for files. Where `associatedFilesPath` is set in your document's meta data, and if it doesn't exist it will use the document's basename (e.g. the basename of `my-holiday-2012.html.eco` is `my-holiday-2012`). Any files inside that path will be associated to your document, and retrieveable by `@getDocument().getAssociatedFiles()` Lets see how this works, we have the document `src/documents/my-holiday-2012.html.eco`: ```html --- title: My Holiday in 2012 ---

Here are some great photos from our trip

<% for file in @getDocument().getAssociatedFiles().toJSON(): %>

<%= file.title or file.name %>

<% end %> ``` Then we will stick a few images inside our path: `src/files/associated-files/my-holiday-2012`. And we'll end up with the rendered result: ```html

Here are some great photos from our trip

sweet-sweet-beach.jpg

sweet-sweet-icecream.jpg

``` ## Configure ### Defaults The default configuration for this plugin is the equivalant of adding the following options to your [DocPad configuration file](http://docpad.org/docs/config): ```coffee plugins: associatedfiles: # The paths for the associated files. associatedFilesPath: 'associated-files' # Whether to use relative base paths for the document. This would # use associated-files/subfolder/myarticle/image.jpg instead of # associated-files/myarticle/image.jpg. useRelativeBase: false ``` ### Template Configuration It is possible to override the default configuration on a per-template basis: ```html --- associatedFilesRelative: true associatedFilesPath: './myfolder' --- <% for file in @getDocument().getAssociatedFiles().toJSON(): %>