Permalink
Browse files

Merge pull request #10 from liquifusion/master

Closes #9 imageTag(attachment=x)
  • Loading branch information...
2 parents d6c0bdb + cc45d74 commit f3e48479151bca1abb43fcc82e66d2472f076ab6 Chris Peters committed Mar 15, 2012
Showing with 117 additions and 9 deletions.
  1. +1 −0 attachments/functions.cfm
  2. +49 −0 attachments/view/assets.cfm
  3. +67 −9 index.cfm
View
1 attachments/functions.cfm
@@ -2,4 +2,5 @@
<cfinclude template="model/attachments.cfm" />
<cfinclude template="model/callbacks.cfm" />
<cfinclude template="model/validations.cfm" />
+<cfinclude template="view/assets.cfm" />
<cfinclude template="view/formsobject.cfm" />
View
49 attachments/view/assets.cfm
@@ -0,0 +1,49 @@
+<cffunction name="imageTag" 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="attachmentStyle" required="false" default="" hint="Pass an attachment style name here to use a particular attachment's style.">
+ <cfscript>
+ var loc = {
+ coreImageTag=core.imageTag,
+ imageTagArgs=Duplicate(arguments)
+ };
+
+ // Remove non-string values
+ StructDelete(loc.imageTagArgs, "attachment");
+ StructDelete(loc.imageTagArgs, "attachmentStyle");
+
+ 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"))
+ {
+ 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 (!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);
+
+ // 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);
+ }
+ </cfscript>
+ <cfreturn loc.returnValue>
+</cffunction>
View
76 index.cfm
@@ -1,7 +1,7 @@
<cfsetting enablecfoutputonly="true" />
<cfset attachments = {}>
-<cfset attachments.version = "0.5">
+<cfset attachments.version = "0.6">
<cfinclude template="stylesheets/doc_styles.cfm" />
@@ -25,13 +25,18 @@
<p>You must also install the JSON Properties plugin for the Attachments plugin to work.</p>
<h2>Usage</h2>
-<p>Call the included <tt>hasAttachment()</tt> from a model's <tt>init()</tt> method to bind one or more properties to handle uploaded files.</p>
+
+<h3>Model Configuration</h3>
+<p>
+ Call the included <tt>hasAttachment()</tt> from a model's <tt>init()</tt> method to bind one or more properties to handle uploaded
+ files.
+</p>
<p>
The plugin stores data about the uploaded files as serialized JSON data in your model, so you should set the configured property's
corresponding database column to a type of <tt>TEXT</tt> or similar.
</p>
-<h3>Arguments</h3>
+<h4><tt>hasAttachment()</tt> Arguments</h4>
<table>
<thead>
<tr>
@@ -95,7 +100,7 @@
</tbody>
</table>
-<h3>Callbacks</h3>
+<h4>Callbacks</h4>
<p>
This plugin adds its own callbacks to the model's callback chain.
</p>
@@ -119,9 +124,9 @@
<tt><a href="http://cfwheels.org/docs/function/afterUpdate">afterUpdate</a></tt>.
</p>
-<h2>Examples</h2>
+<h4>Examples</h4>
-<h3>Example 1: Simple configuration</h3>
+<h5>Example 1: Simple configuration</h5>
<p>
In its most simple form, let's pretend that you want to save files to a property in the <tt>comment</tt> model called <tt>attachment</tt>:
</p>
@@ -163,7 +168,7 @@
&lt;p&gt;&lt;a href=&quot;##comment.attachment.url##&quot;&gt;Download the File&lt;/a&gt;&lt;/p&gt;
&lt;/cfoutput&gt;</pre>
-<h3>Example 2: Saving to a different location</h3>
+<h5>Example 2: Saving to a different location</h5>
<p>
If you want to store the file in a different location on the server, you can specify the path using the <tt>:path</tt>
argument and the placeholders for <tt>:model</tt>, <tt>:property</tt>, <tt>:id</tt>, <tt>:style</tt> (more on this
@@ -189,7 +194,7 @@
&lt;/cffunction&gt;
&lt;/cfcomponent&gt;</pre>
-<h3>Example 3: Styles for images</h3>
+<h5>Example 3: Styles for images</h5>
<p>
The attachments plugin will also handle the creation of &quot;styles&quot; for image files uploaded to your model.
If you choose, you can create any named style that you would like (for example, <tt>thumbnail</tt>).
@@ -239,7 +244,7 @@
</li>
</ul>
-<h3>Example 4: Whitelisting files</h3>
+<h5>Example 4: Whitelisting files</h5>
<p>
By default, the Attachments plugin will block a list of potentially malicious files (using a default value for the
<tt>blockExtensions</tt> argument). But it is strongly recommended for security reasons that you define a whitelist of
@@ -260,6 +265,59 @@
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>
+
+<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.
+</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>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 class="highlight">
+ <td><tt>attachmentStyle</tt></td>
+ <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>
+ </tr>
+ </tbody>
+</table>
+
+<h4>Examples</h4>
+
+<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>
+&lt;cfoutput&gt;
+ ##imageTag(attachment=user.attachment)##
+&lt;/cfoutput&gt;</pre>
+
+<h5>Example 2: Stylized image call</h5>
+<p>
+ Given that there is an attachment property called <tt>avatar</tt> on the <tt>profile</tt> model with a style called
+ <tt>medium</tt>:
+</p>
+<pre>
+&lt;cfoutput&gt;
+ ##imageTag(attachment=profile.attachment, style="medium")##
+&lt;/cfoutput&gt;</pre>
+
<h2>Uninstallation</h2>
<p>To uninstall this plugin, simply delete the <tt>/plugins/Attachments-#attachments.version#.zip</tt> file.</p>

0 comments on commit f3e4847

Please sign in to comment.