Collaboration handler

This is a Stub article. Help the eZ Publish community by expanding it!

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:

[HandlerSettings]
 Extensions[]=extensionname
 Active[]=my

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

Key

Type

Default

Usage

use-messages

boolean

false

When true the collaboration handler will support adding messages to the collaboration item.

type-class-list

array

empty array

Doesn't seem to be used anywhere.

notification-collection-handling

integer

1

EZ_COLLABORATION_NOTIFICATION_COLLECTION_ONE_FOR_ALL (1)
EZ_COLLABORATION_NOTIFICATION_COLLECTION_PER_USER (2), currently not implemented in eZCollaborationItemHandler::handleCollaborationEvent()
EZ_COLLABORATION_NOTIFICATION_COLLECTION_PER_PARTICIPATION_ROLE (3)

notification-types

boolean or array

false

True if the handler supports notifications but does not have any subnotifications, false when notifications are not supported, or an array containing associative arrays with a value and name entry. All available notifications and subnotifications will be listed in the notification/settings view by the collaboration notification handler.

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.