Reference Omeka Classic plugin

Developer Reference

Admin pages

Every page is in the admin (/admin/…); the same addresses on the public site answer Not found.

Address Page ACL resource and privilege
announcements The inbox (?filter=unread, all or archived; &page=) Announcements_Inbox, index
announcements/message/:id A message (:id is the inbox message, not the announcement) Announcements_Inbox, show
announcements/all All announcements (?status=active, expired or recalled) Announcements_Manage, browse
announcements/new New announcement Announcements_Manage, add
announcements/:id An announcement, its recipients and delivery stats Announcements_Manage, show

These take a POST with Omeka's session token (csrf_token) and redirect:

Address Does
announcements/message/:id/mark-read, …/mark-unread, …/archive, …/delete Change the user's own copy
announcements/inbox/mark-all-read, announcements/inbox/archive-all The same for the whole inbox
announcements/inbox/email-preference receive_emails=1 or 0
announcements/:id/recall Recall (Announcements_Manage, recall)
announcements/cleanup Run cleanup (Announcements_Manage, cleanup)

The inbox buttons accept return (unread, all, archived or message) and return_page to come back to the same place.

Permissions

The plugin adds two ACL resources in define_acl:

$acl->addResource('Announcements_Inbox');
$acl->allow(['super', 'admin', 'contributor', 'researcher'], 'Announcements_Inbox');
$acl->addResource('Announcements_Manage');
$acl->allow(['super', 'admin'], 'Announcements_Manage');

Omeka checks them before each action (the resource is named after the controller, the privilege after the action), so a refused user gets the Forbidden page. The settings use Omeka's Plugins resource, which Admins are denied. A plugin that wants another role to send announcements can allow it on Announcements_Manage in its own define_acl.

Hooks used

Hook or filter For
admin_header_bottom The bell, with the unread count, and the hourly automatic cleanup
admin_head The plugin's stylesheet on every admin page (for the bell)
admin_dashboard The dashboard panel (placed first among the panels by its stylesheet)
admin_navigation_main The Announcements menu entry
define_acl, define_routes Permissions and the addresses above
config_form, config The settings
before_delete_user Forgets a deleted user's email choice (their inbox stays in the stats)
html_purifier_config_setup (applied) Other plugins' HTML Purifier definitions, such as Block Suite's HTML5 elements, apply to announcement bodies too

Audit Trail

With the Audit Trail plugin installed, Announcements logs to it through the audit_trail_log hook (a no-op without it):

Action When
announcement.send An announcement is sent (data: everyone, roles, users, recipients, email, expiry, attachment name)
announcement.recall An announcement is recalled
announcement.cleanup Someone runs the cleanup (the automatic cleanup is not logged)
announcement_settings.save The settings are saved

Database

Tables, with the site's table prefix:

Table Holds
announcements Title, body (cleaned HTML), attachment (storage path, original name, size, type), link, target_all, sender, created_at, expires_at, recall (recalled, recalled_by, recalled_at), send_email, emails_sent, emailed_at
announcement_target_roles The roles chosen
announcement_target_users The users chosen by name
user_announcements One row per recipient: is_read, is_archived, is_deleted and their times
announcement_preferences Users who changed their email choice (receive_emails)

Every time is stored in UTC from PHP's clock (Announcements\Service\Clock), never MySQL's NOW(), and shown in PHP's time zone with Omeka's date format.

Options: announcements_cleanup_action (archive or delete), announcements_cleanup_days and announcements_cleanup_last_run (UTC).

Attachments

An attachment is stored through Omeka's file storage (Zend_Registry::get('storage')) at announcements/<random>-<cleaned name>: in files/announcements/ on a site that keeps files on its own disk, or in the cloud storage of a site that uses a storage adapter (such as Backblaze B2). The link is the storage's address for it. The plugin never reads a stored file back, so it works with adapters that can only store, delete and give addresses. Uninstalling deletes the files.

Accepted: pdf, doc, docx, xls, xlsx, ppt, pptx, odt, ods, odp, rtf, txt, csv, jpg, jpeg, png, gif, webp, zip, and the file's detected type must fit its extension. The largest size is the smaller of PHP's upload_max_filesize and post_max_size.

Email

Announcements_Job_SendEmails (in jobs.php) runs through Omeka's long-running job dispatcher with the options announcement_id and inbox_url (the inbox's absolute address, taken in the web request). It sends one Zend_Mail per recipient through Omeka's mail transport, from the administrator_email option with the site title as the name, with an Auto-Submitted: auto-generated header, and records the count in emails_sent. It stops if the announcement is recalled.

Log in for Support