1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
|
The so-called *content functions* are a feature of this blogging system that gives you an easy way to reference another entity of your blog from the content of any other entity, without the need to hard link the URL of the referenced entity.
This document explains the available *content functions* that are shipped with the system by default and shows you how to add your own customized *content functions* to do some interesting things and prevent repetitive lines of text in your content.
**Note:** There is a second older syntax for the so-called *content tags* (like `{POST[1]}`) which are deprecated. They will still be parsed and transformed, but please do not use them anymore if you can use the much more powerful *content functions* described in this document. It's planned to remove parsing/transforming support for the *content tags* soon!
## Registered default functions
The table below contains all default *content functions* you can use.
| Function | Description | Parameters (`?` means optional) |
|----------------|---------------------------------------------------|---------------------------------|
| `BASE_URL` | Return pure URL relative to root directory. | `?extend` |
| `FILE_URL` | Return pure URL relative to `rsrc` directory. | `?extend` |
| `CATEGORY` | Return Markdown formatted link to a **category**. | `id`, `?text`, `?title` |
| `PAGE` | Return Markdown formatted link to a **page**. | `id`, `?text`, `?title` |
| `POST` | Return Markdown formatted link to a **post**. | `id`, `?text`, `?title` |
| `USER` | Return Markdown formatted link to a **user**. | `id`, `?text`, `?title` |
| `CATEGORY_URL` | Return pure URL to a **category**. | `id` |
| `PAGE_URL` | Return pure URL to a **page**. | `id` |
| `POST_URL` | Return pure URL to a **post**. | `id` |
| `USER_URL` | Return pure URL to a **user**. | `id` |
## Syntax
The name of the *content function* and its parameters is put between an opening (`{`) and closing (`}`) curly brace. An optional blank space (` `) is permitted (but not required) between the opening and closing curly braces.
After the opening curly brace (and the optional blank space), the name of the *content function* (in uppercase letters) is followed directly after. If the *content function* shall be called without any parameters, the function name is followed by the optional space (mentioned above) and directly after by the closing curly brace.
### Example: Call `BASE_URL`
~~~
{BASE_URL}
~~~
Parameters (or "arguments") for the *content function* are separated from the function name by a required colon (`:`) and a required blank space. The parameter list consists of either integer values (`123`) or string values (`"Hello"`).
String values must be put between double (`"`) or single (`'`) quotes while integer values do not need quotes around. Multiple parameters are separated from each other by a required comma (`,`) with an optional blank space directly after the comma. It is possible to escape quotes in string arguments by preceding them with a backslash (`\`).
**Note:** The parameters passed to the PHP callback function are (currently) always of type `string`!
### Example: Call functions with parameters
~~~
{BASE_URL: "readme.md"}
{CATEGORY: 1, "Look at this category!"}
~~~
### Example: Escape quotes in string arguments
~~~
{POST: 1, "And then he said: \"Hello\""}
~~~
## How to add custom functions?
The new *content function* feature gives you the ability to define your own custom functions. This is especially useful if you, for example, want to embed a YouTube video in a post but do not want to repeat the repetitive HTML embed code anytime when you want to show a YouTube video in your posts. You can just register a new *content function* to do this!
The interface to register a new *content function* is the method `addContentFunction` of the `Application` class. This method requires exactly two parameters: The **function name** and the **callback function**. The function name is validated and must contain only numbers, uppercase letters and underscores. An exception is thrown if this rule is violated.
The function can take required and optional parameters, but currently only parameters of type `string` are supported. So if you define the type of a parameter to be something other than `string`, it could cause errors when calling the function.
There is also a check for required paremeters. If the function needs required parameters but is called with less than the required amount of parameters, the `FunctionParser` will return `{FUNCTION_NAME: *Missing arguments*}` instead.
In the function itself, it is perfectly OK to use application internal code if you know what you are doing. But please be aware that application internal code will change over time, so you need to keep track of the changes made to the codebase if you use some application internal code in your functions.
### Example: Embed YouTube videos (via Invidious)
So lets register the content function `YOUTUBE` to easily embed YouTube videos! In this example, I will use a public instance of the privacy-friendly *YouTube* frontend called [*Invidious*](https://github.com/iv-org/invidious).
~~~php
# core/configuration.php
Application::addContentFunction('YOUTUBE', function($watch) {
return sprintf('<div class="video">
<iframe src="https://ytprivate.com/embed/%s" allowfullscreen referrerpolicy="no-referrer"></iframe>
</div>', $watch);
});
~~~
Done. You can now call this function by typing `{YOUTUBE: "aqz-KE-bpKQ"}` into the editor!
The benefits of this are obvious: If you later change your mind about the way how videos are embedded, you just need to change your *content function* without modifying all the posts in which you have a video embedded.
|
