Closes #11 linkTo(attachment=x, attachmentStyle='small'). Changes ima…

…geTag() to attachmentImageTag() to avoid name clashes with other plugins like ColdRoute.

README.md

@@ -0,0 +1,26 @@
+= CFWheels Attachments Plugin
+
+Add support for file uploads to your [CFWheels][1] model with the `hasAttachment()` function. Also provides `attachmentImageTag()` and `attachmentLinkTo()` view helpers.
+
+Automatically resize uploaded images to a set of "styles" that you define. (For example, you could automatically resize for `thumbnail`, `small`, `medium`, `large`, etc.)
+
+Overrides `fileField()` to work better with `<cffile>` and [nested properties][2].
+
+== Dependencies
+
+You must also install the [JSON Properties plugin][3] for the Attachments plugin to work.
+
+== Documentation
+
+For more documentation, install the Attachments plugin and click the _Attachments_ link in the _Plugins_ section of the debugging section of your CFWheels application's footer.
+
+== Credits
+
+This plugin was created by [James Gibson][4] and [Chris Peters][5] with support from [Liquifusion Studios][6].
+
+[1]: http://cfwheels.org/
+[2]: http://cfwheels.org/docs/chapter/nested-properties
+[3]: https://github.com/liferealized/cfwheels-json-properties
+[4]: http://iamjamesgibson.com/
+[5]: http://www.clearcrystalmedia.com/
+[6]: http://liquifusion.com/

attachments/functions.cfm

@@ -3,4 +3,5 @@
 <cfinclude template="model/callbacks.cfm" />
 <cfinclude template="model/validations.cfm" />
 <cfinclude template="view/assets.cfm" />
+<cfinclude template="view/links.cfm" />
 <cfinclude template="view/formsobject.cfm" />

attachments/view/assets.cfm

@@ -1,6 +1,6 @@
-<cffunction name="imageTag" returntype="string" mixin="controller" hint="Returns an image tag built for attachments. Otherwise, follows normal `imageTag()` behavior.">
+<cffunction name="attachmentImageTag" returntype="string" mixin="controller" hint="Returns an image tag built for attachments. Otherwise, follows normal `imageTag()` behavior.">
 	<cfargument name="source" type="string" required="false" default="" hint="The file name of the image if it's availabe in the local file system (i.e. ColdFusion will be able to access it). Provide the full URL if the image is on a remote server.">
-	<cfargument name="attachment" required="false" default="" hint="Pass an attachment property struct here to use an attachment.">
+	<cfargument name="attachment" required="false" default="" hint="Pass an attachment property struct here to use an attachment. Can be a struct or JSON-formatted.">
 	<cfargument name="attachmentStyle" required="false" default="" hint="Pass an attachment style name here to use a particular attachment's style.">
 	<cfscript>
 		var loc = {
@@ -15,35 +15,26 @@
 		if (IsJson(arguments.attachment))
 			arguments.attachment = DeserializeJson(arguments.attachment);
 
-		// Handle attachment images
-		if (IsStruct(arguments.attachment))
+		// ugly fix due to the fact that id can't be passed along to cfinvoke
+		if (StructKeyExists(loc.imageTagArgs, "id"))
 		{
-			// ugly fix due to the fact that id can't be passed along to cfinvoke
-			if (StructKeyExists(loc.imageTagArgs, "id"))
-			{
-				loc.imageTagArgs.wheelsId = loc.imageTagArgs.id;
-				StructDelete(loc.imageTagArgs, "id");
-			}
+			loc.imageTagArgs.wheelsId = loc.imageTagArgs.id;
+			StructDelete(loc.imageTagArgs, "id");
+		}
 
-			if (Len(arguments.attachmentStyle))
-				loc.imageTagArgs.src = arguments.attachment.styles[arguments.attachmentStyle].url;
-			else
-				loc.imageTagArgs.src = arguments.attachment.url;
+		if (Len(arguments.attachmentStyle))
+			loc.imageTagArgs.src = arguments.attachment.styles[arguments.attachmentStyle].url;
+		else
+			loc.imageTagArgs.src = arguments.attachment.url;
 
-			if (!StructKeyExists(loc.imageTagArgs, "alt"))
-				loc.imageTagArgs.alt = capitalize(ReplaceList(SpanExcluding(Reverse(SpanExcluding(Reverse(loc.imageTagArgs.src), "/")), "."), "-,_", " , "));
+		if (!StructKeyExists(loc.imageTagArgs, "alt"))
+			loc.imageTagArgs.alt = capitalize(ReplaceList(SpanExcluding(Reverse(SpanExcluding(Reverse(loc.imageTagArgs.src), "/")), "."), "-,_", " , "));
 
-			loc.returnValue = $tag(name="img", skip="source,key,category", close=true, attributes=loc.imageTagArgs);
+		loc.returnValue = $tag(name="img", skip="source,key,category", close=true, attributes=loc.imageTagArgs);
 
-			// ugly fix continued
-			if (StructKeyExists(loc.imageTagArgs, "wheelsId"))
-				loc.returnValue = ReplaceNoCase(loc.returnValue, "wheelsId", "id");
-		}
-		// Normal `imageTag()` request
-		else
-		{
-			loc.returnValue = loc.coreImageTag(loc.imageTagArgs);
-		}
+		// ugly fix continued
+		if (StructKeyExists(loc.imageTagArgs, "wheelsId"))
+			loc.returnValue = ReplaceNoCase(loc.returnValue, "wheelsId", "id");
 	</cfscript>
 	<cfreturn loc.returnValue>
 </cffunction>

