Overview

FarCry formtools provides default support for the award winning tinyMCE rich text editor.

Support for alternative rich text editors will be provided through plugins. Official XStandard support is currently in development; FarCry XStandard plugin. Other editors may be supported to varying degrees through the FarCry developer community.

Rich Text Editor

Formtool metadata for the rich text editor control provides extensive integration with FarCry. By varying the configuration of the editor you can customise your contributors experience.

Attribute	Description	Default Value
ftImageArrayField	Array property in content type containing available images. Is used to populate tinyMCE's external_image_list_url value.	For example, aobjectids in dmHTML
ftImageTypename	The content type representing the image library.	For example, dmImage in dmHTML
ftImageField	The specific field or property in the nominated image library type that holds the file path for the image to be inserted. Note this can be overriden using "insert templates".	For example, dmImage.standardImage in dmHTML.
ftTemplateTypeList	List of content types nominated to provide HTML insert options for tinyMCE editor. Each type must have at least one "insert webskin" associated with it.	For example, in dmHTML dmImage, dmFile, dmNavigation, and other dmHTML content items can be directly associated with the content.
ftTemplateWebskinPrefixList	The filename prefix used to determine suitable "insert webskins" for the nominated template types.	For example, insertHTML.
ftTemplateSnippetWebskinPrefix	The content type using hte rich text editor may have some predefined content snippets for use by content contributors. This prefix allows the developer to filter the available list of snippets for the specific instance of the editor.	For example, insertSnippet.
ftLinkListRelatedTypenames	a list of types that if any objects of that type are related to the current object via an array property, a link to that object will be presented in the richtext popup link list	For example, "dmFile,dmFlash,dmLink"

ftconfig has been deprecated

ftConfig

Option to override default tinyMCE config. Currently looks for application.config.#ftConfig#, but this will be replaced with a reference to a specific function local to the calling content type.

Defaults to a popular collection of plugins and settings.

FarCry 5.0 ignores the ftconfig option. The formtool will automatically use the webtop config for tinyMCE if it is populated. More granular changes to the config, for example different configs for different rich text instances or users, can be achieved by coding your own configuration function; see below.

Example Usage

The body field is bound to the aObjectIDs property populating both the Image button drop down and the FarCry button panel display.

dmHTML body property

<cfproperty name="Body" type="longchar" hint="Main body of content." required="no" default="" 
	ftSeq="12" ftWizzardStep="Body" ftFieldset="Body" 
	ftType="richtext" ftLabel="Body" 
	ftImageArrayField="aObjectIDs" ftImageTypename="dmImage" ftImageField="StandardImage" 
	ftTemplateTypeList="dmImage,dmFile,dmNavigation,dmHTML" ftTemplateWebskinPrefixList="insertHTML"
	ftTemplateSnippetWebskinPrefix="insertSnippet">
<cfproperty ftSeq="13" ftwizardStep="Body" ftFieldset="Relationships" name="aObjectIDs" type="array" 
	hint="Holds objects to be displayed at this particular node.  Can be of mixed types." required="no" default="" 
	ftLabel="Associated Media" ftJoin="dmImage,dmFile,dmFlash" bSyncStatus="true">

An alternative example where a dedicated image array is bound.

<cfproperty ftSeq="12" ftfieldset="Content" ftwizardStep="Overview" name="description" type="longchar" 
	hint="Main body of content." required="no" default="" ftType="richtext" ftLabel="Description" 
	ftImageArrayField="aMedia" ftImageTypename="dmImage" ftImageField="StandardImage"
	ftTemplateTypeList="dmImage" ftTemplateWebskinPrefixList="insertHTML"
	ftTemplateSnippetWebskinPrefix="insertSnippet">

<cfproperty ftSeq="13" ftfieldset="Content" ftwizardStep="Overview" name="aMedia" type="array" 
	hint="Associated image assets." required="no" default="" 
	ftLabel="Image Media" ftJoin="dmImage" bSyncStatus="true">

Changing the Default Configuration

Details of tinyMCE configuration options are availble at: http://wiki.moxiecode.com/index.php/TinyMCE:Configuration

webtop configuration

tinyMCE can be configured through the webtop under Config > tinyMCE. Activating the config in the webtop will override the default behaviour of the rich text formtool. You will need to provide a correctly formed configuration Javascript block, as per the tinyMCE documentation.

Sample Alternative Config

