Event Handlers / Callbacks

The Speck API includes a number of events for which you can write handler methods or callbacks in your content and property types.

Most of these callbacks get invoked at significant events in the lifecycle of a content object. These events are contentPut, contentGet, promote and delete. Writing a method that gets invoked when one of these events occurs is simple - just create a new method definition using the cf_spHandler tag and give the method name one of contentGet, contentPut, promote or delete. The content structure representing the current content item will be available within the method, as per most other methods.

The contentGet method is invoked after the content has been retrieved from the database and allows you to modify the data prior to returning it from cf_spContentGet.

The other methods, contentPut, promote and delete are invoked before the content is put, promoted or deleted. In the case of contentPut, modifications to the values in the content structure will be stored in the database. Some of the built-in content types have contentPut methods that modify properties before saving the content item to the database. The image content type included with Speck includes a contentPut method that is a good example. It gets the dimensions of an uploaded image and then sets the value of related width and height properties. These values are saved in the database and can then be used in methods that display the content.

There is also one special callback that is invoked while an application is refreshing. Funnily enough, it's called refresh. It's special because it only works for content types and it's not called for a particular content item. The refresh method is called after content types have been loaded, but before the application context is available in request.speck. The information normally available in request.speck can be referenced from a context structure, so you can do things like determine the dbtype using context.dbtype. You can use this method to do all sorts of nasty things like modify the database as an application is refreshing. For example, you could create some database indexes that Speck can't create for you automatically.