Related Content and Library Options

Array and UUID properties are effectively references to other content objects in the system. Selecting the appropriate relationship is done through the use of a data library. The library sub-system in farcry provides all the relevant UI to actively select and relate content objects with each other. The following options are available for both array and UUID form tool types.

Automated Joining

The developer must nominate the specific content types to which you are able to relate an object reference. Relationships can be made to any other registered content type in the system. Using this information the library form tools will automatically join the relevant tables in the COAPI and present relevant choices for users in the UI.

Attribute	Description	Value
ftJoin	Nominates a specific content type that this property is bound to.	Must specify a list of valid typenames.

Customising the Rendering/Styles of Library Data

If you don't go for the default styles, and handlers for libraries that ship with FarCry you can override them for any specific property.

Attribute	Description	Value
ftRenderType	Specify how to render the form element for the array, library pop-up, select dropdown, or list of checkbox buttons.	Library, list, or checkbox(default = Library)
ftSelectMultiple	Allow selection of multiple items from a select list	true or false (default = true)
ftSelectSize	Specify the number of items displayed of a select list	default = 10
ftlibrarypickliststyle	Library pick list style.	border: red 1px solid;
ftLibraryPickListClass	Library pick list class.	defaults to...
ftLibraryAddNewMethod	Edit method to render handler when adding a content item through the library. As the library environment is a little unique a standard edit method won't work here.	By default will look for ./webskin/typename/libraryAdd.cfm
ftAllowLibraryAddNew	Boolean to turn on/off ADD tab in the library view.	true/false; default true
ftLibraryPickMethod	Display method to render thumbnail when adding a content item through the library.	By default will look for ./webskin/typename/libraryPick.cfm
ftLibrarySelectedMethod	Display method to render thumbnail when content item is selected in the library or shown on a stadard edit form.	By default will look for ./webskin/typename/librarySelected.cfm
ftLibraryPickListClass
ftLibraryPickListStyle
ftLibrarySelectedListClass
ftLibrarySelectedListStyle
ftShowLibraryLink	Controls the display of the library link in forms	true or false (default = true)

Edit Options

It's possible to activate an edit handler within the library pop-up window. Note such an edit handler has certain restrictions due to itsw environment, for example, you cannot reference another array/uuid library window.

Attribute	Description	Value
ftAllowLibraryEdit	Boolean to activate edit option.	Defaults to false
ftLibraryEditWebskin	Nominate a specific webskin to override the default library edit behaviour.	n/a

Simple Options for Populating Library Data

If you need to filter the results of a library look up, you can do so by nominating a SQL where clause or order by statement through the formtool metadata.

Attribute	Description	Value
ftlibrarydatasqlwhere	A simple where clause filter for the library data result set. Must be in the form PROPERTY OPERATOR VALUE.	For example, status = 'approved'
ftlibrarydatasqlorderby	Nominate a specific property to order library results by.	Defaults to label.

Advanced Options for Populating Library Data

By default the library builds a query of all the data that can be found when joining to the related content types nominated in ftjoin. However, you can override this behaviour by creating your own library methods.

Attribute	Description	Value
ftLibraryData	Calls a public method on the adjoining content type to pre-populate the pop-up library. This is very useful if the property's related content is restricted to a subset.	Defaults to all content items for the nominated content type.
ftLibraryDataTypename	If the joining content type is not the one you want to fire the library data method on, you can override this value by nominating a different content type.	Defaults to all content items for the nominated content type.

The library subsystem integrates a free text search option for users if there a collection exists for the relevant content type. The library method must combine both the free text search result set into whatever business logic is being used to restrict the library dataset. Consequently these custom methods must conform to a specific set of arguments and return structure in order to work within the library subsystem.

Simple Library Function

<cffunction name="getAuthorsSimple" access="public" output="false" returntype="query" hint="Return a query for all author profiles ordered by Fullname.">
	<cfargument name="primaryID" type="uuid" required="true" hint="ObjectID of the object that we are attaching to" />
	<cfargument name="qFilter" type="query" required="false" default="#queryNew('blah')#" hint="If a library verity search has been run, this is the qResultset of that search" />

	<cfset var q = queryNew("blah") />

	<!---
	Run the entire query and return in to the library. Let the library handle the pagination.
	 --->
	<cfquery datasource="#application.dsn#" name="q">
	SELECT *
	FROM ourProfile
	where bAuthor = 1
	<cfif arguments.qFilter.RecordCount>
		AND ObjectID IN (#ListQualify(ValueList(qFilter.key),"'")#)
	</cfif>
	ORDER BY FullName
	</cfquery>

	<cfreturn q />

</cffunction>

With very large result sets its critical that the result set is limited to only retrieve those records to be rendered in the paginated display. Otherwise very large recordsets have a tendency to crash the library subsystem. You can avoid this by using some of the more advanced formtool options. Note that we are returning a struct rather than a straight query.

Advanced Paginated Library Function

<cffunction name="getAuthors" access="public" output="false" returntype="struct" hint="Return a query for all author profiles ordered by Fullname.">
	<cfargument name="primaryID" type="uuid" required="true" hint="ObjectID of the object that we are attaching to" />
	<cfargument name="qFilter" type="query" required="false" default="#queryNew('blah')#" hint="If a library verity search has been run, this is the qResultset of that search" />

	<cfset var stResult = structNew() />

	<cfset var oFormTools = createObject("component","farcry.core.packages.farcry.formtools")>
	<cfset var stLibraryData = structNew() />

	<cfset var filterList = "" />
	<cfset var sqlWhere = "bAuthor=1" />

	<!---
	If we have been sent a verity search resultset, we need to add this to our sqlWhere clause.
	This could be slow if there is a very large resultset.
	 --->
	<cfif arguments.qFilter.RecordCount>
		<cfset filterList = ListQualify(ValueList(qFilter.key),"'") />
		<cfset sqlWhere = "#sqlWhere# AND ObjectID IN (#filterList#)" />
	</cfif>

	<!--- This function returns a recordset containing only the page of information that we require. --->
	<cfset stResult = oFormTools.getRecordset(typename="ourProfile", sqlColumns="*", sqlOrderBy="fullname", SQLWhere="#sqlWhere#", RecordsPerPage="20") />


	<!--- Return the structure containing the resultset and metadata about it (total rows, current page and so on) --->
	<cfreturn stResult />
</cffunction>