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.

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.

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.

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.

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.

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.

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

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

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.

moveToPublic(objectid, typename, stObject,stMetadata)

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

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.

Result on success:

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

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

1. Create a dmFileView permission
2. 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

1. Extend farBarnacle into your project
2. Override the ftJoin attribute on the referenceid property to include "dmFile"
3. Update the COAPI metadata, or use updateapp
4. Edit the "View" permission, and add File to the list of types that it applies to
5. Extend dmFile into your project
6. 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" />
7. 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.