attachments/view/links.cfm

@@ -0,0 +1,29 @@
+<cffunction name="attachmentLinkTo" returntype="string" access="public" output="false" hint="Creates a link to an attachment uploaded via the Attachments plugin. Note: Pass any additional arguments like `class`, `rel`, and `id`, and the generated tag will also include those values as HTML attributes.">
+	<cfargument name="text" type="string" required="false" default="" hint="The text content of the link.">
+	<cfargument name="attachment" required="false" default="" hint="Pass an attachment property struct here to use an attachment. Can be a struct or JSON-formatted.">
+	<cfargument name="attachmentStyle" required="false" default="" hint="Pass an attachment style name here to use a particular attachment's style.">
+	<cfscript>
+		var loc = {
+			linkToArgs=Duplicate(arguments),
+			skip="text,confirm,route,controller,action,key,params,anchor,onlyPath,host,protocol,port"
+		};
+		
+		// Remove non-string values
+		StructDelete(loc.linkToArgs, "attachment");
+		StructDelete(loc.linkToArgs, "attachmentStyle");
+
+		if (IsJson(arguments.attachment))
+			arguments.attachment = DeserializeJson(arguments.attachment);
+
+		if (Len(arguments.attachmentStyle))
+			loc.linkToArgs.href = arguments.attachment.styles[arguments.style].url;
+		else
+			loc.linkToArgs.href = arguments.attachment.url;
+
+		if (!Len(loc.linkToArgs.text))
+			loc.linkToArgs.text = loc.linkToArgs.href;
+
+		loc.returnValue = $element(name="a", skip=loc.skip, content=loc.linkToArgs.text, attributes=loc.linkToArgs);
+	</cfscript>
+	<cfreturn loc.returnValue>
+</cffunction>

index.cfm

@@ -1,7 +1,7 @@
 <cfsetting enablecfoutputonly="true" />
 
 <cfset attachments = {}>
-<cfset attachments.version = "0.6">
+<cfset attachments.version = "0.7">
 
 <cfinclude template="stylesheets/doc_styles.cfm" />
 
@@ -10,7 +10,7 @@
 <h1>Attachments v#attachments.version#</h1>
 
 <p>
