Add tests and documentation for useRelative

README.md

@@ -66,7 +66,42 @@ Then we will stick a few images inside our path: `src/files/associated-files/my-
 </p>
 ```
 
-Ins't that cool?
+
+## 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(): %>
+<p>
+	<h3><%= file.title or file.name %></h3>
+	<img src="<%= file.url %>" title="<%= file.title or file.name %>" />
+</p>
+<% end %>
+```
 
 
 <!-- HISTORY/ -->

src/associatedfiles.plugin.coffee

@@ -28,8 +28,13 @@ module.exports = (BasePlugin) ->
 
 			# Extend our prototype
 			DocumentModel::getAssociatedFilesPath = ->
-				documentBase = if config.useRelativeBase then @get('relativeBase') else @get('basename')
+				# Retrieve the document base name, minding relative paths.
+				documentBase = if config.useRelativeBase or @get('associatedFilesRelative') then @get('relativeBase') else @get('basename')
+
+				# Find the associated files path for the document.
 				documentAssociatedFilesPath = @get('associatedFilesPath') or documentBase
+
+				# Get the clean path for the associated files.
 				documentAssociatedFilesPathNormalized = @getPath(documentAssociatedFilesPath, associatedFilesPath)
 				unless documentAssociatedFilesPathNormalized.slice(-1) in ['\\','/']
 					documentAssociatedFilesPathNormalized += pathUtil.sep

test/out-expected/associated-files/subfolder/test3/test3-a.txt

@@ -0,0 +1 @@
+c

test/out-expected/subfolder/test3.html

@@ -0,0 +1 @@
+["test3-a.txt"]

test/src/documents/subfolder/test3.html.eco

@@ -0,0 +1,5 @@
+---
+associatedFilesRelative: true
+---
+
+<%- JSON.stringify @getDocument().getAssociatedFiles().pluck('filename') %>

test/src/files/associated-files/subfolder/test3/test3-a.txt

@@ -0,0 +1 @@
+c