Add documentation for category system

3 files changed, 91 insertions, 13 deletions

diff --git a/Configuration.md b/Configuration.md
index 6928db9..bb10918 100644
--- a/Configuration.md
+++ b/Configuration.md
@@ -66,9 +66,11 @@ Protocol, hostname and base directory of your installation.
 ## List size
 Number of items to display per-site on overview sites.
 
+* `CATEGORY.LIST_SIZE`: [integer: `10`]
 * `PAGE.LIST_SIZE`: [integer: `10`]
 * `POST.LIST_SIZE`: [integer: `10`]
 * `USER.LIST_SIZE`: [integer: `10`]
+* `ADMIN.CATEGORY.LIST_SIZE`: [integer: `12`]
 * `ADMIN.PAGE.LIST_SIZE`: [integer: `12`]
 * `ADMIN.POST.LIST_SIZE`: [integer: `12`]
 * `ADMIN.USER.LIST_SIZE`: [integer: `10`]
@@ -82,6 +84,7 @@ Number of items to display within the RSS feed.
 ## Slug URLs
 Enable or disable the use of slug URLs for item permalinks. If disabled, the unique primary item ID is used instead.
 
+* `CATEGORY.SLUG_URLS`: [bool: `TRUE`|`FALSE`]
 * `PAGE.SLUG_URLS`: [bool: `TRUE`|`FALSE`]
 * `POST.SLUG_URLS`: [bool: `TRUE`|`FALSE`]
 * `USER.SLUG_URLS`: [bool: `TRUE`|`FALSE`]
@@ -89,6 +92,7 @@ Enable or disable the use of slug URLs for item permalinks. If disabled, the uni
 ## Single redirects
 Enable or disable the redirection from the overviews to the items main page if only one item of the specific type exists. For example, if you only have one user and `USER.SINGLE_REDIRECT` is set to `TRUE`, then requests to `/user/` will be automatically redirected to `/user/username/` or `/user/id/`.
 
+* `CATEGORY.SINGLE_REDIRECT`: [bool: `TRUE`|`FALSE`]
 * `PAGE.SINGLE_REDIRECT`: [bool: `TRUE`|`FALSE`]
 * `POST.SINGLE_REDIRECT`: [bool: `TRUE`|`FALSE`]
 * `USER.SINGLE_REDIRECT`: [bool: `TRUE`|`FALSE`]
@@ -96,6 +100,7 @@ Enable or disable the redirection from the overviews to the items main page if o
 ## Directories
 Item base directories relative to your base directory where the application is installed.
 
+* `CATEGORY.DIRECTORY`: [string: `'category'`]
 * `PAGE.DIRECTORY`: [string: `'page'`]
 * `POST.DIRECTORY`: [string: `'post'`]
 * `USER.DIRECTORY`: [string: `'user'`]
@@ -103,6 +108,7 @@ Item base directories relative to your base directory where the application is i
 ## Emoticons
 Enable or disable parsing of emoticons for the body of the specific item type.
 
+* `CATEGORY.EMOTICONS`: [bool: `TRUE`|`FALSE`]
 * `PAGE.EMOTICONS`: [bool: `TRUE`|`FALSE`]
 * `POST.EMOTICONS`: [bool: `TRUE`|`FALSE`]
 * `USER.EMOTICONS`: [bool: `TRUE`|`FALSE`]
@@ -110,6 +116,7 @@ Enable or disable parsing of emoticons for the body of the specific item type.
 ## `<meta>` description
 Number of characters of the items content to display within the `<meta>` description.
 
+* `CATEGORY.DESCRIPTION_SIZE`: [integer: `200`]
 * `PAGE.DESCRIPTION_SIZE`: [integer: `200`]
 * `POST.DESCRIPTION_SIZE`: [integer: `200`]
 * `USER.DESCRIPTION_SIZE`: [integer: `200`]
