Update documentation for content functions

2 files changed, 146 insertions, 33 deletions

diff --git a/Content functions.md b/Content functions.md
new file mode 100644
index 0000000..dea14a6
--- /dev/null
+++ b/Content functions.md
@@ -0,0 +1,66 @@
+The so-called *content functions* are a feature of this blogging system that gives you an easy way to reference another item of your blog from the content of any other item, without the need to hardlink the URL of the referenced item.
+
+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 now. They are still supported and 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.
+
+## 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 **category**. | `id`, `?text`, `?title`         |
+| `PAGE`     | Return Markdown formatted link to **page**.     | `id`, `?text`, `?title`         |
+| `POST`     | Return Markdown formatted link to **post**.     | `id`, `?text`, `?title`         |
+| `USER`     | Return Markdown formatted link to **user**.     | `id`, `?text`, `?title`         |
+
+## 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 between the opening and closing curly braces (but not necessary).
+
+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 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.
+
+**Note:** The parameters passed to the PHP callback function are (currently) always of type `string`!
+
+### Example: Calls with multiple parameters
+~~~
+{BASE_URL: "readme.md"}
+{CATEGORY: 1, "Look at this category!"}
+~~~
+
+## How to add custom functions?
+The new *content function* feature gives you the ability to define your own custom functions with a choosable set of parameters. 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.
\ No newline at end of file
diff --git a/Editor.md b/Editor.md
index 3659d7f..8d776f9 100644
--- a/Editor.md
+++ b/Editor.md
@@ -1,36 +1,83 @@
-If you wanna link an item of your blog application, please don't put the absolute URL hardcoded into the content editor. What if you want to change your blogs address (or just the base directory) in the future? You would have to change all the hardcoded links in your content. This is not cool! Therefore, you can use the following special syntax within the content editor to link any resource of your installation dynamically.
-
-**Note:** You can combine these codes with markdown syntax because the special codes are processed before the markdown parser walks through the content. The markdown parser will never see the original syntax of this special codes, but rather the result (an absolute URL) of those.
-
-## Dynamic linking of resources
-You can link resources which are located anywhere within your installation dynamically, either relative to your base directory or relative to your `rsrc` directory where you store your files like images and other stuff (this is the preferred method to include an image within your items content):
-
-* Write `{BASE["other/directory/"]}` into the editor and get:  
-`https://hostname/other/directory/`
-* Write `{FILE["image/foobar.jpg"]}` into the editor and get:  
-`https://hostname/rsrc/image/foobar.jpg`
-
-### Combined with markdown syntax for displaying images
-* Write `![A foobar image]({FILE["image/foobar.jpg"]})` into the editor and get:  
-`<img src="https://hostname/rsrc/image/foobar.jpg" alt="A foobar image" />`
-
-## Dynamic linking of pages, posts and users
-You have to know the unique ID of the item which you can find in the administration area, so that the system can identify it and replace the code with the items URL (if you put an ID into the syntax which does not exist, the output in your HTML will be just `{undefined}`):
-
-* Write `{PAGE[123]}` into the editor and get:  
-`https://hostname/page/page-with-id-123/`
-* Write `{POST[123]}` into the editor and get:  
-`https://hostname/post/post-with-id-123/`
-* Write `{USER[123]}` into the editor and get:  
-`https://hostname/user/user-with-id-123/`
-
-### Combined with markdown syntax for URL linking:
-* Write `[A cool page]({PAGE[123]})` into the editor and get:  
-`<a href="https://hostname/page/page-with-id-123/">A cool page</a>`
-* Write `[A cool post]({POST[123]})` into the editor and get:  
-`<a href="https://hostname/post/post-with-id-123/">A cool post</a>`
-* Write `[A cool user]({USER[123]})` into the editor and get:  
-`<a href="https://hostname/user/user-with-id-123/">A cool user</a>`
+If you want to reference another item (e.g. a post or a category) in your content, please do not put the URL to it hardcoded into the editor. Consider what happens if you change your blog's address (or just the base directory) in the future. You would need to change all the hardcoded URLs in your content which is inflexible and not cool. Therefore, you can use the following so-called [*content functions*](Content_Functions) to link an item or a resource of your installation dynamically within your Markdown content.
+
+**Note:** You can combine these functions with Markdown syntax since they are processed and transformed before the Markdown parser finally transforms the content to HTML. There is even the possibility [to add your own custom functions](Content_Functions#how-to-add-custom-functions).
+
+## Relative URLs
+You can link any resource (e.g. a file) which is located anywhere within your document root dynamically, either relative to your base directory (the installation directory) or relative to the `rsrc` directory where you store your files, images and other stuff. The `BASE_URL` and `FILE_URL` functions will return the pure plain text URL (extended by the first argument).
+
+### Example #1
+~~~markdown
+Hello there. Check out [the README]({BASE_URL: "readme.md"})!
+~~~
+~~~markdown
+<!-- Result after the functions were transformed: -->
+Hello there. Check out [the README](https://blog.git/readme.md)!
+~~~
+~~~html
+<!-- Final result after the Markdown was parsed: -->
+Hello there. Check out <a href="https://blog.git/readme.md">the README</a>!
+~~~
+
+### Example #2
+~~~markdown
+![A cute kitten]({FILE_URL: "image/content/kitten.jpg"} "Look at this!")
+~~~
+~~~markdown
+<!-- Result after the functions were transformed: -->
+![A cute kitten](https://blog.git/rsrc/image/content/kitten.jpg "Look at this!")
+~~~
+~~~html
+<!-- Final result after the Markdown was parsed: -->
+<img src="https://blog.git/rsrc/image/content/kitten.jpg" alt="A cute kitten" title="Look at this!" />
+~~~
+
+## Linking items in your content (categories, pages, posts and users)
+The following examples show you how to link a post in the content editor from any other item.
+
+Instead of returing just the pure URL like the `BASE_URL` or `FILE_URL` functions do, the item functions returning the complete Markdown formatted hyperlink syntax (including the text for the `title` attribute).
+
+The first argument is expected to be the unique ID of the item (which you can find in the administration area). If the second argument is present, it will be used as the hyperlink text; if it is omitted, the post title will be used as the hyperlink text. The third and last argument, if present, is used to customize the text for the `title` attribute of the final HTML's `<a>` tag.
+
+### Example #1
+~~~markdown
+Hello there! Check out this post: {POST: 1}
+~~~
+~~~markdown
+<!-- Result after the functions were transformed: -->
+Hello there! Check out this post: [»Hello World!«](https://blog.git/post/hello-world/ "Post »Hello World!«")
+~~~
+~~~html
+<!-- Final result after the Markdown was parsed: -->
+Hello there! Check out this post: <a href="https://blog.git/post/hello-world/" title="Post »Hello World!«">»Hello World!«</a>
+~~~
+
+### Example #2
+~~~markdown
+Hello there! Check out {POST: 1, "this post"}!
+~~~
+~~~markdown
+<!-- Result after the functions were transformed: -->
+Hello there! Check out [this post](https://blog.git/post/hello-world/ "Post »Hello World!«")!
+~~~
+~~~html
+<!-- Final result after the Markdown was parsed: -->
+Hello there! Check out <a href="https://blog.git/post/hello-world/" title="Post »Hello World!«">this post</a>!
+~~~
+
+### Example #3
+~~~markdown
+Hello there! Check out {POST: 1, "this post", "Click to show post"}!
+~~~
+~~~markdown
+<!-- Result after the functions were transformed: -->
+Hello there! Check out [this post](https://blog.git/post/hello-world/ "Click to show post")!
+~~~
+~~~html
+<!-- Final result after the Markdown was parsed: -->
+Hello there! Check out <a href="https://blog.git/post/hello-world/" title="Click to show post">this post</a>!
+~~~
+
+**Note:** The same syntax can also be used for the `CATEGORY`, `PAGE` and `USER` functions!