Farcry Custom Widgets

This is a quick how-to for custom widgets. Widgets can be a really powerful tools if used correctly. I recently found a really good use for them so here is an explanation of how to create them and use them. Enjoy!

Create a folder path inside your project folder that looks like this: /farcry/project_name/tags/widgets. This will hold any custom widgets. I’ve blogged about this before but we are going to create a link inserter widget. Create a file inside the folder you just made called whatever you want (I’m using bodyInsertLink.cfm). Here’s the code:

<cfoutput>
	<cfquery name="getHTMLPages" datasource="#application.dsn#">
		SELECT	label,objectid
		FROM	dmHTML
		WHERE	status = <cfqueryparam cfsqltype="CF_SQL_VARCHAR" value="approved">
		UNION
		SELECT	label,objectid
		FROM	dmInclude
		WHERE	status = <cfqueryparam cfsqltype="CF_SQL_VARCHAR" value="approved">
		ORDER BY label ASC
	</cfquery>

	<script type="text/javascript" language="JavaScript">
		function getLinkValueInsert()
		{
			objSelect = document.getElementById("links");
			tempStr = objSelect.options[objSelect.selectedIndex].value;
			arVal = tempStr.split("|");
			oID = arVal[0];
			label = arVal[1];
			//alert(tempStr+"\\n"+oID+"\\n"+label);
			if(!oID || !label)
				alert("Please select a valid link to insert.");
			else
				insertHTML('<a href="#application.url.conjurer#?objectid='+oID+'">'+label+'</a>');
			return false;
		}
	</script>

	<div class="relateditems-wrap" style="margin-left:30px;">
		<h2>Links</h2>
		<select name="links" id="links" size="3">
			<cfloop from="1" to="#getHTMLPages.recordcount#" step="1" index="i">
				<option value="#getHTMLPages.objectid[i]#|#getHTMLPages.label[i]#">#getHTMLPages.label[i]#</option>
			</cfloop>
		</select>
		<div class="f-submit-wrap">
			<input type="button" name="buttonInsertLinkInBody" value="Insert in body" class="f-submit" onclick="return getLinkValueInsert();" />
		</div>
	</div>
</cfoutput>

Now, wherever you want to call this widget you can simply import the tag library like this:

<cfimport taglib="/farcry/project_name/tags/widgets" prefix="cWidgets">

Change project name to whatever the your project name is. You cannot use variable names inside a cfimport tag but the project name is stored in #application.applicationname# if you don’t know it.

Finally, call the widget in your code like this:

<cWidgets:bodyInsertLink>

Wigets can contain attributes if necessary the same as when you call a file using cfmodule. In this case, let’s say we wanted to allow the user to define if we are pulling dmHTML objects in approved or draft status. In the widget we can have the following code:

<cfparam name="attributes.status" default="approved">

Later in the file we can alter the query based on this variable:

<cfquery name="getHTMLPages" datasource="#application.dsn#">
	SELECT	label,objectid
	FROM	dmHTML
	WHERE	status = <cfqueryparam cfsqltype="CF_SQL_VARCHAR" value="approved">
	UNION
	SELECT	label,objectid
	FROM	dmInclude
	WHERE	status = <cfqueryparam cfsqltype="CF_SQL_VARCHAR" value="#attributes.status#">
	ORDER BY label ASC
</cfquery>

The new call to this file would look like this:

<cWidgets:bodyInsertLink status="approved">