Add documentation

7 files changed, 173 insertions, 0 deletions

diff --git a/doc/baseconfig_-_config-variables b/doc/baseconfig_-_config-variables
new file mode 100644
index 00000000..6c85b7de
--- /dev/null
+++ b/doc/baseconfig_-_config-variables
@@ -0,0 +1,42 @@
+The baseconfig module (configuration variables) is now modularized in two
+ways.
+
+
+1) The definition of configuration variables has moved from the database to
+dedicated .json files, which can be defined by one or multiple additional
+modules. This means the database table "settings" is no longer in use.
+As an example, see the module "baseconfig_bwlp".
+If you only enable the module "baseconfig", you will find that visiting
+the "configuration variables" menu entry in slx-admin shows a pretty empty
+page. However, if you additionally enable the baseconfig_bwlp module, many
+configuration variables will be shown.
+baseconfig_bwlp doesn't contain any config.json or page.inc.php, as its
+sole purpose is to supply wanted configuration variables. This is achieved
+by supplying two .json files.
+
+./modules/<module>/baseconfig/categories.json: Defines categories for
+configuration variables. Syntax is <id>:<sort-order>
+
+./modules/<module>/baseconfig/settings.json: Defines configuration variables
+to be shown by the baseconfig page. This has taken the place of the settings
+table from the database and contains pretty much the same information.
+
+Note that you can have multiple modules that supply categories.json or
+settings.json files. They will all be honored by the baseconfig module.
+
+2) You can hook into the baseconfig API mechanism (previously known as
+the "getconfig" API) which creates the plain text output intended for
+the clients. This way you can create more sophisticated output logic, or
+simply have a nicer guy for some values you want to generate.
+To hook into the API, you need a hook:
+./modules/<module>/baseconfig/getconfig.inc.php
+This code will run directly in the context of the baseconfig API request,
+so you write code straight away that should add any configuration variables
+to the associative array called $configVars, e.g.
+$configVars['SLX_FOO'] = 'bar';
+These values can be static, or queried from anywhere in the database, etc.
+For an example of this, see the module "baseconfig_partitions_cdn"
+Which is basically a normal slx-admin module with a GUI for creating a
+partitioning config that get stored in the database.
+It also contains the .../baseconfig/getconfig.inc.php hook that adds
+the partition configuration to the output of the baseconfig API.
diff --git a/doc/dashboard b/doc/dashboard
new file mode 100644
index 00000000..3040bb6f
--- /dev/null
+++ b/doc/dashboard
@@ -0,0 +1,20 @@
+The dashboard is usually created automatically and doesn't require any
+special setup. The order of the settings and categories in the menu
+can be influenced by the two variables $MENU_CAT_SORT_ORDER and
+$MENU_SETTING_SORT_ORDER in config.php (see config.php.example)
+
+Menu categories can be defined implicitly in the form of
+modulename.catname, i.e. main.content
+
+To assign an icon to the category, create a file called category-icons.json
+in the module's root dir (i.e. ./modules/main/category-icons.json)
+and add a key value pair of the form "catname":"glyphicon", i.e.
+{ "content":"th" }. Notice the module name is not prefixed again.
+
+To translate the category's name, visit the translation page and go
+to the module in which the category is defined (in this example, main).
+You'll see a panel dedicated to menu categories, it should contain the
+Note: The menu section will only appear in the translation list of the
+module if any active module is assigned to this category. However, you
+can still manually create the entry by using the "create tag" button.
+As an example, see the "main" or the "citymanagement" module.
diff --git a/doc/enabling_modules b/doc/enabling_modules
new file mode 100644
index 00000000..dd36d000
--- /dev/null
+++ b/doc/enabling_modules
@@ -0,0 +1,16 @@
+As a convention, modules should be placed in another directory and then
+get selectively enabled by symlinking.
+Currently, all modules are placed in ./modules-available, and the symlinks
+reside in ./modules
+Note that you can name the symlink differently. The name of the symlink
+will define by what identifier the module is referred to. This way
+you can have different implementations or versions of the same module
+and switch them out.
+An example of this is the module "serversetup-bwlp" which is symlinked
+as just "serversetup", so we can have "serversetup-cdn" in the future,
+as it seems the two locations have quite different requirements for this
+module's functionality.
+
+Note that a module identifier cannot contain dashes (-), so this is an
+easy way to hint that a module is supposed to be aliased when being
+activated.
diff --git a/doc/installation b/doc/installation
new file mode 100644
index 00000000..14fba625
--- /dev/null
+++ b/doc/installation
@@ -0,0 +1,28 @@
+Installation of slx-admin is modularized, that means there is no central,
+global SQL dump, but every module can provide an install hook, that is
+supposed to install everything it needs to the database (or anything else).
+
+The hook file is called install.inc.php and needs to reside in the module's
+root directory. Some modules might not have an install hook.
+
+A few simple helper functions are provided to make it easier to create
+tables, check for their existence, and create feedback of the installation
+process.
+
+It is important to make as little assumptions as possible about what is
+already present in the database, so try not to call functions like
+User::load() in your install hook. There might be no user table yet.
+
+The installation hook should be written in a way that it is non-destructive,
+and can recognize if an old version of the module's schema is already
+present in the database, in which case it should update the table(s)
+instead of erroring out or losing data. See the install hook of the
+'main' module for an example.
+
+Installation/Upgrading can be triggered manually through the browser
+by accessing "install.php" in slx-admin's root. Please note that this
+page does not require any form of authentication. While any actions
+this page can perform should not be destructive, you might want to
+consider moving the file away after each install/upgrade.
+The other way of triggering the process is running 'install-all' from
+the command line. This comes in handy for automated install scripts.
diff --git a/doc/javascript_css b/doc/javascript_css
new file mode 100644
index 00000000..de4896d5
--- /dev/null
+++ b/doc/javascript_css
@@ -0,0 +1,19 @@
+In order to prevent the global ./style/default.css from growing until
+it's a complete mess, it is also possible to modularize css stylesheets
+and javascript files.
+
+If a module contains a file called style.css, it is automatically included
+in the generated HTML page of the module, or any module that declared this
+module as a dependency.
+The same goes for a file called clientscript.js. Any module containing such
+a file will have this script included in the generated HTML.
+
+This way you can have module specific CSS definitions. Some of the
+definitions in ./style/default.css should be moved into modules over
+time (TODO :)), since they are only used in one module.
+
+Thanks to the dependency mechanism it is possible to have dedicated css/js
+modules, like "js_chart" or "js_circles". An example is the module
+"statistics", which defines js_chart as a dependency in its config.json.
+The result is that js_chart/clientscript.js is automatically included
+in the HTML output of the statistics module.
diff --git a/doc/main_page_warnings b/doc/main_page_warnings
new file mode 100644
index 00000000..e69a6125
--- /dev/null
+++ b/doc/main_page_warnings
@@ -0,0 +1,17 @@
+The warning messages that can appear on the main site (after logging in)
+can be added by hooks now, too, so the page.inc.php of the "main" module
+doesn't contain code specific to a dozen other modules.
+
+If you want to add a hook, create a file in your module:
+./modules/<module>/hooks/main-warning.inc.php
+The file contains flat code, no classes or functions. You should
+do your checks, and then call Message::addError (or the likes).
+You could also render your own template if you feel fancy.
+Remember you're running in the context of the main module, so your
+message ID should use the full syntax module.id, or add your
+module's name to the Render::addTemplate call.
+
+If you also want to enable the "configuration incomplete" global
+warning, set $needSetup to true.
+
+See modules "vmstore", "minilinux" or "sysconfig" for an example.
diff --git a/doc/module-dependencies b/doc/module-dependencies
new file mode 100644
index 00000000..3da27b16
--- /dev/null
+++ b/doc/module-dependencies
@@ -0,0 +1,31 @@
+Modules can define other modules as dependencies. You should do this
+whenever you require resources (like database tables) that belong
+to module A in module B, if you want to use automatic css/js
+inclusion (see javascript_css doc), or if you just feel like your
+module should not be accessible if another module is not present.
+
+"baseconfig_partitions_cdn" has "baseconfig" as a dependency; it
+does not directly access any tables of the module "baseconfig", but
+since it depends on the getconfig-API of the baseconfig module, one
+might argue that having the partition setup feature is of limited
+use if the clients can't fetch it.
+
+"statistics" module has "js_chart" as a dependency, since it
+makes use of the automatic clientscript.js inclusion. The statistics
+module uses the chart javascript library to draw, well, charts.
+
+
+You can write modules that can optionally interact or take advantage
+of other modules if they are present. The statistics module can
+make use of the locations module to show which location a client
+belongs to, but it would still work without the locations module
+being present. You can check for the availability of a module
+by calling Module::isAvailable('<module_name>')
+If the module is available, the call will return true, and
+the class autoloader for the requested module is also installed,
+so you can use any classes from ./modules/<module_name>/inc/*.inc.php
+Again, see how the statistics module calls Location::getFromIp()
+and other functions after calling Module::isAvailable().
+If you'd try to access Location::* without doing so, you'd get
+a class not found error.
+