Event Hooks

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

  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 (smile). 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.