diff options
| -rw-r--r-- | Arguments.md | 12 | ||||
| -rw-r--r-- | Configuration.md | 34 | ||||
| -rw-r--r-- | Database.md | 2 | ||||
| -rw-r--r-- | Editor.md | 8 |
4 files changed, 35 insertions, 21 deletions
diff --git a/Arguments.md b/Arguments.md index 53edfce..6e00feb 100644 --- a/Arguments.md +++ b/Arguments.md @@ -1,7 +1,9 @@ -This document explains how to use the optional field for arguments in the content editor. This field can contain a list of arguments as key or key/value pairs formatted as follows: `FOO=value|BAR=value` (or `FOO=value|BAR`; `BAR` will be automatically set to `TRUE`). +This document explains how to use the optional field for arguments in the content editor. This field can contain a list of arguments as key or key/value pairs formatted as follows: + +`FOO=value|BAR=value` (or `FOO=value|BAR`; `BAR` will be automatically set to `TRUE`). ## How to access arguments in a template -Lets assume that your argument string for a specific post is something like this: `HIGHLIGHT|PREVIEW_IMG=foobar.png`. You can now access the entire (unparsed) argument string in templates by `$POST['ATTR']['ARGV']` (see template documentation for further information). This contains the unparsed argument string as he was written in the content editor. You also can access an parsed version of the arguments as key->value array with `$POST['ARGV']`: +Lets assume that your argument string for a specific post is something like this: `HIGHLIGHT|PREVIEW_IMG=foobar.png`. You can now access the entire (unparsed) argument string in templates with `$POST['ATTR']['ARGV']` (see template documentation for more information). This contains the unparsed argument string as he was written into the content editor. You also can access a parsed version of the arguments as key->value array with `$POST['ARGV']`: ### Unparsed: `$POST['ATTR']['ARGV']` string(32) "HIGHLIGHT|PREVIEW_IMG=foobar.png" @@ -15,9 +17,9 @@ Lets assume that your argument string for a specific post is something like this } ## How this arguments can be used to do something special -If you are a template developer, you can check within your templates if the argument `HIGHLIGHT` is present (arguments with no explicit value will be automatically set to `TRUE`). If true, you can highlight this post differently (if you have some "promo posts" or something: just check if this value is set and add an extra CSS class to your HTML markup which then will highlight your post). +If you are a template developer, you can check within your templates if the argument `HIGHLIGHT` is present (arguments with no explicit value will be automatically set to boolean `TRUE`). If set, you can highlight this post differently. Just check if this value is set and add an extra CSS class to your HTML markup which then will highlight your post. -You even can add an preview image functionality. What if you want to show an preview image for each post in the list? There is no core functionality to do this, but with the argument functionality you can do this very simple: +You can even add an preview image functionality. Lets assume you want to show a preview image for each post in the list? There is no core functionality to do this, but with the argument functionality you can do this very simple: <?php if(isset($POST['ARGV']['PREVIEW_IMG'])): ?> <img class="preview-img" href="<?=Application::getFileURL("images/preview/{$POST['ARGV']['PREVIEW_IMG']}")?>" alt="" /> @@ -27,4 +29,4 @@ You even can add an preview image functionality. What if you want to show an pre Each argument key (the part before the `=`) must only contain letters from `A-Z`, `a-z`, `0-9` and underscores (`_`)! ## Conclusion -The use cases of the arguments are practically unlimited. Please note that the templates of the `default` theme are not using any arguments provided in the argument field. It is up to you whether you implement this in your own template to do something special or not!
\ No newline at end of file +The use cases of these arguments are practically unlimited. Please note that the templates of the `default` theme are not using any arguments provided in the argument field. It is up **to you** whether you implement this in your own template to do something special or not!
\ No newline at end of file diff --git a/Configuration.md b/Configuration.md index d2f1996..e964745 100644 --- a/Configuration.md +++ b/Configuration.md @@ -1,17 +1,29 @@ -This document describes the available configuration settings from the `configuration.php` file in more detail. +This document describes the available configuration settings of the `configuration.php` file in more detail. ## Language configuration -This is the core language which will be used. A corresponding language file **must exists** within `core/language/`. Currently are only `en` and `de` supported. If you are a translator, please only use the original `en` language file for your translation and open a pull request on GitHub or send your language file via email to `code@nerdmind.de`! +This is the core language which will be used. A corresponding language file **must exists** within `core/language/`. Currently only `en` and `de` are supported. If you are a translator, please only use the original `en` language file for your translation and open a pull request on GitHub or send your language file via email to `code@nerdmind.de`! * `CORE.LANGUAGE`: [string: `'en'`] ## ETag configuration -If this parameter is set to `TRUE`, the system will generate an `ETag` response header which includes a hash of the timestamps from the last created / edited items and sends him to the client. The client will cache this header and sends him with each further request in the request header back to the application. If the hash, which the appplication now creates again, is not the same as the one from the request header (which means that no new items have been published and no existing item have been edited), the application exit and returns the `304 Not Modified` response header to reduce server load and traffic. +If `CORE.SEND_304` is set to `TRUE`, the application generates an `ETag` response header on each request which consists of a hash value based on the timestamps of the last created/edited items. The client will cache this information and sends it with the next request (inside the request header `If-None-Match`) back to the application. + +**Application sends `ETag` header:** +~~~ +ETag: "241d9ec9cb7526853698590929f06ae9-gzip" +~~~ + +**Client sends `If-None-Match` header on next request:** +~~~ +If-None-Match: "241d9ec9cb7526853698590929f06ae9-gzip" +~~~ + +The application now calculates again a hash value of the last created/edited items and compares it to the hash of the `If-None-Match` request header which was sent by the client. If these two hash values are **the same**, then obviously no new items have been created/edited since the last request by the client. Therefore, the application immediately exits and returns the `304 Not Modified` HTTP response status. * `CORE.SEND_304`: [boolean: `TRUE`|`FALSE`] ## Blog informations -Meta informations about your custom blog installation. Note that `BLOGMETA.LANG` is not the system language! It is the language in which **your content** is written and is useful for the `lang` attribute on the `<html>` tag within the template. It depends on the template whether this variable is used or not. +Meta informations about your custom blog installation. Please note that `BLOGMETA.LANG` is not the system language! It is the language in which **your content** is written and is useful for the `lang` attribute on the `<html>` tag within the template. It depends on the template whether this variable is used or not. * `BLOGMETA.NAME`: [string: `'My Techblog'`] * `BLOGMETA.DESC`: [string: `'[a creative description]'`] @@ -20,7 +32,7 @@ Meta informations about your custom blog installation. Note that `BLOGMETA.LANG` * `BLOGMETA.LANG`: [string: `'en'`] ## Database -Database and hostname with login credentials to authenticate to the MariaDB or MySQL server. +Database and hostname with login credentials to authenticate to the MariaDB/MySQL server. * `DATABASE.HOSTNAME`: [string: `'localhost'`] * `DATABASE.BASENAME`: [string: `'niceblog'`] @@ -67,7 +79,7 @@ Enable or disable the use of slug URLs for item permalinks. If disabled, the uni * `USER.SLUG_URLS`: [boolean: `TRUE`|`FALSE`] ## 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/`. +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/`. * `PAGE.SINGLE_REDIRECT`: [boolean: `TRUE`|`FALSE`] * `POST.SINGLE_REDIRECT`: [boolean: `TRUE`|`FALSE`] @@ -81,30 +93,30 @@ Item base directories relative to your base directory where the application is i * `USER.DIRECTORY`: [string: `'user'`] ## Emoticons -Enable or disable parsing of emoticons for the body of the item. +Enable or disable parsing of emoticons for the body of the specific item type. * `PAGE.EMOTICONS`: [boolean: `TRUE`|`FALSE`] * `POST.EMOTICONS`: [boolean: `TRUE`|`FALSE`] * `USER.EMOTICONS`: [boolean: `TRUE`|`FALSE`] ## `<meta>` description -Number of characters from the items content to display within the `<meta>` description. +Number of characters of the items content to display within the `<meta>` description. * `PAGE.DESCRIPTION_SIZE`: [integer: `200`] * `POST.DESCRIPTION_SIZE`: [integer: `200`] * `USER.DESCRIPTION_SIZE`: [integer: `200`] ## 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 information. +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. * `PAGE.LIST_SORT`: [string: `'time_insert DESC'`] * `POST.LIST_SORT`: [string: `'time_insert DESC'`] * `USER.LIST_SORT`: [string: `'time_insert DESC'`] ## Feed sorting -The `ORDER BY` clause for item sorting within the RSS feed. 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 information. +The `ORDER BY` clause for item sorting within the RSS feed. 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. -**Note:** It depends on the RSS reader how the content is sorted. The settings here are only for the sorting of the content in the raw XML source code, but it is nevertheless a good idea to sort them as they shall appear in the RSS reader. +**Note:** It depends on the RSS reader how the content is sorted. The settings here are only for the sorting of the content **in the raw XML** source code, but it is nevertheless a good idea to sort them in the order as they shall appear in the RSS reader. * `PAGE.FEED_SORT`: [string: `'time_insert DESC'`] * `POST.FEED_SORT`: [string: `'time_insert DESC'`] diff --git a/Database.md b/Database.md index 58d378e..aef3a33 100644 --- a/Database.md +++ b/Database.md @@ -37,4 +37,4 @@ In this table are all created user objects stored and will be removed if the adm * 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 are 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 +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 @@ -1,9 +1,9 @@ -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 sites 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! Thus, you can use the following special syntax within the content editor to link any resource of your installation dynamically. +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 starts. The markdown parser will never see the original syntax of this special codes, but rather the result (an absolute URL) of those. +**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 content like images and other files (this is the preferred method to include an image within your items content): +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/` @@ -15,7 +15,7 @@ You can link resources which are located anywhere within your installation dynam `<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 exists, the output in your HTML will be just `{undefined}`): +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/` |