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 currently in development. This document is an attempt to layout all the changes for review, and eventually as documentation.
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 |