From 1873fa94f309b4acc2c16eea2b26387d540ae55f Mon Sep 17 00:00:00 2001 From: Simon Rettberg Date: Tue, 14 Jun 2016 17:13:54 +0200 Subject: Add documentation --- doc/baseconfig_-_config-variables | 42 +++++++++++++++++++++++++++++++++++++++ doc/dashboard | 20 +++++++++++++++++++ doc/enabling_modules | 16 +++++++++++++++ doc/installation | 28 ++++++++++++++++++++++++++ doc/javascript_css | 19 ++++++++++++++++++ doc/main_page_warnings | 17 ++++++++++++++++ doc/module-dependencies | 31 +++++++++++++++++++++++++++++ 7 files changed, 173 insertions(+) create mode 100644 doc/baseconfig_-_config-variables create mode 100644 doc/dashboard create mode 100644 doc/enabling_modules create mode 100644 doc/installation create mode 100644 doc/javascript_css create mode 100644 doc/main_page_warnings create mode 100644 doc/module-dependencies (limited to 'doc') 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//baseconfig/categories.json: Defines categories for +configuration variables. Syntax is : + +./modules//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//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//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('') +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//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. + -- cgit v1.2.3-55-g7522