Collaboration handler

Collaboration extensions

The eZ publish kernel needs to know that your extension contains collaboration handlers. If you want to create a collaboration handler my in the extension extensionname, then put these settings in In extension/ extensionname /settings/workflow.ini.append:

The collaboration handler class should be called MyCollaborationHandler. You have to place this class in the file extension/extensionname/collaboration/my/mycollaborationhandler.php.

Note that in the eZ publish kernel, collaboration handlers are placed at another location: kernel/classes/collaborationhandlers.

Collaboration handler class

The collaboration handler class should extend eZCollaborationItemHandler and implement some specific abstract functions.

Constructor

In the constructor, you should initialize your handler by calling $this->eZCollaborationItemHandler(). The arguments you need to pass are:

1. the unique identifier of your collaboration handler, in our example this was "my"
2. a user-readable name for our handler (don't forget to pass it through the ezi18n function to make the name translatable)
3. an associative array with optional parameters, the keys used by the kernel are listed in the next table

The handleCustomAction function

This function is executed when you post a form to the collaboration/action view. Two arguments are passed:

1. $module, by reference, you can use this for example to redirect to another module/view
2. $collaborationItem, by reference, so you can modify the current collaboration item according the executed action

You can use $this->isCustomAction( $actionName ) to see if a specific action is triggered by a post variable of the form CollaborationAction_$actionName.

$this->hasCustomInput( $name ) and $this->customInput( $name ) can be used to check the existence of and retrieve custom input post variables of the form Collaboration_$name.

The notificationParticipantTemplate function

When notification collection handling is set to EZ_COLLABORATION_NOTIFICATION_COLLECTION_PER_PARTICIPATION_ROLE then this function is used to return the name of the template to use by the notification system. One argument $participantRole is passed, containing the role id of the participant. The template will be fetched from the directory notification/handler/ezcollaboration/view/my/. The default implementation uses participant.tpl. This template will also be used as a fallback when you return a boolean false from your custom implementation.

You can use your own method of handling collaboration notifications by reimplementing the function handleCollaborationEvent.

Notifications

You can make the system send out notifications for a specific collaboration item by calling the createNotificationEvent function of the collaboration item:

$collaborationItem->createNotificationEvent();

You can pass an optional parameter to the function to specify a notification subtype (if your handler is configured to support this).

When the notification cronjob runs, the collaboration notification handler will pick up each collaboration notification event created this way, and will use the right templates (according to the type and optionally subtype of a specific collaboration item) to send out e-mails.

Templates

The templates specific to your collaboration handler are placed at the following locations:

• collaboration/handlers/view/full/my.tpl, used by the collaboration_view_gui template function (replace "full" with any custom view mode you'd like to use)
• collaboration/handlers/icon/small/my.tpl, used by the collaboration_icon template function (replace "small" with any custom view mode you'd like to use)
• notification/handler/ezcollaboration/view/my/... used for the notifications
• notification/handler/ezcollaboration/view/my_[notification_subtype]/... used for notifications when more granular subnotifications are used

Troubleshooting

If eZ Publish doesn't seem to want to load your collaboration handler, then you might want to check out some useful tips to get it to work at the Troubleshooting extensions page.