theme : "advanced",
plugins : "table,advhr,farcrycontenttemplates,advimage,advlink,preview,zoom,searchreplace,print,contextmenu,paste,directionality,fullscreen",	
theme_advanced_buttons2_add : "separator,farcrycontenttemplates",
theme_advanced_buttons3_add_before : "tablecontrols,separator",			
theme_advanced_buttons3_add : "separator,fullscreen,pasteword,pastetext",				
theme_advanced_toolbar_location : "top",
theme_advanced_toolbar_align : "left",
theme_advanced_path_location : "bottom",
theme_advanced_resize_horizontal : true,
theme_advanced_resizing : true,
extended_valid_elements: "textarea[name|class|cols|rows],script[type],img[style|class|src|border=0|alt|title|hspace|vspace|width|height|align|onmouseover|onmouseout|name]",
remove_linebreaks : false,
relative_urls : false

getConfig function

You can also change the configuration programmatically. This option is preferable in environments where you want to version control the configuration change, or provide more sophisticated configurations such as those that respond to who the user is. The ./formtools/richtext.cfc getConfig() function can be extended to provide your project (or plugin) with customisable configuration options.

See below for a sample extended richtext.cfc You will need to place this in /farcry/projects/yourprojectname/packages/formtools/richtext.cfc

Sample extended richtext getConfig

<cfcomponent extends="farcry.core.packages.formtools.richtext" name="richtext" displayname="Rich Text Editor" hint="Used to liase with longchar type fields"> 

	<cffunction name="getConfig" access="public" output="false" returntype="string" hint="This will return the configuration that will be used by the richtext field">
	
		<cfset var configJS = "" />
		
		<cfsavecontent variable="configJS">
			<cfoutput>			
				theme : "advanced",
				plugins : "table,advhr,farcrycontenttemplates,advimage,advlink,preview,zoom,searchreplace,print,contextmenu,paste,directionality,fullscreen",		<!--- farcryimage --->
				theme_advanced_buttons2_add : "separator,farcrycontenttemplates",
				theme_advanced_buttons3_add_before : "tablecontrols,separator",			
				theme_advanced_buttons3_add : "separator,fullscreen,pasteword,pastetext",				
				theme_advanced_toolbar_location : "top",
				theme_advanced_toolbar_align : "left",
				theme_advanced_path_location : "bottom",
				theme_advanced_resize_horizontal : true,
				theme_advanced_resizing : true,
				extended_valid_elements: "textarea[name|class|cols|rows],script[type],img[style|class|src|border=0|alt|title|hspace|vspace|width|height|align|onmouseover|onmouseout|name]",
				remove_linebreaks : false,
				relative_urls : false
			</cfoutput>
		</cfsavecontent>
		
		<cfreturn configJS />
	</cffunction>

</cfcomponent>

external_link_list_url is populated with the contents of the site overview tree by default.

InsertHTML Templates

The related media content (for example, images, files and html pages) that have been configured for the rich text editor will look for the presence of templates prefixed with "inserthtml" (lowercase is required for case-sensitive operating systems). These are little mini templates that can be used to insert a special chunk of HTML with properties from the relevant content type selected.

By default, if there are no "inserthtml" files inside your webskin folders, then you do not see a dropdown under the tab for the relevant content type. Remember, the "@@displayname:" line determines what the user sees in the dropdown so make this descriptive and relevant.

Sample dmImage template

../webskin/dmImage/inserthtml_imagewithcaption.cfm

<!--- @@displayname: Image and caption --->
<cfoutput>
<p class="featurepic">
<img src="/images/#stObj.imagefile#" alt="#stObj.alt#" /><br />
#stObj.alt#
</p>
</cfoutput>

Sample dmFile template

This example uses the FncFileSize cflib.org function

../webskin/dmFile/inserthtml_fileLinkFull.cfm

<!--- @@displayname: Full file link --->

<!--- include FncFileSize function here; omitted for brevity --->

<cfif application.config.general.fileDownloadDirectLink eq "false">
  <cfset theURL = "#application.url.webroot#/download.cfm?DownloadFile=#stObj.ObjectID#">
<cfelse>
  <cfset theURL = "#application.url.webroot#/files/#stObj.filename#">
</cfif>

<cfoutput>
<a class="file-#LCase(stObj.fileExt)#" href="#variables.theURL#" target="_blank" title="#stObj.description#">#stObj.title# [#UCase(stObj.fileExt)# #FncFileSize(stObj.fileSize)#]</a>
</cfoutput>