@@ -117,6 +124,7 @@ Number of characters of the items content to display within the `<meta>` descrip
 ## Item overview sorting
 The `ORDER BY` clause for item sorting on item overview sites. You can use each column from the database table to sort and you also can combine multiple columns together. See the [MySQL documentation for `ORDER BY`](https://dev.mysql.com/doc/refman/5.6/en/sorting-rows.html) for more instructions.
 
+* `CATEGORY.LIST_SORT`: [string: `'name ASC'`] This option is currently used only for the list sorting of child categories in a category!
 * `PAGE.LIST_SORT`: [string: `'time_insert DESC'`]
 * `POST.LIST_SORT`: [string: `'time_insert DESC'`]
 * `USER.LIST_SORT`: [string: `'time_insert DESC'`]
diff --git a/Database.md b/Database.md
index 7c898af..053e796 100644
--- a/Database.md
+++ b/Database.md
@@ -1,34 +1,47 @@
 ## Table `migration` [`InnoDB`]
-This is an internal information table used for database schema upgrades and must contain only one row. Never modify this table manually unless you know what you are doing.
+This is an internal information table used for database schema migrations and must contain only one row with the current schema version used by the database. Never modify this table manually unless you know what you are doing.
 
 * Column `schema_version`: Contains the current schema version of the database structure.
 
+## Table `category` [`InnoDB`]
+This table contains all category entities.
+
+* Column `id`: Contains the unique primary ID to identify a category
+* Column `time_insert`: Contains the time stamp (Format: `YYYY-MM-DD HH:II:SS`) when the category was created
+* Column `time_update`: Contains the time stamp (Format: `YYYY-MM-DD HH:II:SS`) when the category was updated
+* Column `parent`: Contains the ID of the parent category (`category.id`) or is `NULL`
+* Column `slug`: Contains the slug part of the categories absolute URL
+* Column `name`: Contains the name of the category
+* Column `body`: Contains the content of the category in the markdown format
+* Column `argv`: Contains the optional argument string or is `NULL`
+
 ## Table `page` [`InnoDB`]
-In this table are all created page objects stored and will be removed if the admin deletes them.
+This table contains all page entities.
 
 * Column `id`: Contains the unique primary ID to identify a page
 * Column `time_insert`: Contains the time stamp (Format: `YYYY-MM-DD HH:II:SS`) when the page was created
 * Column `time_update`: Contains the time stamp (Format: `YYYY-MM-DD HH:II:SS`) when the page was updated
-* Column `user`: Contains the user ID of the user who created this page (`user.id`)
+* Column `user`: Contains the ID of the user assigned to this page (`user.id`)
 * Column `slug`: Contains the slug part of the pages absolute URL
 * Column `name`: Contains the name of the page
-* Column `body`: Contains the body of the page in the markdown format
+* Column `body`: Contains the content of the page in the markdown format
 * Column `argv`: Contains the optional argument string or is `NULL`
 
 ## Table `post` [`InnoDB`]
-In this table are all created post objects stored and will be removed if the admin deletes them.
+This table contains all post entities.
 
 * Column `id`: Contains the unique primary ID to identify a post
 * Column `time_insert`: Contains the time stamp (Format: `YYYY-MM-DD HH:II:SS`) when the post was created
 * Column `time_update`: Contains the time stamp (Format: `YYYY-MM-DD HH:II:SS`) when the post was updated
-* Column `user`: Contains the user ID of the user who created this post (`user.id`)
+* Column `user`: Contains the ID of the user assigned to this post (`user.id`)
+* Column `category`: Contains the ID of the category in which this post was published (`category.id`) or is `NULL`
 * Column `slug`: Contains the slug part of the posts absolute URL
 * Column `name`: Contains the name of the post
-* Column `body`: Contains the body of the post in the markdown format
+* Column `body`: Contains the content of the post in the markdown format
 * Column `argv`: Contains the optional argument string or is `NULL`
 
 ## Table `user` [`InnoDB`]
-In this table are all created user objects stored and will be removed if the admin deletes them.
+This table contains all user entities.
 
 * Column `id`: Contains the unique primary ID to identify a user
 * Column `time_insert`: Contains the time stamp (Format: `YYYY-MM-DD HH:II:SS`) when the user was created
@@ -38,8 +51,8 @@ In this table are all created user objects stored and will be removed if the adm
 * Column `password`: Contains the `bcrypt` hashed password of the user
 * Column `fullname`: Contains the full name of the user
 * Column `mailaddr`: Contains the contact email address of the user
-* Column `body`: Contains the body of the user in the markdown format
+* Column `body`: Contains the content of the user in the markdown format
 * Column `argv`: Contains the optional argument string or is `NULL`
 
-## Why database table prefixes are not supported
-The blogging application does not support the definition of a prefix for the database tables. This is because one database should only contain the data from one application (and if this is the case, prefixes are unnecessary). If multiple applications sharing  the same database and a security vulnerability is discovered in one of those applications, an attacker may be able to manipulate the data from the second application through the security vulnerability in the first application.
\ No newline at end of file
+## Why database table prefixes are not supported?
+The blogging application does not support the definition of a prefix for the database tables. This is because one database should only contain the data from one application (and if this is the case, prefixes are not necessary). If multiple applications sharing the same database and a security vulnerability is discovered in one of those applications, an attacker may be able to manipulate the data from the second application through the security vulnerability in the first application.
\ No newline at end of file
diff --git a/Templates.md b/Templates.md
index d58e6b1..841287f 100644
--- a/Templates.md
+++ b/Templates.md
@@ -3,6 +3,10 @@
 	├── html
 	│   ├── 403.php
 	│   ├── 404.php
+	│   ├── category
+	│   │   ├── item.php
+	│   │   ├── list.php
+	│   │   └── main.php
 	│   ├── feed
 	│   │   ├── item_page.php
 	│   │   ├── item_post.php
@@ -50,8 +54,12 @@ Basic framework of the HTML document which contains the main content:
 * `$HEAD['OG_IMAGES']`: Contains a list of image URLs for the document
 * `$HTML`: Contains the documents main body (other templates)
 
-**If you are on a page, post or user site:**  
-* `$TYPE`: Contains either `PAGE`, `POST` or `USER` as string value.
+**If you are on a single category, page, post or user:**  
+* `$TYPE`: Contains either `CATEGORY`, `PAGE`, `POST` or `USER` as string value.
+
+**If `$TYPE` is `CATEGORY`:**  
+* `$CATEGORY`: [See reference for `@CATEGORY`]
+* `$CATEGORIES`: Contains a list of `@CATEGORY` arrays (the parents and the direct category itself)
 
 **If `$TYPE` is `PAGE`:**  
 * `$PAGE`: [See reference for `@PAGE`]
@@ -70,6 +78,14 @@ This is the default startpage template which contains a list with the last posts
 * `$LIST['POSTS']`: Contains a list of post items for the home site
 * `$PAGINATION['HTML']`: Contains the pagination template with the list navigation
 
+## Category List Template `html/category/list.php`
+Overview template which contains the site navigation and a list of category items to be displayed.
+
+* `$LIST['CATEGORIES']`: Contains a list of category items for the current site
+* `$PAGINATION['THIS']`: Contains the current site number of the list navigation
+* `$PAGINATION['LAST']`: Contains the last site number of the list navigation
+* `$PAGINATION['HTML']`: Contains the pagination template with the list navigation
+
 ## Page List Template `html/page/list.php`
 Overview template which contains the site navigation and a list of page items to be displayed.
 
@@ -94,6 +110,15 @@ Overview template which contains the site navigation and a list of user items to
 * `$PAGINATION['LAST']`: Contains the last site number of the list navigation
 * `$PAGINATION['HTML']`: Contains the pagination template with the list navigation
 
+## Category Item Template `html/category/item.php`
+Represents a single category to display within the list template.
+
+* `$CATEGORY`: [See reference for `@CATEGORY`]
+* `$CATEGORIES`: Contains a list of `@CATEGORY` arrays (the parents and the direct category itself)
+* `$IS_ROOT`: Boolean if this category item is in the root list or if it is a child of some category
+* `$COUNT['POST']`: Contains the number of posts published in this category
+* `$COUNT['CHILDREN']`: Contains the number of children categories
+
 ## Page Item Template `html/page/item.php`
 Represents a single page to display within the list template.
 
@@ -105,12 +130,26 @@ Represents a single post to display within the list template.
 
 * `$POST`: [See reference for `@POST`]
 * `$USER`: [See reference for `@USER`]
+* `$CATEGORY`: [See reference for `@CATEGORY`]
+* `$CATEGORIES`: Contains a list of `@CATEGORY` arrays (the parents and the direct category itself)
 
 ## User Item Template `html/user/item.php`
 Represents a single user to display within the list template.
 
 * `$USER`: [See reference for `@USER`]
 
+## Category Main Template `html/category/main.php`
+Main template for a single category.
+
+* `$CATEGORY`: [See reference for `@CATEGORY`]
+* `$CATEGORIES`: Contains a list of `@CATEGORY` arrays (the parents and the direct category itself)
+* `$COUNT['POST']`: Contains the number of posts published in this category
+* `$COUNT['CHILDREN']`: Contains the number of children categories
+* `$CATEGORY['PREV']`: *NOT IMPLEMENTED YET*
+* `$CATEGORY['NEXT']`: *NOT IMPLEMENTED YET*
+* `$LIST['CATEGORIES']`: Contains a list of direct children categories
+* `$LIST['POSTS']`: Contains a list of post items in this category
+
 ## Page Main Template `html/page/main.php`
 Main template for a single page.
 
@@ -124,6 +163,8 @@ Main template for a single post.
 
 * `$POST`: [See reference for `@POST`]
 * `$USER`: [See reference for `@USER`]
+* `$CATEGORY`: [See reference for `@CATEGORY`]
+* `$CATEGORIES`: Contains a list of `@CATEGORY` arrays (the parents and the direct category itself)
 * `$POST['PREV']`: Same data structure as `$POST` but with the data from the previous post
 * `$POST['NEXT']`: Same data structure as `$POST` but with the data from the next post
 
@@ -199,6 +240,22 @@ Default template for error page 404 Not Found.
 
 ## References to reduce duplicate text
 
+### `@CATEGORY`
+* `$CATEGORY['URL']`: Contains the complete URL to the category content
+* `$CATEGORY['GUID']`: Contains a pseudo-guid of the category
+* `$CATEGORY['ARGV']`: Contains the arguments parsed as key->value array
+* `$CATEGORY['FILE']['LIST']`: List of extracted image URLs from the body
+* `$CATEGORY['BODY']['TEXT'] ()`: Pre-parsed content of the category body
+* `$CATEGORY['BODY']['HTML'] ()`: HTML parsed content of the category body
+* `$CATEGORY['ATTR']['ID']`: Raw attribute data from database column `id`
+* `$CATEGORY['ATTR']['PARENT']`: Raw attribute data from database column `parent`
+* `$CATEGORY['ATTR']['SLUG']`**{!}**: Raw attribute data from database column `slug`
+* `$CATEGORY['ATTR']['NAME']`**{!}**: Raw attribute data from database column `name`
+* `$CATEGORY['ATTR']['BODY']`**{!}**: Raw attribute data from database column `body`
+* `$CATEGORY['ATTR']['ARGV']`: Raw attribute data from database column `argv`
+* `$CATEGORY['ATTR']['TIME_INSERT']`: Raw attribute data from database column `time_insert`
+* `$CATEGORY['ATTR']['TIME_UPDATE']`: Raw attribute data from database column `time_update`
+
 ### `@PAGE`
 * `$PAGE['URL']`: Contains the complete URL to the page content
 * `$PAGE['GUID']`: Contains a pseudo-guid of the page