From c4350d400510ce476b4b21ad51d7306e04c05684 Mon Sep 17 00:00:00 2001 From: Matthias Schmidt Date: Thu, 3 Jun 2021 09:24:12 +0200 Subject: [PATCH] Add part 6 of tutorial series --- docs/tutorial/series/overview.md | 1 + docs/tutorial/series/part_6.md | 140 +++++++++++++++++++++++++++++++ mkdocs.yml | 1 + 3 files changed, 142 insertions(+) create mode 100644 docs/tutorial/series/part_6.md diff --git a/docs/tutorial/series/overview.md b/docs/tutorial/series/overview.md index 4f7be8bc..f8d5138c 100644 --- a/docs/tutorial/series/overview.md +++ b/docs/tutorial/series/overview.md @@ -11,3 +11,4 @@ Note that in the context of this example, not every added feature might make per - [Part 3: Person Page and Comments](part_3.md) - [Part 4: Box and Box Conditions](part_4.md) - [Part 5: Person Information](part_5.md) +- [Part 6: Activity Points and Activity Events](part_6.md) diff --git a/docs/tutorial/series/part_6.md b/docs/tutorial/series/part_6.md new file mode 100644 index 00000000..13da5faa --- /dev/null +++ b/docs/tutorial/series/part_6.md @@ -0,0 +1,140 @@ +# Part 6: Activity Points and Activity Events + +In this part of our tutorial series, we use the person information added in the [previous part](part_5.md) to award activity points to users adding new pieces of information and to also create activity events for these pieces of information. + + +## Package Functionality + +In addition to the existing functions from [part 5](part_5.md), the package will provide the following functionality after this part of the tutorial: + +- Users are awarded activity points for adding new pieces of information for people. +- If users add new pieces of information for people, activity events are added which are then shown in the list of recent activities. + + +## Used Components + +In addition to the components used in previous parts, we will use the [user activity points API](../../php/api/user_activity_points.md) and the user activity events API. + + +## Package Structure + +The package will have the following file structure _excluding_ unchanged files from previous parts: + +``` +├── files +│ └── lib +│ ├── data +│ │ └── person +│ │ ├── PersonAction.class.php +│ │ └── information +│ │ ├── PersonInformation.class.php +│ │ └── PersonInformationAction.class.php +│ └── system +│ ├── user +│ │ └── activity +│ │ └── event +│ │ └── PersonInformationUserActivityEvent.class.php +│ └── worker +│ ├── PersonInformationRebuildDataWorker.class.php +│ └── PersonRebuildDataWorker.class.php +├── eventListener.xml +├── language +│ ├── de.xml +│ └── en.xml +└── objectType.xml +``` + +For all changes, please refer to the [source code on GitHub]({jinja{ config.repo_url }}tree/{jinja{ config.edit_uri.split("/")[1] }}/snippets/tutorial/tutorial-series/part-6). + + +## User Activity Points + +The first step to support activity points is to register an object type for the `com.woltlab.wcf.user.activityPointEvent` object type definition for created person information and specify the default number of points awarded per piece of information: + +{jinja{ codebox( + language="xml", + title="objectType.xml", + contents=""" + + com.woltlab.wcf.people.information + com.woltlab.wcf.user.activityPointEvent + 2 + + """ +) }} + +Additionally, the phrase `wcf.user.activityPoint.objectType.com.woltlab.wcf.people.information` (in general: `wcf.user.activityPoint.objectType.{objectType}`) has to be added. + +The activity points are awarded when new pieces are created via `PersonInformation::create()` using `UserActivityPointHandler::fireEvent()` and removed in `PersonInformation::create()` via `UserActivityPointHandler::removeEvents()` if pieces of information are deleted. + +Lastly, we have to add two components for updating data: +First, we register a new rebuild data worker + +{jinja{ codebox( +language="xml", +title="objectType.xml", +contents=""" + + com.woltlab.wcf.people.information + com.woltlab.wcf.rebuildData + wcf\system\worker\PersonInformationRebuildDataWorker + +""" +) }} + +{jinja{ codebox( + title="files/lib/system/worker/PersonInformationRebuildDataWorker.class.php", + language="php", + filepath="tutorial/tutorial-series/part-6/files/lib/system/worker/PersonInformationRebuildDataWorker.class.php" +) }} + +which updates the number of instances for which any user received person information activity points. +(This data worker also requires the phrases `wcf.acp.rebuildData.com.woltlab.wcf.people.information` and `wcf.acp.rebuildData.com.woltlab.wcf.people.information.description`). + +Second, we add an event listener for `UserActivityPointItemsRebuildDataWorker` to update the total user activity points awarded for person information: + +{jinja{ codebox( + language="xml", + title="eventListener.xml", + contents=""" + + wcf\system\worker\\UserActivityPointItemsRebuildDataWorker + execute + wcf\system\event\listener\PersonUserActivityPointItemsRebuildDataWorkerListener + admin + +""" +) }} + +{jinja{ codebox( + title="files/lib/system/event/listener/PersonUserActivityPointItemsRebuildDataWorkerListener.class.php", + language="php", + filepath="tutorial/tutorial-series/part-6/files/lib/system/event/listener/PersonUserActivityPointItemsRebuildDataWorkerListener.class.php" +) }} + + +## User Activity Events + +To support user activity events, an object type for `com.woltlab.wcf.user.recentActivityEvent` has to be registered with a class implementing `wcf\system\user\activity\event\IUserActivityEvent`: + +{jinja{ codebox( +language="xml", +title="objectType.xml", +contents=""" + + com.woltlab.wcf.people.information + com.woltlab.wcf.user.recentActivityEvent + wcf\system\\user\activity\event\PersonInformationUserActivityEvent + +""" +) }} + +{jinja{ codebox( + title="files/lib/system/user/activity/event/PersonInformationUserActivityEvent.class.php", + language="php", + filepath="tutorial/tutorial-series/part-6/files/lib/system/user/activity/event/PersonInformationUserActivityEvent.class.php" +) }} + +`PersonInformationUserActivityEvent::prepare()` must check for all events whether the associated piece of information still exists and if it is the case, mark the event as accessible via the `setIsAccessible()` method, set the title of the activity event via `setTitle()`, and set a description of the event via `setDescription()` for which we use the newly added `PersonInformation::getFormattedExcerpt()` method. + +Lastly, we have to add the phrase `wcf.user.recentActivity.com.woltlab.wcf.people.information`, which is shown in the list of activity events as the type of activity event. diff --git a/mkdocs.yml b/mkdocs.yml index 0024425e..2b35eeba 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -137,6 +137,7 @@ nav: - '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 -- 2.20.1