From 3feb79d4fa2982d7379e5ba8b1d56f9ad68d0752 Mon Sep 17 00:00:00 2001
From: Thomas Lange <code@nerdmind.de>
Date: Mon, 5 Feb 2024 20:27:31 +0100
Subject: Add page "Content_tags.md"

---
 Content_tags.md | 91 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 91 insertions(+)
 create mode 100644 Content_tags.md

diff --git a/Content_tags.md b/Content_tags.md
new file mode 100644
index 0000000..d526095
--- /dev/null
+++ b/Content_tags.md
@@ -0,0 +1,91 @@
+The *content tags* are the predecessor of the [*content functions*](Content_functions) which have been introduced in July 2021. Since then, *content tags* were considered deprecated in favor of the new *content functions*, and parsing/transforming support for the old syntax has been fully removed from the codebase in February 2024.
+
+This means that users who are still using the old syntax in their entities' content are recommended to run the `convert_content_tags.php` script in the `core/script` directory to migrate to the new syntax.
+
+## List of old content tags
+This table contains all hardcoded *content tags* that existed.
+
+| Tag    | Description                                   | Parameters      |
+|--------|-----------------------------------------------|-----------------|
+| `BASE` | Return pure URL relative to root directory.   | `(string) path` |
+| `FILE` | Return pure URL relative to `rsrc` directory. | `(string) path` |
+| `PAGE` | Return pure URL to a **page** entity.         | `(int) id`      |
+| `POST` | Return pure URL to a **post** entity.         | `(int) id`      |
+| `USER` | Return pure URL to a **user** entity.         | `(int) id`      |
+
+## Usage examples
+~~~md
+Hello. Check out [my new post]({POST[123]})!
+~~~
+
+~~~md
+![A cute kitten]({FILE["images/cats/kitten.jpg"]})
+~~~
+
+~~~md
+<script>let userUrl = "{USER[1]}";</script>
+~~~
+
+**Result:**
+~~~md
+Hello. Check out [my new post](https://hostname/post/new-post/)!
+~~~
+
+~~~md
+![A cute kitten](https://hostname/rsrc/images/cats/kitten.jpg)
+~~~
+
+~~~md
+<script>let userUrl = "https://hostname/user/john_doe/";</script>
+~~~
+
+## Executing the converter script
+The converter script can be found within the `core/script` directory. Just `cd` into the directory from the command-line and execute the script as follows (no worries, this is a *dry-run* first):
+
+~~~
+cd core/script
+php convert_content_tags.php
+~~~
+
+You now can check the output in your terminal to verify if all matches would be replaced correctly. If you are sure that everything is good, execute the script with the `commit` parameter:
+
+~~~
+php convert_content_tags.php commit
+~~~
+
+### Executing the script in HTTP context
+The system currently has no mechanism to run scripts from inside the administration area. The script must be placed in a directory that is not accessible via web so no one can run the script in the `core/script` directory from HTTP context.
+
+If you don't have terminal access, temporarily copy the script to your root directory and change the `require` statement in line `3` accordingly. You now can execute the script via web browser (the `commit` parameter can be passed as GET parameter).
+
+## How the converter scripts works
+The converter script loops through each entities' content and converts the old syntax to the new syntax in three steps, which are explained in detail below.
+
+### First step: Convert *all* `BASE` and `FILE` tags
+The script replaces **all** occurrences of the `BASE|FILE` syntax anywhere in the content, regardless of whether the tag is found within a Markdown formatted link or image syntax or somewhere else. All matches will be replaced with a call to the `BASE_URL` or `FILE_URL` *content function*.
+
+**Example:**  
+~~~
+<-- ![A cute kitten]({FILE["images/cats/kitten.jpg"]})
+--> ![A cute kitten]({FILE_URL: "images/cats/kitten.jpg"})
+~~~
+
+### Second step: Convert `PAGE|POST|USER` tags *used inside Markdown syntax*
+Because the new *content functions* `CATEGORY|PAGE|POST|USER` return a Markdown formatted link to the entity, the script searches for all occurrences of the `PAGE|POST|USER` *content tags* used as URL **inside a (valid) Markdown formatted link.**
+
+It then converts the **whole** Markdown formatted link to just a call of either the `PAGE`, `POST` or `USER` *content function* with the original link text and title as parameters for the *content function*.
+
+**Example:**  
+~~~
+<-- Hello. Check out [my new post]({POST[123]})!
+--> Hello. Check out {POST: 123, "my new post"}!
+~~~
+
+### Third step: Convert `PAGE|POST|USER` tags used anywhere else
+Now all `PAGE|POST|USER` *content tags* that are found anywhere else in the content will be replaced with the `(PAGE|POST|USER)_URL` *content function*, which will just return the absolute URL to the entity.
+
+**Example:**  
+~~~
+<-- <script>let userUrl = "{USER[1]}";</script>
+--> <script>let userUrl = "{USER_URL: 1}";</script>
+~~~
-- 
cgit v1.2.3