Composr Supplementary: Using Form Handlers

Written by Patrick Schmalstig

Table of contents

  1. Composr Supplementary: Using Form Handlers
    1. Form Handler Hooks
      1. Hooks: join
      2. Hooks: profile_edit
      3. Hooks: catalogue_entry

Form handlers are hooks which can be used to provide additional post-processing of data from member registrations / profiles and catalogue entries. For example, you can use a form handler to transmit form data to an external system, such as a Customer Relation Management (CRM) software. Form handlers operate on their own and do not control the relevant action being performed. In other words, form handlers cannot manipulate form data for Composr itself nor prevent forms from being submitted (they are for 'post' processing). They can, however, manipulate data before sending it out to an external system or webhook (this is often necessary to conform to the data structures of external systems).

Composr has support for building custom form handlers out of the box. While Composr does not bundle any form handlers by default, developers can make and release their own handlers through non-bundled addons.

Form Handler Hooks

Form handlers are managed through special hooks located under sources_custom/hooks/form_handlers/. There are currently three types of hooks available: join hooks (when a member registers), profile_edit hooks (when a member edits their profile), and catalogue_entry hooks (when catalogue entries get added, edited, or deleted; also includes custom fields used in other content types).

Hooks: join

These hooks are triggered when a member registers an account on your website (note that these are not triggered when a member is added manually; these are explicitly run on registration). These hooks support one method: run. The run method will take the following parameters:
  1. MEMBER $member_id
    The member ID assigned to the new member.
  2. ID_TEXT $username
    The username chosen by the member.
  3. string $email_address
    The provided e-mail address of the member.
  4. ?int $dob_day, $dob_month, and $dob_year
    The member's provided birthday. Relevant values will be null if not specified.
  5. array $actual_custom_fields
    A map of custom profile fields filled in by the member, the key being the custom field ID and the value being the specified value by the member.
  6. string $timezone
    The time zone of the member.
  7. BINARY $validated
    Whether the member is validated (1) or not (0).
  8. ID_TEXT $language
    The language code of the member.
  9. BINARY $allow_emails
    Whether the member is allowing e-mails from other members (1) or not (0).
  10. BINARY $allow_emails_from_staff
    Whether the member is allowing mass e-mails from staff (1) or not (0).
  11. IP $ip_address
    The IP address of the member.

Hooks: profile_edit

These hooks are triggered when a member edits their profile (note these are not triggered when a member is manually edited; these are explicitly triggered when a member or staff edits their profile from the profile page). These hooks support one method: run. The run method will take the following parameters:
  1. MEMBER $member_id_of
    The ID of the member that was edited.
  2. ?ID_TEXT $username
    The new username of the member (null: it is not being changed).
  3. ?string $email_address
    The new e-mail address of the member (null: it is not being changed).
  4. ?int $dob_day, $dob_month, and $dob_year
    The member's provided birthday. Null values should be treated as literal null, that-is the member removed it from their profile.
  5. array $actual_custom_fields
    A map of custom profile fields filled in by the member, the key being the custom field ID and the value being the specified value by the member. Custom profile fields which are not to be changed from their original value will not be included in the array.
  6. ?string $timezone
    The time zone of the member (null: it is not to be changed).
  7. ?ID_TEXT $language
    The language code of the member (null or STRING_MAGIC_NULL: it is not to be changed).
  8. ?BINARY $allow_emails
    Whether the member is allowing e-mails from other members (1) or not (0) (null or STRING_MAGIC_NULL: it is not to be changed).
  9. ?BINARY $allow_emails_from_staff
    Whether the member is allowing mass e-mails from staff (1) or not (0) (null or STRING_MAGIC_NULL: it is not to be changed).
  10. BINARY $validated
    Whether the member is validated (1) or not (0).

Hooks: catalogue_entry

These hooks are triggered when a catalogue entry is added, edited, or deleted. They are also triggered when a content type supporting custom fields is added, edited, or deleted (and the relevant custom fields are passed through). These hooks support three methods: add, edit, and delete, called when the relevant action is performed on an entry.

TODO: WIP


Feedback

Please rate this tutorial:

Have a suggestion? Report an issue on the tracker.