tyler.durden
/
icingaweb2
mirror of https://github.com/Icinga/icingaweb2.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

doc: Remove developer information from preferences.md

This commit is contained in:
Eric Lippmann 2014-12-18 15:40:26 +01:00
parent 53179981d6
commit 0bcda60dab
1 changed files with 35 additions and 83 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

118
doc/preferences.md
View File

@ -1,101 +1,53 @@
# Preferences # <a id="preferences"></a> Preferences
Preferences are user based configuration for Icinga Web 2. For example max page Preferences are settings a user can set for his account only, for example his language and time zone.
items, languages or date time settings can controlled by users.
# Architecture **Choosing Where to Store Preferences**
Preferences are initially loaded from a provider (ini files or database) and Preferences can be stored either in INI files or in a MySQL or in a PostgreSQL database. By default, Icinga Web 2 stores
stored into session at login time. After this step preferences are only preferences in INI files beneath Icinga Web 2's configuration directory.
persisted to the configured backend, but never reloaded from them.
# Configuration ## <a id="preferences-configuration"></a> Configuration
Preferences can be configured in config.ini in **preferences** section, default Where to store preferences is defined in the INI file **config/config.ini** in the *preferences* section.
settings are this:
[preferences] ### <a id="preferences-configuration-ini"></a> Store Preferences in INI Files
type=ini
The ini provider uses the directory **config/preferences** to create one ini If preferences are stored in INI Files, Icinga Web 2 automatically creates one file per user using the username as
file per user and persists the data into a single file. If you want to drop your file name for storing preferences. A INI file is created once a user saves changed preferences the first time.
preferences just drop the file from disk and you'll start with a new profile. The files are located beneath the `preferences` directory beneath Icinga Web 2's configuration directory.
## Database Provider For storing preferences in INI files you have to add the following section to the INI file **config/config.ini**:
To be more flexible in distributed setups you can store preferences in a ```
database (pgsql or mysql), a typical configuration looks like the following [preferences]
example: type = ini
````
[preferences] ### <a id="preferences-configuration-db"></a> Store Preferences in a Database
type=db
resource=icingaweb-pgsql
## Null Provider In order to be more flexible in distributed setups you can store preferences in a MySQL or in a PostgreSQL database.
For storing preferences in a database, you have to define a [database resource](#resources-configuration-database)
which will be referenced as resource for the preferences storage.
The Null Provider discards all preferences and is mainly used as a fallback when no provider could be Directive | Description
created (due to permission errors, database outtakes, etc.). ------------------------|------------
**type** | `db`
**resource** | The name of the database resource defined in [resources.ini](resources).
[preferences] **Example:**
type=null
If your preferences aren't stored it's best to take a look into the logfiles - errors during the preference setup ```
are displayed as warnings here. [preferences]
type = db
resource = icingaweb-mysql
```
### Settings #### <a id="preferences-configuration-db-setup"></a> Database Setup
* **resource**: A reference to a database declared in *resources.ini*. Please read the chapter about For storing preferences in a database, you have to import one of the following database schemas:
resources for a detailed description about how to set up resources.
### Preparation * **etc/schema/preferences.mysql.sql** (for **MySQL** database)
* **etc/schema/preferences.pgsql.sql** (for **PostgreSQL** databases)
To use this feature you need a running database environment. After creating a After that you have to define the [database resource](#resources-configuration-database).
database and a writable user you need to import the initial table file:
* etc/schema/preferences.mysql.sql (for mysql database)
* etc/schema/preferemces.pgsql.sql (for postgres databases)
#### Example for mysql
# mysql -u root -p
mysql> create database icingaweb;
mysql> GRANT SELECT,INSERT,UPDATE,DELETE ON icingaweb.* TO \
'icingaweb'@'localhost' IDENTIFIED BY 'icingaweb';
mysql> exit
# mysql -u root -p icingaweb < /path/to/icingaweb/etc/schema/preferences.mysql.sql
After following these steps above you can configure your preferences provider.
## Coding API
You can set, update or remove preferences using the Preference data object
which is bound to the user. Here are some simple examples how to work with
that:
$preferences = $user->getPreferences();
// Get language with en_US as fallback
$preferences->get('app.language', 'en_US');
$preferences->set('app.language', 'de_DE');
$preferences->remove('app.language');
// Using transactional mode
$preferences->startTransaction();
$preferences->set('test.pref1', 'pref1');
$preferences->set('test.pref2', 'pref2');
$preferences->remove('test.pref3');
$preferemces->commit(); // Stores 3 changes in one operation
More information can be found in the api docs.
## Namespaces and behaviour
If you are using this API please obey the following rules:
* Use dotted notation for preferences
* Namespaces starting with one context identifier
* **app** as global identified (e.g. app.language)
* **mymodule** for your module
* **monitoring** for the monitoring module
* Use preferences wisely (set only when needed and write small settings)
* Use only simple data types, e.g. strings or numbers
* If you need complex types you have to do it your self (e.g. serialization)