Overview

Several kinds of features and functionality need to hook into certain events. Examples of an existing hook is the types.afterSave function which allows a developer to run their own code in the event of a save, without mucking about with setData.

The following extra hooks are available to developers.

TYPES Hooks

Hooks for content type events.

onDelete(typename, stObject)

This function is called after the delete() function is finished. Is function is called AFTER the object has been removed from the database.

By default it will call the onDelete function (where defined) on the formtool of each property.

Argument	Notes
typename	Content type
stObject	Properties of deleted object

onStatusChange(typename, stProperties, newstatus, previousstatus)

This function is called when an object's status is changed using setData, but ONLY IF NO STATUS SPECIFIC TRIGGER IS DEFINED.

This is the only status change trigger included in core types. By default it looks for and calls the status specific trigger or onStatusChange function on each property formtool.

Argument	Notes
typename	The type of the updated object.
stProperties	The properties of the updated object
newstatus	The new status
previousstatus	The old status

onApproved / onDraft / onPending(typename, stProperties, previousstatus)

This function is called on an object when it's status is changed with setData.

Core does not include these functions by default. If a status specific trigger is added, onStatusChange does not get called for that status.

Argument	Notes
typename	The type of the updated object.
stProperties	The properties of the updated object
newstatus	The new status

onSecurityChange(changetype, objectid, typename, stObject, farRoleID, farPermissionID, oldRight, newRight)

This function is called on an object when the security on it object is changed. This includes changes to that particular object's permission (e.g. denying anonymous access to a branch of the site), and changes to a permission for that object's type (granting edit permission for news).

The default onSecurityChange function calls the onSecurityChange function for each property formtool if one has been defined.

Argument	Notes
changetype	"type" for a type permission or "object" for an object permission
objectid	This and typename OR stObject are required. The object that was changed.
typename	This and objectid OR stObject are required. The object that was changed.
stObject	This OR objectid and typename are required. The object that was changed.
farRoleID	The role that was updated.
farPermissionID	The permission that was updated.
oldright	The old permission. 0 (deny) or 1 (grant) for type permissions. -1 (deny), 0 (inherit), or 1 (grant) for object permissions.
newright	The new permission. 0 (deny) or 1 (grant) for type permissions. -1 (deny), 0 (inherit), or 1 (grant) for object permissions.

Triggers	Notes
farBarnacle.updateRight()	currently only used by Manage Permissions page
farPermission.setData()	when a permission is changed from a barnacle permission to an ordinary permission
farPermission.delete()	when a barnacle permission is deleted
farRole.updatePermission()	when a type permission is added or removed from a role, currently only used by scaffold
farRole.delete()	this is probably going to be buggy
farRole.setData()	when a type permission is added or removed from a role

FORMTOOL Hooks

onDelete(typename, stObject, stMetadata)

This function is called by types.onDelete() after an object is deleted.

By default only the file and image formtools use this hook. In both cases the relevant file is deleted from the file system.

Argument	Notes
typename	The type of the updated object.
stObject	The properties of the updated object
stMetadata	The property metadata

onStatusChange(typename, stObject, newstatus, previousstatus, stMetadata)

This function is called by types.onStatusChange() after an object's status is changed. NOTE: this function is ONLY used if a status specific function is not defined.

By default no formtools use this hook.

Argument	Notes
typename	The type of the updated object.
stObject	The properties of the updated object
newstatus	The new object status
previousstatus	The old object status
stMetadata	The property metadata

onApproved / onDraft / onPending(typename, stObject, stMetadata, previousstatus)

This function is called by types.onStatusChange() after an object's status is changed. NOTE: these status specific hooks override onStatusChange.

By default the file formtool uses onApproved and onDraft to move files between the secure and public file directories as appropriate for the security of the object and metadata of the property. No other formtools use these hooks.

To be clear about when a file stays in the secure directory:

view for the content type is denied for anonymous
view for the object is denied for anonymous
ftSecure is true

Argument	Notes
typename	The type of the updated object.
stObject	The properties of the updated object
previousstatus	The old object status
stMetadata	The property metadata

onSecurityChange(changetype, objectid, typename, farRoleID, stObject, farPermissionID, oldRight, newRight, stMetadata)

This function is called by types.onSecurityChange() after an object's permissions have changed.

By default only the file formtool uses this hook, to move files between the secure and public file directories depending on anonymous access and the property metadata.

To be clear about when a file stays in the secure directory:

view for the content type is denied for anonymous
view for the object is denied for anonymous
ftSecure is true

