# Config library (JavaScript)

The JavaScript Config library is the counterpart of the C++ Config library. Both parts are communicating to each other using an active appwebsocket connection. Each config item defined on the C++ side will be mapped to the JavaScript part. So if e. G. the app-service has a config item with the name "enableSync", the same field will exist on the JavaScript side after the first synchronization between them. Password fields will be automaticaly encrypted and decrypted and number fields with min / max values will be handled correctly. Please note that for security reasons, the C++ side will never send a password back to the JavaScript library.

## File information

File | web/config/innovaphone.config.js
Objects | innovaphone.Config
Examples | Config Sample

# Objects

## innovaphone.Config

    var innovaphone = innovaphone || {};
    innovaphone.Config = innovaphone.Config || function() {
        function save() {}
        function getItemsChoices(itemName) {}
        function init(appWebsocket) {}

        this.evOnConfigItemsReceived = new innovaphone.lib1.Event(this);
        this.evOnConfigLoaded = new innovaphone.lib1.Event(this);
        this.evOnConfigUpdate = new innovaphone.lib1.Event(this);
        this.evOnConfigSaveResult = new innovaphone.lib1.Event(this);

        this.save = save;
        this.getItemChoices = getItemChoices;
        this.init = init;
    }

### Public functions

init
  Initializes the object by requesting the config items and the current configuration from the C++ Config library.

  #### Parameters

  appWebsocket | An active an already connected appWebsocket object.

  #### Events

  After init and receiving data, the following events will be raised (in the order below):
  - evOnConfigItemsReceived
  - evOnConfigLoaded

  #### Remarks

  Because init() directly starts to communicate with the C++ part, it must be called after the appWebsocket object is connected. So onAppConnected of appWebsocket will be a good place to call init(). See appWebsocket for details.
  After the config items had been received, evOnConfigItemsReceived will be raised.
getItemChoices
  The C++ library provides an config item with type choice. Those items have a list of choices. After receiving the items (noted by the evOnConfigItemsReceived event), the list of a choice item can be accessed using getItemChoices.

  #### Parameters

  itemName | The name of the item to get the choices from.

  #### Return value

  If the item given in itemName exist and is a choice item and have a list of choices, getItemChoices() returns a JavaScript array with all the choices of the items. Else null will be returned.
save
  An app can also change config values (as long as they are not defined as unmanaged - see the C++ Config library docu for details). Calling save() will send the items to the app-service and let the service save them to the database.

  #### Events

  The function will lead to a evOnConfigSaveResult event.

### Public events

evOnConfigItemsReceived
  This event will be raised after calling init() and after the config object has received the list and types of config items, including the list of choices for the choice-items. This event is only called once, after the initialization is complete. This event will pass one parameter to an attached event handler.

  #### Parameters

  sender | The sender of the event.

  #### Remarks

  Please note that when receiving this event, the current config itself still had not been loaded. This will noticed by the evOnConfigLoaded event.
  When this event had been realised, the innovaphone.Config instance will have a property for each config item on the C++ side. The name of the property is the same as the name of the config item defined from the app service. See the C++ Config library docu for details.
evOnConfigLoaded
  This event will be raised when the config object has received the config values from the app-service side. The event will pass one parameter to an attached event handler.

  #### Parameters

  sender | The sender of the event.

evOnConfigUpdate
  After changes on the C++ Config side (for example, by an other instance of an app which edited the config), the config items will be sent to the Config object and the evOnConfigUpdate event will be raied. You have to check each config item available to figure out, which one had been updated.

  #### Parameters

  sender | The sender of the event.

evOnConfigSaveResult
  After calling save() and after the config had been saved to the database on the app-service side, this event will be raised. The event will pass two parameters to an attached event handler.

  #### Parameters

  sender | The sender of the event.
  result | True, if the config had been saved successfully, else false.

  #### Remarks

  Note that the only information about saving the config is, if it was successful or not. In case of doubts, more informations can be found inside the app-services log (if logging the config is enabled). See the C++ Config library docu for details.

# Code Example

Config Sample

    // Let assume, that the appWebsocket initialization alrady have been done.
    // Let's also assume, that there are two config items on the apps-service side:
    //
    //    activeLog (bool)
    //    logType (Choice: DB, TXT, CSV)
    //
    var config = null;

    appWebsocket.onconnected = onAppWSConnected;

    function onAppWSConnected(appWebsocket) {
        config = new innovaphone.Config();
        config.evOnConfigItemsReceived.attach(onConfigItemsReceived);
        config.evOnConfigLoaded.attach(onConfigLoaded);
        config.evOnConfigSaveResult.attach(onConfigSaveResult);
        config.evOnConfigUpdate.attach(onConfigUpdate);
        config.init(appWebsocket);
    }

    function onConfigItemsReceived(sender) {
        var choices = config.getItemChoices("logType");
        console.log("Choices available for logType = " + choices);
    }

    function onConfigLoaded(sender) {
        console.log("Logging activated: " + config.activeLog ? "YES" : "NO");

        var choices = config.getItemChoices("logType");
        consoleLog("Log Type          : " + choices[config.logType]);

        config.activeLog = !config.activeLog;
        config.save();
    }

    function onConfigUpdate(sender) {
        console.log("Config updated");
    }

    function onConfigSaveResult(sender, result) {
        console.log("Config save-result: " + result);
    }