From a3058f5536905dc1d178c61844e3f2713b1aed88 Mon Sep 17 00:00:00 2001 From: Marcel Werk Date: Wed, 26 Jun 2024 16:41:50 +0200 Subject: [PATCH] Document user activity events Closes #414 --- docs/php/api/user_activity_events.md | 87 ++++++++ mkdocs.yml | 311 ++++++++++++++------------- 2 files changed, 243 insertions(+), 155 deletions(-) create mode 100644 docs/php/api/user_activity_events.md diff --git a/docs/php/api/user_activity_events.md b/docs/php/api/user_activity_events.md new file mode 100644 index 00000000..6b9a8aa9 --- /dev/null +++ b/docs/php/api/user_activity_events.md @@ -0,0 +1,87 @@ +# User Activity Events + +User activity events provide content from different sources for the list of recent activities. Entries in the last activities consist of a title, optionally a description, the author and the date. + +## Registration of User Activity Events + +To integrate user activity events into your package, you have to register object types for the defintion `com.woltlab.wcf.user.recentActivityEvent` and specify a class that implements the `wcf\system\user\activity\event\IUserActivityEvent` interface: + +```xml + + foo.bar.recentActivityEvent + com.woltlab.wcf.user.recentActivityEvent + wcf\system\user\activity\event\FooUserActivityEvent + +``` + +Specify multiple object types if you want to provide multiple types of user activity events. + +Example of the implementation of the `wcf\system\user\activity\event\IUserActivityEvent` interface: + +```php +handleEvent($event); + } + } + + private function handleEvent(ViewableUserActivityEvent $event): void + { + $foo = new FooObject($event->objectID); + if ($foo === null) { + $event->setIsOrphaned(); + return; + } + + $event->setIsAccessible(); + $event->setTitle(WCF::getLanguage()->getDynamicVariable('foo.bar.recentActivity', [ + 'foo' => $foo, + 'author' => $event->getUserProfile(), + ])); + $event->setDescription( + StringUtil::encodeHTML( + StringUtil::truncate($foo->getPlainTextDescription(), 500) + ), + true + ); + $event->setLink($foo->getLink()); + } +} +``` + +## Creating User Activity Events + +If a relevant object is created, you have to use `UserActivityEventHandler::fireEvent()` which expects the name of the object type, the id of the object and optionally the language id, user id and the date. + +```php +UserActivityEventHandler::getInstance()->fireEvent( + 'foo.bar.recentActivityEvent', + 1, // object id + 2, // language id + 3, // user id + \TIME_NOW // date +); +``` + +## Removing User Activity Events + +To remove user activity events once objects are deleted, you have to use `UserActivityEventHandler::removeEvents()` which also expects the name of the object type and additionally an array with object ids: + +```php +UserActivityEventHandler::getInstance()->removeEvents( + 'foo.bar.recentActivityEvent', + [1, 2] +); +``` diff --git a/mkdocs.yml b/mkdocs.yml index 4ceaab3e..2c6c2567 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -16,174 +16,175 @@ repo_url: https://github.com/WoltLab/docs.woltlab.com/ edit_uri: edit/6.1/docs/ nav: - - "Getting Started": "getting-started.md" + - 'Getting Started': 'getting-started.md' - - "PHP API": - - "Pages": "php/pages.md" - - "Database Objects": "php/database-objects.md" - - "Database Access": "php/database-access.md" - - "Exceptions": "php/exceptions.md" - - "API": - - "ACP Dashboard Boxes": "php/api/acp_dashboard_boxes.md" - - "Caches": - - "Overview": "php/api/caches.md" - - "Persistent Caches": "php/api/caches_persistent-caches.md" - - "Runtime Caches": "php/api/caches_runtime-caches.md" - - "Comments": "php/api/comments.md" - - "Cronjobs": "php/api/cronjobs.md" - - "Events": "php/api/events.md" - - "Form Builder": - - "Overview": "php/api/form_builder/overview.md" - - "Structure": "php/api/form_builder/structure.md" - - "Fields": "php/api/form_builder/form_fields.md" - - "Validation and Data": "php/api/form_builder/validation_data.md" - - "Dependencies": "php/api/form_builder/dependencies.md" - - "Package Installation Plugins": "php/api/package_installation_plugins.md" - - "RPC API": "php/api/rpc_api.md" - - "User Activity Points": "php/api/user_activity_points.md" - - "User Notifications": "php/api/user_notifications.md" - - "RSS Feeds": "php/api/rss_feeds.md" - - "Sitemaps": "php/api/sitemaps.md" - - "Code Style": "php/code-style.md" - - "Apps": "php/apps.md" - - "GDPR": "php/gdpr.md" + - 'PHP API': + - 'Pages': 'php/pages.md' + - 'Database Objects': 'php/database-objects.md' + - 'Database Access': 'php/database-access.md' + - 'Exceptions': 'php/exceptions.md' + - 'API': + - 'ACP Dashboard Boxes': 'php/api/acp_dashboard_boxes.md' + - 'Caches': + - 'Overview': 'php/api/caches.md' + - 'Persistent Caches': 'php/api/caches_persistent-caches.md' + - 'Runtime Caches': 'php/api/caches_runtime-caches.md' + - 'Comments': 'php/api/comments.md' + - 'Cronjobs': 'php/api/cronjobs.md' + - 'Events': 'php/api/events.md' + - 'Form Builder': + - 'Overview': 'php/api/form_builder/overview.md' + - 'Structure': 'php/api/form_builder/structure.md' + - 'Fields': 'php/api/form_builder/form_fields.md' + - 'Validation and Data': 'php/api/form_builder/validation_data.md' + - 'Dependencies': 'php/api/form_builder/dependencies.md' + - 'Package Installation Plugins': 'php/api/package_installation_plugins.md' + - 'RPC API': 'php/api/rpc_api.md' + - 'User Activity Events': 'php/api/user_activity_events.md' + - 'User Activity Points': 'php/api/user_activity_points.md' + - 'User Notifications': 'php/api/user_notifications.md' + - 'RSS Feeds': 'php/api/rss_feeds.md' + - 'Sitemaps': 'php/api/sitemaps.md' + - 'Code Style': 'php/code-style.md' + - 'Apps': 'php/apps.md' + - 'GDPR': 'php/gdpr.md' - - "Languages, Templates & CSS": - - "Languages": "view/languages.md" - - "Templates": "view/templates.md" - - "Template Modifiers": "view/template-modifiers.md" - - "Template Plugins": "view/template-plugins.md" - - "CSS": "view/css.md" + - 'Languages, Templates & CSS': + - 'Languages': 'view/languages.md' + - 'Templates': 'view/templates.md' + - 'Template Modifiers': 'view/template-modifiers.md' + - 'Template Plugins': 'view/template-plugins.md' + - 'CSS': 'view/css.md' - - "TypeScript and JavaScript API": - - "General Usage": "javascript/general-usage.md" - - "TypeScript": "javascript/typescript.md" - - "Components": - - "CKEditor 5": "javascript/components_ckeditor5.md" - - "Confirmation": "javascript/components_confirmation.md" - - "Dialog": "javascript/components_dialog.md" - - "Google Maps": "javascript/components_google_maps.md" - - "Notices": "javascript/components_notice.md" - - "Pagination": "javascript/components_pagination.md" - - "RPC API": "javascript/components/rpc_api.md" - - "New API": - - "Writing a module": "javascript/new-api_writing-a-module.md" - - "Core Functions": "javascript/new-api_core.md" - - "DOM": "javascript/new-api_dom.md" - - "Event Handling": "javascript/new-api_events.md" - - "Ajax": "javascript/new-api_ajax.md" - - "Dialogs": "javascript/new-api_dialogs.md" - - "Browser and Screen Sizes": "javascript/new-api_browser.md" - - "User Interface": "javascript/new-api_ui.md" - - "Legacy API": "javascript/legacy-api.md" - - "Code Snippets": "javascript/code-snippets.md" + - 'TypeScript and JavaScript API': + - 'General Usage': 'javascript/general-usage.md' + - 'TypeScript': 'javascript/typescript.md' + - 'Components': + - 'CKEditor 5': 'javascript/components_ckeditor5.md' + - 'Confirmation': 'javascript/components_confirmation.md' + - 'Dialog': 'javascript/components_dialog.md' + - 'Google Maps': 'javascript/components_google_maps.md' + - 'Notices': 'javascript/components_notice.md' + - 'Pagination': 'javascript/components_pagination.md' + - 'RPC API': 'javascript/components/rpc_api.md' + - 'New API': + - 'Writing a module': 'javascript/new-api_writing-a-module.md' + - 'Core Functions': 'javascript/new-api_core.md' + - 'DOM': 'javascript/new-api_dom.md' + - 'Event Handling': 'javascript/new-api_events.md' + - 'Ajax': 'javascript/new-api_ajax.md' + - 'Dialogs': 'javascript/new-api_dialogs.md' + - 'Browser and Screen Sizes': 'javascript/new-api_browser.md' + - 'User Interface': 'javascript/new-api_ui.md' + - 'Legacy API': 'javascript/legacy-api.md' + - 'Code Snippets': 'javascript/code-snippets.md' - - "Package Components": - - "package.xml": "package/package-xml.md" - - "Bootstrap Scripts": "package/bootstrap-scripts.md" - - "PIPs": - - "Overview": "package/pip.md" - - "aclOption": "package/pip/acl-option.md" - - "acpMenu": "package/pip/acp-menu.md" - - "acpSearchProvider": "package/pip/acp-search-provider.md" - - "acpTemplate": "package/pip/acp-template.md" - - "acpTemplateDelete": "package/pip/acp-template-delete.md" - - "bbcode": "package/pip/bbcode.md" - - "box": "package/pip/box.md" - - "clipboardAction": "package/pip/clipboard-action.md" - - "coreObject": "package/pip/core-object.md" - - "cronjob": "package/pip/cronjob.md" - - "database": "package/pip/database.md" - - "eventListener": "package/pip/event-listener.md" - - "file": "package/pip/file.md" - - "fileDelete": "package/pip/file-delete.md" - - "language": "package/pip/language.md" - - "mediaProvider": "package/pip/media-provider.md" - - "menu": "package/pip/menu.md" - - "menuItem": "package/pip/menu-item.md" - - "objectType": "package/pip/object-type.md" - - "objectTypeDefinition": "package/pip/object-type-definition.md" - - "option": "package/pip/option.md" - - "page": "package/pip/page.md" - - "pip": "package/pip/pip.md" - - "script": "package/pip/script.md" - - "smiley": "package/pip/smiley.md" - - "sql": "package/pip/sql.md" - - "style": "package/pip/style.md" - - "template": "package/pip/template.md" - - "templateDelete": "package/pip/template-delete.md" - - "templateListener": "package/pip/template-listener.md" - - "userGroupOption": "package/pip/user-group-option.md" - - "userMenu": "package/pip/user-menu.md" - - "userNotificationEvent": "package/pip/user-notification-event.md" - - "userOption": "package/pip/user-option.md" - - "userProfileMenu": "package/pip/user-profile-menu.md" - - "ACP Menu Items": "package/acp-menu-items.md" - - "Database PHP API": "package/database-php-api.md" + - 'Package Components': + - 'package.xml': 'package/package-xml.md' + - 'Bootstrap Scripts': 'package/bootstrap-scripts.md' + - 'PIPs': + - 'Overview': 'package/pip.md' + - 'aclOption': 'package/pip/acl-option.md' + - 'acpMenu': 'package/pip/acp-menu.md' + - 'acpSearchProvider': 'package/pip/acp-search-provider.md' + - 'acpTemplate': 'package/pip/acp-template.md' + - 'acpTemplateDelete': 'package/pip/acp-template-delete.md' + - 'bbcode': 'package/pip/bbcode.md' + - 'box': 'package/pip/box.md' + - 'clipboardAction': 'package/pip/clipboard-action.md' + - 'coreObject': 'package/pip/core-object.md' + - 'cronjob': 'package/pip/cronjob.md' + - 'database': 'package/pip/database.md' + - 'eventListener': 'package/pip/event-listener.md' + - 'file': 'package/pip/file.md' + - 'fileDelete': 'package/pip/file-delete.md' + - 'language': 'package/pip/language.md' + - 'mediaProvider': 'package/pip/media-provider.md' + - 'menu': 'package/pip/menu.md' + - 'menuItem': 'package/pip/menu-item.md' + - 'objectType': 'package/pip/object-type.md' + - 'objectTypeDefinition': 'package/pip/object-type-definition.md' + - 'option': 'package/pip/option.md' + - 'page': 'package/pip/page.md' + - 'pip': 'package/pip/pip.md' + - 'script': 'package/pip/script.md' + - 'smiley': 'package/pip/smiley.md' + - 'sql': 'package/pip/sql.md' + - 'style': 'package/pip/style.md' + - 'template': 'package/pip/template.md' + - 'templateDelete': 'package/pip/template-delete.md' + - 'templateListener': 'package/pip/template-listener.md' + - 'userGroupOption': 'package/pip/user-group-option.md' + - 'userMenu': 'package/pip/user-menu.md' + - 'userNotificationEvent': 'package/pip/user-notification-event.md' + - 'userOption': 'package/pip/user-option.md' + - 'userProfileMenu': 'package/pip/user-profile-menu.md' + - 'ACP Menu Items': 'package/acp-menu-items.md' + - 'Database PHP API': 'package/database-php-api.md' - - "Migration": - - "From WoltLab Suite 6.0": - - "PHP API": "migration/wsc60/php.md" - - "Templates": "migration/wsc60/templates.md" - - "Deprecations and Removals": "migration/wsc60/deprecations_removals.md" - - "From WoltLab Suite 5.5": - - "PHP API": "migration/wsc55/php.md" - - "TypeScript and JavaScript": "migration/wsc55/javascript.md" - - "Templates": "migration/wsc55/templates.md" - - "Icons": "migration/wsc55/icons.md" - - "Dialogs": "migration/wsc55/dialogs.md" - - "Third Party Libraries": "migration/wsc55/libraries.md" - - "Deprecations and Removals": "migration/wsc55/deprecations_removals.md" - - "From WoltLab Suite 5.4": - - "PHP API": "migration/wsc54/php.md" - - "TypeScript and JavaScript": "migration/wsc54/javascript.md" - - "Templates": "migration/wsc54/templates.md" - - "Third Party Libraries": "migration/wsc54/libraries.md" - - "Deprecations and Removals": "migration/wsc54/deprecations_removals.md" - - "From WoltLab Suite 5.3": - - "PHP API": "migration/wsc53/php.md" - - "Session Handling and Authentication": "migration/wsc53/session.md" - - "TypeScript and JavaScript": "migration/wsc53/javascript.md" - - "Templates": "migration/wsc53/templates.md" - - "Third Party Libraries": "migration/wsc53/libraries.md" - - "From WoltLab Suite 5.2": - - "PHP API": "migration/wsc52/php.md" - - "Templates and Languages": "migration/wsc52/templates.md" - - "Third Party Libraries": "migration/wsc52/libraries.md" - - "From WoltLab Suite 3.1": - - "PHP API": "migration/wsc31/php.md" - - "From WoltLab Suite 3.0": - - "PHP API": "migration/wsc30/php.md" - - "JavaScript API": "migration/wsc30/javascript.md" - - "Templates": "migration/wsc30/templates.md" - - "CSS": "migration/wsc30/css.md" - - "Package Components": "migration/wsc30/package.md" - - "From WCF 2.1": - - "PHP API": "migration/wcf21/php.md" - - "Templates": "migration/wcf21/templates.md" - - "CSS": "migration/wcf21/css.md" - - "Package Components": "migration/wcf21/package.md" + - 'Migration': + - 'From WoltLab Suite 6.0': + - 'PHP API': 'migration/wsc60/php.md' + - 'Templates': 'migration/wsc60/templates.md' + - 'Deprecations and Removals': 'migration/wsc60/deprecations_removals.md' + - 'From WoltLab Suite 5.5': + - 'PHP API': 'migration/wsc55/php.md' + - 'TypeScript and JavaScript': 'migration/wsc55/javascript.md' + - 'Templates': 'migration/wsc55/templates.md' + - 'Icons': 'migration/wsc55/icons.md' + - 'Dialogs': 'migration/wsc55/dialogs.md' + - 'Third Party Libraries': 'migration/wsc55/libraries.md' + - 'Deprecations and Removals': 'migration/wsc55/deprecations_removals.md' + - 'From WoltLab Suite 5.4': + - 'PHP API': 'migration/wsc54/php.md' + - 'TypeScript and JavaScript': 'migration/wsc54/javascript.md' + - 'Templates': 'migration/wsc54/templates.md' + - 'Third Party Libraries': 'migration/wsc54/libraries.md' + - 'Deprecations and Removals': 'migration/wsc54/deprecations_removals.md' + - 'From WoltLab Suite 5.3': + - 'PHP API': 'migration/wsc53/php.md' + - 'Session Handling and Authentication': 'migration/wsc53/session.md' + - 'TypeScript and JavaScript': 'migration/wsc53/javascript.md' + - 'Templates': 'migration/wsc53/templates.md' + - 'Third Party Libraries': 'migration/wsc53/libraries.md' + - 'From WoltLab Suite 5.2': + - 'PHP API': 'migration/wsc52/php.md' + - 'Templates and Languages': 'migration/wsc52/templates.md' + - 'Third Party Libraries': 'migration/wsc52/libraries.md' + - 'From WoltLab Suite 3.1': + - 'PHP API': 'migration/wsc31/php.md' + - 'From WoltLab Suite 3.0': + - 'PHP API': 'migration/wsc30/php.md' + - 'JavaScript API': 'migration/wsc30/javascript.md' + - 'Templates': 'migration/wsc30/templates.md' + - 'CSS': 'migration/wsc30/css.md' + - 'Package Components': 'migration/wsc30/package.md' + - 'From WCF 2.1': + - 'PHP API': 'migration/wcf21/php.md' + - 'Templates': 'migration/wcf21/templates.md' + - 'CSS': 'migration/wcf21/css.md' + - 'Package Components': 'migration/wcf21/package.md' - - "Tutorials": - - "Tutorial Series": - - "Overview": "tutorial/series/overview.md" - - "Part 1": "tutorial/series/part_1.md" - - "Part 2": "tutorial/series/part_2.md" - - "Part 3": "tutorial/series/part_3.md" - - "Part 4": "tutorial/series/part_4.md" - - "Part 5": "tutorial/series/part_5.md" - - "Part 6": "tutorial/series/part_6.md" + - 'Tutorials': + - 'Tutorial Series': + - 'Overview': 'tutorial/series/overview.md' + - 'Part 1': 'tutorial/series/part_1.md' + - 'Part 2': 'tutorial/series/part_2.md' + - 'Part 3': 'tutorial/series/part_3.md' + - 'Part 4': 'tutorial/series/part_4.md' + - 'Part 5': 'tutorial/series/part_5.md' + - 'Part 6': 'tutorial/series/part_6.md' plugins: - git-revision-date - search - macros: - j2_comment_start_string: "{jinja#" - j2_variable_start_string: "{jinja{" + j2_comment_start_string: '{jinja#' + j2_variable_start_string: '{jinja{' markdown_extensions: - toc: - permalink: "#" + permalink: '#' toc_depth: 4 - admonition - abbr @@ -196,7 +197,7 @@ markdown_extensions: startinline: true - pymdownx.superfences - pymdownx.snippets: - base_path: "snippets/" + base_path: 'snippets/' extra_css: - stylesheets/extra.css -- 2.20.1