Argument	Notes
changetype	"type" for a type permission or "object" for an object permission
objectid	This and typename OR stObject are required. The object that was changed.
typename	This and objectid OR stObject are required. The object that was changed.
stObject	This OR objectid and typename are required. The object that was changed.
farRoleID	The role that was updated.
farPermissionID	The permission that was updated.
oldright	The old permission. 0 (deny) or 1 (grant) for type permissions. -1 (deny), 0 (inherit), or 1 (grant) for object permissions.
newright	The new permission. 0 (deny) or 1 (grant) for type permissions. -1 (deny), 0 (inherit), or 1 (grant) for object permissions.
stMetadata	The property metadata

Related Functions

Some extra functions were added to the file formtool. These make it easier to customise file behaviour.

moveToSecure(objectid, typename, stObject,stMetadata)

Moves the file to the secure directory. This function is used by onDraft and onSecurityChange.

Argument	Notes
objectid	This and typename OR stObject are required. The object properties.
typename	This and objectid OR stObject are required. The object properties.
stObject	This OR objectid and typename are required. The object properties.
stMetadata	The property metadata.

moveToPublic(objectid, typename, stObject,stMetadata)

Moves the file to the public directory. This function is used by onApproved and onSecurityChange.

Argument	Notes
objectid	This and typename OR stObject are required. The object properties.
typename	This and objectid OR stObject are required. The object properties.
stObject	This OR objectid and typename are required. The object properties.
stMetadata	The property metadata.

getFileLocation(objectid, typename, stObject, stMetadata)

Returns a struct containing information about the file defined by the property. If stMetadata is not defined the first file property is used. This function is used by moveToSecure, moveToPublic, and download.cfm.

Argument	Notes
objectid	This and typename OR stObject are required. The object properties.
typename	This and objectid OR stObject are required. The object properties.
stObject	This OR objectid and typename are required. The object properties.
stMetadata	The property metadata.

Result on success:

Key	Notes
relativepath	the field value
filename	file and extension, no directory information
type	"redirect" (use cflocation) or "stream" (use cfcontent)
path	the path to use in the redirect or stream
fullpath	always the full system path of the file (mostly used by moveTo functions)
mimetype	file type

Result on failure (property could not be determined, permission was denied, file could not be found):

Key	Notes
message	Error message

Default Hook Cascade

Examples

Hopefully this section will give you some ideas of what these changes are are good for and how to use them.

Case 1: Secure the entire file library to Member users

Create a dmFileView permission
Assign the dmFileView permission to Member

Once this is done, future uploaded files should be uploaded to the secure file directory and automatically restricting access to Member users. The action of creating the dmFileView permission should also prompt FarCry to move all public files to the secure file directory.

Case 2: Secure some files to Member users

Extend farBarnacle into your project
Override the ftJoin attribute on the referenceid property to include "dmFile"
Update the COAPI metadata, or use updateapp
Edit the "View" permission, and add File to the list of types that it applies to
Extend dmFile into your project
Add a property: <cfproperty ftSeq="40" ftFieldset="Access" name="viewPermission" type="boolean" hint="Dummy field to control view permissions" required="no" ftLabel="Access" ftType="permissions" ftPermissions="View" bSave="false" />
Deploy the new property from the Admin webtop tab

Let's review what is happening here:

In steps 1-3 we are setting up the security system to allow you to add permissions to specific file objects - object permissions.
In step 4 we have added the View permission to dmFile. The risk with doing this is that now NO-ONE has permission to view any file - not even the SysAdmin users. Typically this is something you will at the start of a project, not after users have already been uploading files.
Steps 5-7 add a permission controller to the file edit form. You may have already seen the Manage Permissions page that allow you to restrict access to parts of the site tree. This page is available for every object that has object permissions set up. But to access it for a file you need to 1) Go to the file overview page 2) Click on the Miscellaneous pane 3) Click Manage Permissions 4) Choose the role you want to change 5) Change the permission 6) Click Save. By adding this dummy property with the permissions formtool, you provide users with a way to manage access to the file like they edit any other property.

Unfortunately there isn't any way to automatically grant a permission to a role, like SysAdmin, for new objects. Eventually we will add a ftDefaultRoles attribute (or something . Until then there are the following approaches:

Add a afterSave function that adds these permissions
Train your users to always select SysAdmin and SiteAdmin as well as the user roles they need to specify
Give your SysAdmin users every role

Case 3: Open the entire file library

This is the default setup of core. All draft files are stored in the secure file directory, and are moved to the public directory on approval.