commit 1a0977b3af98cfdaaff68fdd4e9edc4a7808fec2 parent c8006e39be69e86700103ef579a33c6eb311de8c Author: Jan Dankert <develop@jandankert.de> Date: Mon, 24 Feb 2020 18:36:11 +0100 Documentation added. Diffstat:
27 files changed, 296 insertions(+), 15 deletions(-)
diff --git a/client/java/README.md b/client/java/README.md @@ -0,0 +1,5 @@ +# Java client side implementation + +Java client for accessing the API is now available in a separate project. + +See [openrat-java-client](http://code.weiherhei.de/openrat-java-client/log.html). diff --git a/client/java/README.txt b/client/java/README.txt @@ -1 +0,0 @@ -See other project "openrat-java-client".- \ No newline at end of file diff --git a/client/php/README.md b/client/php/README.md @@ -0,0 +1,3 @@ +# PHP API client + +This is a simple PHP client for accessing the CMS API. diff --git a/config/config.yml b/config/config.yml @@ -4,7 +4,7 @@ # This file is YAML formatted. -# Security attention: +# Security warning: # Place your sensitive configuration outside of your document root! @@ -15,7 +15,7 @@ database: user : "dbuser" # user password: "dbpass" # password (attention: please to NOT place any passwords in the document root) -# It is recommended to place a configation outside the document root +# It is recommended to place the configuration outside of the document root # # Simple example: # include: /etc/openrat/config.yml diff --git a/dev-helper/README.md b/dev-helper/README.md @@ -1,6 +1,6 @@ # Development Tools -These files are only necessary for developers! +These files are only necessary **for developers**! ## Generate output files diff --git a/modules/README.md b/modules/README.md @@ -1,6 +1,7 @@ OpenRat Module System --------------------- -Every directory contains a module with a file `require.php`. +## Classloading +Classes in modules are normally loaded by the [autoloader](autoload.php). \ No newline at end of file diff --git a/modules/cms/README.md b/modules/cms/README.md @@ -0,0 +1,4 @@ +# CMS modules + +OpenRat CMS is using the [model-view-presenter](https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93presenter) design pattern for executing requests. + diff --git a/modules/cms/action/README.md b/modules/cms/action/README.md @@ -0,0 +1,12 @@ +# And... Action! + +These action classes are the 'presenter' part in the [model-view-presenter](https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93presenter). + + +Their mission is to +- validate input data +- calling the model +- providing all data for the UI. + +Contracts: +- **no database requests are done here!** Database requests are only done by the model classes.+ \ No newline at end of file diff --git a/modules/cms/auth/README.md b/modules/cms/auth/README.md @@ -0,0 +1,8 @@ +# Authentication backends + +These authentication backends are used for user identification and authentication. + +Every Authentication must implement [Auth](Auth.class.php) and must provide the 2 methods + +1. `login()` must do an authentification. On successful logins, it should return `OR_AUTH_STATUS_SUCCESS`. If this is not possible, this methode must return `false` or `OR_AUTH_STATUS_FAILED`. +1. `username()` may find out the username of the user which want to log in. If this is not possible, this method must return `false` or `OR_AUTH_STATUS_FAILED`.+ \ No newline at end of file diff --git a/modules/cms/macros/README.md b/modules/cms/macros/README.md @@ -0,0 +1,5 @@ +# Macros + +Macros are executed by the CMS for generating custom data. Mostly this is necessary for navigation fragments in web pages. + +Execution is done in the publishing step of pages.+ \ No newline at end of file diff --git a/modules/cms/publish/README.md b/modules/cms/publish/README.md @@ -0,0 +1,5 @@ +# Publishing + +The Publish objects are used for +- creating links to other node objects. +- copying the generated file to a live server.+ \ No newline at end of file diff --git a/modules/cms/publish/filter/README.md b/modules/cms/publish/filter/README.md @@ -0,0 +1,7 @@ +# Filters + +Filters are executed by the CMS after generating a node object. + +## Example + +A script file is generated and before publishing it should be minified. This is done by the JavascriptMinifierFilter.+ \ No newline at end of file diff --git a/modules/cms/ui/README.md b/modules/cms/ui/README.md @@ -0,0 +1,7 @@ +# UI + +This module is containing the CMS user interface. + +- Styles +- Scripts +- HTML views+ \ No newline at end of file diff --git a/modules/cms/ui/themes/default/html/views/README.md b/modules/cms/ui/themes/default/html/views/README.md @@ -1,19 +1,26 @@ -## OpenRat CMS Templates +# OpenRat CMS Views All views are desribe within a XML file with the extension `.tpl.src.xml`. These views are compiled to `.php` files. -# Components +All XML files are linked to the [XSD schema](../../../../../../template_engine/components/README.md), this makes the creation of template files more simple. -You may use the following namespaces for the source xml files: +## Finding the view + +Every request has an 'action' and a 'subaction'. + +The matching template is `html/views/<action>/<subaction>.src.xml` + +## Components + +The following namespaces are available for the source xml files: - `http://www.openrat.de/template` for special CMS components. - `http://www.w3.org/1999/xhtml` for HTML5 components. -# Variables +## Variables - `${variable.name}` outputs a data variable - `#{messagekey}` outputs a i18n message - `%{config/subconfig/value}` outputs a configuration value - diff --git a/modules/cms/update/README.md b/modules/cms/update/README.md @@ -0,0 +1,19 @@ +# Updating + +This module is intended to upgrade a database schema. + +## Usage + + +The `isUpdateRequired()` method finds out the version of the actual db schema. If it is lower than the last known version, `true` is returned. + +The `update()` applys all necessary changes from the subdirectory `version` to the database. + +## Example + +``` +$updater = new Update( $database ); + +if ( $updater->isUpdateRequired() ) + $updater->update(); +``` diff --git a/modules/configuration/README.md b/modules/configuration/README.md @@ -0,0 +1 @@ +# Configuration module diff --git a/modules/database/README.md b/modules/database/README.md @@ -0,0 +1,27 @@ +# Database module + +This module contains database specific functionality. + +## Usage + +### Initialisation + +``` +$database = new Database( [ + 'dsn' =>'mysql:host=localhost; dbname=name; charset=utf8', + 'user' =>'user',' + 'password'=>'...' + ] ); +``` + +The `dsn` is described in the [PDO manual](https://www.php.net/manual/de/pdo.construct.php). + +## Executing queries +The database object is able to create Statement objects. You only have to apply a SQL query. +``` +$statement = $database->sql('select * from table'); + +$data = $statement->getRow(); +$data = $data['column']; +// ... +```+ \ No newline at end of file diff --git a/modules/editor/README.md b/modules/editor/README.md @@ -0,0 +1,3 @@ +# External editors + +External editor implementations+ \ No newline at end of file diff --git a/modules/language/README.md b/modules/language/README.md @@ -0,0 +1,9 @@ +# Internationalisation + +A module for internationalisation + +## Maintanance of entrys + +All language information is contained in the file `language.yml`. + +The files `lang-<key>.php` are generated by the language file compiler. Do not change these manually.+ \ No newline at end of file diff --git a/modules/logger/README.md b/modules/logger/README.md @@ -0,0 +1,22 @@ +# Logger + +A simple custom logger implementation. + +## Configuration + +The logger is configurated in a static way + +### Example + +``` +Logger::level = LOGGER_LOG_INFO; +``` + +## Using + +### Example + +``` +Logger::error('something happened'); + +```+ \ No newline at end of file diff --git a/modules/security/README.md b/modules/security/README.md @@ -0,0 +1 @@ +# Security+ \ No newline at end of file diff --git a/modules/template_engine/components/README.md b/modules/template_engine/components/README.md @@ -0,0 +1,9 @@ + +# XSD file +the [XSD](https://en.wikipedia.org/wiki/XML_schema) file [template.xsd](template.xsd) contains a declaration of all available components with its possible attributes. + +Its point is to simplify the creation of template files. + +# XSD generator + +The [XSD generator](XSDGenerator.php) can be called directly by a browser.+ \ No newline at end of file diff --git a/modules/template_engine/components/XSDGenerator.php b/modules/template_engine/components/XSDGenerator.php @@ -26,7 +26,8 @@ fwrite($componentsFile, '# generated by XSDGenerator. do not change manually.' . fwrite($xsdFile, '<?xml version="1.0" encoding="utf-8"?> <xsd:schema xmlns="http://www.openrat.de/template" targetNamespace="http://www.openrat.de/template" xmlns:xsd="http://www.w3.org/2001/XMLSchema" - elementFormDefault="qualified" attributeFormDefault="unqualified">' . "\n"); + elementFormDefault="qualified" attributeFormDefault="unqualified">' . "\n". + '<!-- generated by XSDGenerator. do not change manually -->'."\n"); foreach ($folder as $f) { diff --git a/modules/template_engine/element/README.md b/modules/template_engine/element/README.md @@ -0,0 +1,29 @@ +# Element and Attributes + +The template compiler is transforming the component tree into a tree of elements. + +## Example + + form + + link + + text + +is transformed into + + form + + div + + a + + span + + div + + button + + button + +# Values and ValueExpressions + +[Value](Value.class.php)s are a string, which may contain [ValueExpression](ValueExpression.class.php) objects. + +## Example + + i am ${feeling} + +The value is `i am ${feeling}` and it contains a ValueExpression object based on `${feeling}`. diff --git a/modules/template_engine/element/attribute/ConditionalAttribute.class.php b/modules/template_engine/element/attribute/ConditionalAttribute.class.php @@ -7,15 +7,21 @@ namespace template_engine\element\attribute; use template_engine\element\attribute\SimpleAttribute; use template_engine\element\Value; +/** + * A conditional attribute is an attribute whose existence depends on a condition. + * The condition would normally be an PHP expression. +*/ class ConditionalAttribute extends SimpleAttribute { +/** The condition must be an valid PHP expression. + */ protected $condition; /** * ConditionalAttribute constructor. - * @param $condition - * @param $name - * @param $value + * @param $condition must be a valid PHP expression + * @param $name name of attribute + * @param $value value */ public function __construct($condition,$name,$value) { @@ -24,6 +30,10 @@ class ConditionalAttribute extends SimpleAttribute } + /** + * Rendering of the value. + * the value is wrapped into the conditional PHP expression. + */ public function render() { return '<?php if('.$this->condition.'){ ?>'.parent::render().'<?php } ?>'; diff --git a/modules/util/README.md b/modules/util/README.md @@ -0,0 +1,4 @@ +# Utilities + + + + \ No newline at end of file diff --git a/modules/wikiparser/README.md b/modules/wikiparser/README.md @@ -0,0 +1,71 @@ +# Wikiparser module + +This is a older markup language, which is similar to some common markup languages like Markdown. + +This module is necessary for old content, which is based on this language. + +## Syntax + +### Simple text +- \***bold text**\* +- \__italice text_\_ +- =`fixed width`= + +### Definition lists + +some::thing + +### Source text += +``` +source text +``` += + +### Quotes + +\> +> multiline quote + +\> + + +### Headlines + +\+ Headline 1\ +\++ Headline 2\ +\+++ Headline 3\ +\++++ Headline 4\ +\+++++ Headline 5\ +\++++++ Headline 6\ + +Headline 1\ +\========== + +Headline 2\ +\---------- + +Headline 3\ +\.......... + + +### List + +\- some\ +\- thing + +### Numbered List + +\# some\ +\# thing + + +### Links + +Link->http://... + +### Tables + +|!Headline||!Headline over 2 columns|!Headline\ +|Text|Text|(cssclass)Text|Text +