-	Add support for uploaded files to your model with the <tt>hasAttachment()</tt> function.
+	Add support for file uploads to your model with the <tt>hasAttachment()</tt> function. Also provides <tt>attachmentImageTag()</tt> and <tt>attachmentLinkTo()</tt> view helpers.
 </p>
 <p>
 	Automatically resize uploaded images to a set of &quot;styles&quot; that you define. (For example, you could automatically
@@ -265,11 +265,16 @@
 	Note that when the <tt>allowExtensions</tt> list is provided, the <tt>blockExtensions</tt> list will be ignored completely.
 </p>
 
-<h3>View Helper for Images</h3>
+<h3>View Helpers</h3>
+<p>
+	The plugin also provides helpers&mdash;<tt>attachmentImageTag()</tt> and <tt>attachmentLinkTo()</tt>&mdash;for displaying
+	images and linking to files uploaded via attachments.
+</p>
 
+<h3>Displaying Images via <tt>attachmentImageTag()</tt></h3>
 <p>
-	The plugin also modifies the Wheels <tt>imageTag()</tt> method to accept 2 additional arguments. These arguments help you
-	work with images uploaded as attachments and any associated styles that you may have configured for the images.
+	<tt>attachmentImageTag()</tt> allows you to display an image uploaded via the Attachments plugin. It optionally allows you
+	to specify any style generated when the attachment was uploaded and handles all of the data references for you.
 </p>
 <table>
 	<thead>
@@ -294,7 +299,7 @@
 			<td>string</td>
 			<td><tt>false</tt></td>
 			<td><tt>[empty&nbsp;string]</tt></td>
-			<td>Image style to reference (as configured in <tt>hasAttachment()</tt>'s <tt>styles</tt> argument.</td>
+			<td>Name of image style to reference (as configured in <tt>hasAttachment()</tt>'s <tt>styles</tt> argument.</td>
 		</tr>
 	</tbody>
 </table>
@@ -304,18 +309,101 @@
 <h5>Example 1: Simple image call</h5>
 <p>Given that there is an attachment property called <tt>attachment</tt> on the <tt>user</tt> model:</p>
 <pre>
+// In the `init()` method of `models/User.cfc`
+hasAttachment(property="attachment", allowExtensions=GetReadableImageFormats());</pre>
+<p>
+	You can display uploaded images like so:
+</p>
+<pre>
 &lt;cfoutput&gt;
-	##imageTag(attachment=user.attachment)##
+	##attachmentImageTag(attachment=user.attachment)##
 &lt;/cfoutput&gt;</pre>
 
-<h5>Example 2: Stylized image call</h5>
+<h5>Example 2: Display stylized image</h5>
 <p>
 	Given that there is an attachment property called <tt>avatar</tt> on the <tt>profile</tt> model with a style called
+	<tt>small</tt>:
+</p>
+<pre>
+// In the `init()` method of `models/Profile.cfc`
+##hasAttachment(property=&quot;avatar&quot;, styles=&quot;small:100x100&quot;, allowExtensions=GetReadableImageFormats())##</pre>
+<p>
+	You can display the stylized image like so:
+</p>
+<pre>
+&lt;cfoutput&gt;
+	##attachmentImageTag(attachment=profile.avatar, attachmentStyle=&quot;small&quot;)##
+&lt;/cfoutput&gt;</pre>
+
+<h3>Linking to Files via <tt>attachmentLinkTo()</tt></h3>
+<p>
+	Similar to <tt>attachmentImageTag()</tt>, <tt>attachmentLinkTo()</tt> allows you to link to a file uploaded via this
+	plugin, also optionally with image styles.
+</p>
+<table>
+	<thead>
+		<tr>
+			<th>Argument</th>
+			<th>Type</th>
+			<th>Required</th>
+			<th>Default</th>
+			<th>Description</th>
+		</tr>
+	</thead>
+	<tbody>
+		<tr>
+			<td><tt>text</tt></td>
+			<td>string</td>
+			<td><tt>false</tt></td>
+			<td><tt>[empty&nbsp;string]</tt></td>
+			<td>Link text. If left blank, the path to the attachment file is used as the link text.</td>
+		</tr>
+		<tr class="highlight">
+			<td><tt>attachment</tt></td>
+			<td>string/struct</td>
+			<td><tt>false</tt></td>
+			<td><tt>[empty&nbsp;string]</tt></td>
+			<td>Value of attachment property. Accepts both JSON- and struct-formatted data.</td>
+		</tr>
+		<tr>
+			<td><tt>attachmentStyle</tt></td>
+			<td>string</td>
+			<td><tt>false</tt></td>
+			<td><tt>[empty&nbsp;string]</tt></td>
+			<td>Name of image style to reference (as configured in <tt>hasAttachment()</tt>'s <tt>styles</tt> argument.</td>
+		</tr>
+	</tbody>
+</table>
+
+<h4>Examples</h4>
+
+<h5>Example 1: Simple link</h5>
+<p>Given that there is an attachment property called <tt>documentation</tt> on the <tt>equipment</tt> model:</p>
+<pre>
+// In the `init()` method of `models/Equipment.cfc`
+##hasAttachment(property=&quot;documentation&quot;)##</pre>
+<p>
+	You can link to the file in your view like this:
+</p>
+<pre>
+&lt;cfoutput&gt;
+	##attachmentLinkTo(text=&quot;Download the Manual&quot;, attachment=equipment.documentation)##
+&lt;/cfoutput&gt;</pre>
+
+<h5>Example 2: Link directly to a stylized image</h5>
+<p>
+	Given that there is an attachment property called <tt>photo</tt> on the <tt>person</tt> model with a style of
 	<tt>medium</tt>:
 </p>
 <pre>
+// In the `init()` method of `models/Person.cfc`
+##hasAttachment(property=&quot;photo&quot;, styles=&quot;medium:300x300&gt;,avatar:100x100&quot;, allowExtensions=GetReadableImageFormats())##</pre>
+<p>
+	You can link to the stylized image in your view like so:
+</p>
+<pre>
 &lt;cfoutput&gt;
-	##imageTag(attachment=profile.attachment, style="medium")##
+	##attachmentLinkTo(text=&quot;Download Photo&quot;, attachment=person.photo, attachmentStyle=&quot;medium&quot;)##
 &lt;/cfoutput&gt;</pre>
 
 <h2>Uninstallation</h2>