Skip to content

Commit c4350d4

Browse files
author
Matthias Schmidt
committed
Add part 6 of tutorial series
1 parent 9ffa897 commit c4350d4

File tree

3 files changed

+142
-0
lines changed

3 files changed

+142
-0
lines changed

‎docs/tutorial/series/overview.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,3 +11,4 @@ Note that in the context of this example, not every added feature might make per
1111
- [Part 3: Person Page and Comments](part_3.md)
1212
- [Part 4: Box and Box Conditions](part_4.md)
1313
- [Part 5: Person Information](part_5.md)
14+
- [Part 6: Activity Points and Activity Events](part_6.md)

‎docs/tutorial/series/part_6.md‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
# Part 6: Activity Points and Activity Events
2+
3+
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.
4+
5+
6+
## Package Functionality
7+
8+
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:
9+
10+
- Users are awarded activity points for adding new pieces of information for people.
11+
- If users add new pieces of information for people, activity events are added which are then shown in the list of recent activities.
12+
13+
14+
## Used Components
15+
16+
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.
17+
18+
19+
## Package Structure
20+
21+
The package will have the following file structure _excluding_ unchanged files from previous parts:
22+
23+
```
24+
├── files
25+
│ └── lib
26+
│ ├── data
27+
│ │ └── person
28+
│ │ ├── PersonAction.class.php
29+
│ │ └── information
30+
│ │ ├── PersonInformation.class.php
31+
│ │ └── PersonInformationAction.class.php
32+
│ └── system
33+
│ ├── user
34+
│ │ └── activity
35+
│ │ └── event
36+
│ │ └── PersonInformationUserActivityEvent.class.php
37+
│ └── worker
38+
│ ├── PersonInformationRebuildDataWorker.class.php
39+
│ └── PersonRebuildDataWorker.class.php
40+
├── eventListener.xml
41+
├── language
42+
│ ├── de.xml
43+
│ └── en.xml
44+
└── objectType.xml
45+
```
46+
47+
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).
48+
49+
50+
## User Activity Points
51+
52+
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:
53+
54+
{jinja{ codebox(
55+
language="xml",
56+
title="objectType.xml",
57+
contents="""
58+
<type>
59+
<name>com.woltlab.wcf.people.information</name>
60+
<definitionname>com.woltlab.wcf.user.activityPointEvent</definitionname>
61+
<points>2</points>
62+
</type>
63+
"""
64+
) }}
65+
66+
Additionally, the phrase `wcf.user.activityPoint.objectType.com.woltlab.wcf.people.information` (in general: `wcf.user.activityPoint.objectType.{objectType}`) has to be added.
67+
68+
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.
69+
70+
Lastly, we have to add two components for updating data:
71+
First, we register a new rebuild data worker
72+
73+
{jinja{ codebox(
74+
language="xml",
75+
title="objectType.xml",
76+
contents="""
77+
<type>
78+
<name>com.woltlab.wcf.people.information</name>
79+
<definitionname>com.woltlab.wcf.rebuildData</definitionname>
80+
<classname>wcf\system\worker\PersonInformationRebuildDataWorker</classname>
81+
</type>
82+
"""
83+
) }}
84+
85+
{jinja{ codebox(
86+
title="files/lib/system/worker/PersonInformationRebuildDataWorker.class.php",
87+
language="php",
88+
filepath="tutorial/tutorial-series/part-6/files/lib/system/worker/PersonInformationRebuildDataWorker.class.php"
89+
) }}
90+
91+
which updates the number of instances for which any user received person information activity points.
92+
(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`).
93+
94+
Second, we add an event listener for `UserActivityPointItemsRebuildDataWorker` to update the total user activity points awarded for person information:
95+
96+
{jinja{ codebox(
97+
language="xml",
98+
title="eventListener.xml",
99+
contents="""
100+
<eventlistener name=\"execute@wcf\system\worker\\UserActivityPointItemsRebuildDataWorker\">
101+
<eventclassname>wcf\system\worker\\UserActivityPointItemsRebuildDataWorker</eventclassname>
102+
<eventname>execute</eventname>
103+
<listenerclassname>wcf\system\event\listener\PersonUserActivityPointItemsRebuildDataWorkerListener</listenerclassname>
104+
<environment>admin</environment>
105+
</eventlistener>
106+
"""
107+
) }}
108+
109+
{jinja{ codebox(
110+
title="files/lib/system/event/listener/PersonUserActivityPointItemsRebuildDataWorkerListener.class.php",
111+
language="php",
112+
filepath="tutorial/tutorial-series/part-6/files/lib/system/event/listener/PersonUserActivityPointItemsRebuildDataWorkerListener.class.php"
113+
) }}
114+
115+
116+
## User Activity Events
117+
118+
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`:
119+
120+
{jinja{ codebox(
121+
language="xml",
122+
title="objectType.xml",
123+
contents="""
124+
<type>
125+
<name>com.woltlab.wcf.people.information</name>
126+
<definitionname>com.woltlab.wcf.user.recentActivityEvent</definitionname>
127+
<classname>wcf\system\\user\activity\event\PersonInformationUserActivityEvent</classname>
128+
</type>
129+
"""
130+
) }}
131+
132+
{jinja{ codebox(
133+
title="files/lib/system/user/activity/event/PersonInformationUserActivityEvent.class.php",
134+
language="php",
135+
filepath="tutorial/tutorial-series/part-6/files/lib/system/user/activity/event/PersonInformationUserActivityEvent.class.php"
136+
) }}
137+
138+
`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.
139+
140+
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.

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -137,6 +137,7 @@ nav:
137137
- 'Part 3': 'tutorial/series/part_3.md'
138138
- 'Part 4': 'tutorial/series/part_4.md'
139139
- 'Part 5': 'tutorial/series/part_5.md'
140+
- 'Part 6': 'tutorial/series/part_6.md'
140141

141142
plugins:
142143
- git-revision-date

0 commit comments

Comments
 (0)