Developers/Concepts/Configuration

From Tine 2.0 - Wiki

< Developers
STATUS: PARTLY IMPLEMENTED (SETUP UI MISSING)
RELEASED IN: MILAN


Config

Configuration deals with the administrative parameters which configure Tinebase and all the Applications. This is in contrast to Preferences which deals with parameters each user prefers.

Configuration is set on different places

  1. config.inc.php absolute core configurations like database connection and logging. Needs filesystem access and a text editor.
  2. Application/config.inc.php overwrites config for this application, useful for feature switches config
  3. setup.php core configurations for hosters like mail and ldap. Needs Setup login credentials.
  4. Admin->Appname->Config admin configurations. Needs Tine 2.0 login and right to set the corresponding config (Mostly 'Appname admin right').

Config Definition

Config definitions are done in PHP code. Each application comes with a Appname_Config class wich defines:

  • name
  • label
  • description
  • type {string|int|dateTime|array|record}
    • type array has a optional contents field to define whats in that numeric indices array (defaults to string)
    • types record and recordSet require a model field to define record types
  • clientRegistryInclude boolean flag if this config should be included in the client registry
  • default value
  • code interceptors on read/set
  • comment translations for name and description
  • 'setByAdminModule' : can be set in admin module (Applications/Settings)
  • 'setBySetupModule' : not implemented yet - can be set in setup gui

NOTE: Non scalar config types must have their own models!

Config Values

Config values are stored in db config table:

  • id
  • applicationId
  • name
  • value JSON encoded for non scalar values

If a config name/key is present in config.inc.php it overwrites the database value.

Registry

Configs, the user has read rights for are available in the users registy data. For this, the config API gets all config names/keys from the PHP definitions, fetches all values from DB at once and passes them to the code interceptions.

Admin_Frontend_Json

Admin Config is always done via the Admin front end using the two admin APIs:

  • Admin_Frontend_Json::getConfig($appname) gets all definitions and values for given application.
  • Admin_Frontend_Json::setConfig($appname, $key, $value) sets all values for given application.

The admin JSON frontend ensures that non scalar data instances a corresponding model via setFromJsonInUsersTimezone.

Admin Configuration Javascript UI

The Admin Config UI is build automatically from the config definitions. To Overwriting/Implementing a custom UI you need to create a panel named Appname.config.configkeyPanel

Feature Toggles

Feature Toggles have been introduced in 2014.09 Koriander version and allow to switch on/off certain features.

Definition

A feature toggle is defined in the APP_Config file like this:

protected static $_properties = array(
 self::ENABLED_FEATURES => array(
           //_('Enabled Features')
           'label'                 => 'Enabled Features',
           //_('Enabled Features in Calendar Application.')
           'description'           => 'Enabled Features in Calendar Application.',
           'type'                  => 'object',
           'class'                 => 'Tinebase_Config_Struct',
           'clientRegistryInclude' => TRUE,
           'content'               => array(
               self::FEATURE_SPLIT_VIEW => array(
                   'label'         => 'Calendar Split View', //_('Calendar Split View')
                   'description'   => 'Split day and week views by attendee', //_('Split day and week views by attendee)
               ),
           ),
           'default'               => array(
               self::FEATURE_SPLIT_VIEW           => true,
           ),
       ),
  [...]
);

each feature should have a constant:

    /**
    * FEATURE_SPLIT_VIEW
    *
    * @var string
    */
   const FEATURE_SPLIT_VIEW = 'featureSplitView';

===Get/Set Configuration

Show current value of feature toggle config:

vagrant@precise32:~$ php -d include_path=/vagrant/conf /vagrant/tine20.git/tine20/setup.php --getconfig configkey="features" app=Calendar
{"featureSplitView":true} 


You may set the enabled/disabled features configuration by using the CLI (this one disables the split view):

vagrant@precise32:~$ php -d include_path=/vagrant/conf /vagrant/tine20.git/tine20/setup.php --setconfig configkey="features"  configvalue={"featureSplitView":false} app=Calendar


Usage In PHP Code

if (Calendar_Config::getInstance()->featureEnabled(Calendar_Config::FEATURE_SPLIT_VIEW)) {
   // do something if the feature is enabled
}

Usage In JavaScript Code

"normal" applications:

if (Tine.Tinebase.appMgr.get('Calendar').featureEnabled('featureSplitView')) {
   // do something if the feature is enabled
}

Tinebase:

       // need to create a "dummy" app to call featureEnabled()
       // TODO: should be improved
       var tinebaseApp = new Tine.Tinebase.Application({
           appName: 'Tinebase'
       });
       this.advancedSearchEnabled = (tinebaseApp.featureEnabled('featureShowAdvancedSearch'));