Update `codebox` macro

[GitHub/WoltLab/woltlab.github.io.git] / docs / tutorial / series / part_3.md

diff --git a/docs/tutorial/series/part_3.md b/docs/tutorial/series/part_3.md
index 5f650a5133c805e0fa3d93b1d851cf054669af15..6404d58078183ba62efb129947d99d7213533878 100644 (file)
--- a/docs/tutorial/series/part_3.md
+++ b/docs/tutorial/series/part_3.md
@@ -1,4 +1,4 @@
-# Tutorial Series Part 3: Person Page and Comments
+# Part 3: Person Page and Comments
 
 In this part of our tutorial series, we will add a new front end page to our package that is dedicated to each person and shows their personal details.
 To make good use of this new page and introduce a new API of WoltLab Suite, we will add the opportunity for users to comment on the person using WoltLab Suite’s reusable comment functionality.
@@ -29,6 +29,9 @@ The complete package will have the following file structure (including the files
 │   ├── personAdd.tpl
 │   └── personList.tpl
 ├── files
+│   ├── acp
+│   │   └── database
+│   │       └── install_com.woltlab.wcf.people.php
 │   └── lib
 │       ├── acp
 │       │   ├── form
@@ -55,7 +58,6 @@ The complete package will have the following file structure (including the files
 │           └── page
 │               └── handler
 │                   └── PersonPageHandler.class.php
-├── install.sql
 ├── language
 │   ├── de.xml
 │   └── en.xml
@@ -69,16 +71,18 @@ The complete package will have the following file structure (including the files
 └── userGroupOption.xml
 ```
 
-!!! warning "We will not mention every code change between the first part and this part, as we only want to focus on the important, new parts of the code. For example, there is a new `Person::getLink()` method and new language items have been added. For all changes, please refer to the [source code on GitHub]({jinja{ repo_url }}tree/{jinja{ edit_uri.split("/")[1] }}/snippets/tutorial/tutorial-series/part-3)."
+!!! warning "We will not mention every code change between the first part and this part, as we only want to focus on the important, new parts of the code. For example, there is a new `Person::getLink()` method and new language items have been added. 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-3)."
 
 
 ## Runtime Cache
 
 To reduce the number of database queries when different APIs require person objects, we implement a [runtime cache](../../php/api/caches_runtime-caches.md) for people:
 
-```php
---8<-- "tutorial/tutorial-series/part-3/files/lib/system/cache/runtime/PersonRuntimeCache.class.php"
-```
+{jinja{ codebox(
+  title="files/lib/system/cache/runtime/PersonRuntimeCache.class.php",
+  language="php",
+  filepath="tutorial/tutorial-series/part-3/files/lib/system/cache/runtime/PersonRuntimeCache.class.php"
+) }}
 
 
 ## Comments
@@ -86,15 +90,19 @@ To reduce the number of database queries when different APIs require person obje
 To allow users to comment on people, we need to tell the system that people support comments.
 This is done by registering a `com.woltlab.wcf.comment.commentableContent` object type whose processor implements [ICommentManager](https://github.com/WoltLab/WCF/blob/master/wcfsetup/install/files/lib/system/comment/manager/ICommentManager.class.php):
 
-```xml
---8<-- "tutorial/tutorial-series/part-3/objectType.xml"
-```
+{jinja{ codebox(
+  title="objectType.xml",
+  language="xml",
+  filepath="tutorial/tutorial-series/part-3/objectType.xml"
+) }}
 
 The `PersonCommentManager` class extended `ICommentManager`’s default implementation [AbstractCommentManager](https://github.com/WoltLab/WCF/blob/master/wcfsetup/install/files/lib/system/comment/manager/AbstractCommentManager.class.php):
 
-```php
---8<-- "tutorial/tutorial-series/part-3/files/lib/system/comment/manager/PersonCommentManager.class.php"
-```
+{jinja{ codebox(
+  title="files/lib/system/comment/manager/PersonCommentManager.class.php",
+  language="php",
+  filepath="tutorial/tutorial-series/part-3/files/lib/system/comment/manager/PersonCommentManager.class.php"
+) }}
 
 - First, the system is told the names of the permissions via the `$permission*` properties.
   More information about comment permissions can be found [here](../../php/api/comments.md#user-group-options).
@@ -116,9 +124,11 @@ With this option, comments on individual people can be disabled.
 
 ### `PersonPage`
 
-```php
---8<-- "tutorial/tutorial-series/part-3/files/lib/page/PersonPage.class.php"
-```
+{jinja{ codebox(
+  title="files/lib/page/PersonPage.class.php",
+  language="php",
+  filepath="tutorial/tutorial-series/part-3/files/lib/page/PersonPage.class.php"
+) }}
 
 The `PersonPage` class is similar to the `PersonEditForm` in the ACP in that it reads the id of the requested person from the request data and validates the id in `readParameters()`.
 The rest of the code only handles fetching the list of comments on the requested person.
@@ -127,9 +137,11 @@ The `assignVariables()` method assigns some additional template variables like `
 
 ### `person.tpl`
 
-```tpl
---8<-- "tutorial/tutorial-series/part-3/templates/person.tpl"
-```
+{jinja{ codebox(
+  title="templates/person.tpl",
+  language="tpl",
+  filepath="tutorial/tutorial-series/part-3/templates/person.tpl"
+) }}
 
 For now, the `person` template is still very empty and only shows the comments in the content area.
 The template code shown for comments is very generic and used in this form in many locations as it only sets the header of the comment list and the container `ul#personCommentList` element for the comments shown by `commentList` template.
@@ -139,9 +151,11 @@ The attribute `wysiwygSelector` should be the id of the comment list `personComm
 
 ### `page.xml`
 
-```xml
---8<-- "tutorial/tutorial-series/part-3/page.xml"
-```
+{jinja{ codebox(
+  title="page.xml",
+  language="xml",
+  filepath="tutorial/tutorial-series/part-3/page.xml"
+) }}
 
 The `page.xml` file has been extended for the new person page with identifier `com.woltlab.wcf.people.Person`.
 Compared to the pre-existing `com.woltlab.wcf.people.PersonList` page, there are four differences:
@@ -155,9 +169,11 @@ Compared to the pre-existing `com.woltlab.wcf.people.PersonList` page, there are
 
 ### `PersonPageHandler`
 
-```php
---8<-- "tutorial/tutorial-series/part-3/files/lib/system/page/handler/PersonPageHandler.class.php"
-```
+{jinja{ codebox(
+  title="files/lib/system/page/handler/PersonPageHandler.class.php",
+  language="php",
+  filepath="tutorial/tutorial-series/part-3/files/lib/system/page/handler/PersonPageHandler.class.php"
+) }}
 
 Like any page handler, the `PersonPageHandler` class has to implement the [IMenuPageHandler](https://github.com/WoltLab/WCF/blob/master/wcfsetup/install/files/lib/system/page/handler/IMenuPageHandler.class.php) interface, which should be done by extending the [AbstractMenuPageHandler](https://github.com/WoltLab/WCF/blob/master/wcfsetup/install/files/lib/system/page/handler/AbstractMenuPageHandler.class.php) class.
 As we want  administrators to link to specific people in menus, for example, we have to also implement the [ILookupPageHandler](https://github.com/WoltLab/WCF/blob/master/wcfsetup/install/files/lib/system/page/handler/ILookupPageHandler.class.php) interface by extending the [AbstractLookupPageHandler](https://github.com/WoltLab/WCF/blob/master/wcfsetup/install/files/lib/system/page/handler/AbstractLookupPageHandler.class.php) class.
@@ -185,5 +201,5 @@ The `IOnlineLocationPageHandler` interface requires two methods to be implemente
 
 This concludes the third part of our tutorial series after which each person has a dedicated page on which people can comment on the person.
 
-The complete source code of this part can be found on [GitHub]({jinja{ repo_url }}tree/{jinja{ edit_uri.split("/")[1] }}/snippets/tutorial/tutorial-series/part-3).
+The complete source code of this part can be found on [GitHub]({jinja{ config.repo_url }}tree/{jinja{ config.edit_uri.split("/")[1] }}/snippets/tutorial/tutorial-series/part-3).