View source for AppSuite:Creating a settings section in AppSuite settings

<div class="title">Creating a settings section in AppSuite settings</div>

This article explains how to add an settings section into AppSuite settings. You can also [[AppSuite:Embedding_your_settings_into_AppSuite_settings | implement your own settings using iframes]]. 


__TOC__ 

== Folder structure ==
Assuming you got an app or plugin in a folder like <code>com.example/helloWorld</code> for which you want to implement settings in AppSuite, you will need a new subfolder called <code>settings</code>. So <code>com.example/helloWorld/settings</code> will prospectively contain the files managing your settings.

== File Structure ==
=== Manifest ===
Creating a [[AppSuite:UI_manifests_explained | manifest]] is quite easy, writing the following into <code>com.example/helloWorld/settings/manifest.json</code> to load your settings, once AppSuite loads it's settings

<pre class="language-javascript">
{
    namespace: ['io.ox/settings/main']
}
</pre>

=== Defaults ===
<code>com.example/helloWorld/settings/defaults.js</code> should contain your default settings, so an example setting the variable <code>exampleBoolean</code> to <code>false</code> and <code>exampleInteger</code> to 15 might be
<pre class="language-javascript">
define('com.example/helloWorld/settings/defaults', [], function () {
    
    'use strict';

    // define the default values for your settings here
    var settingsDefaults = {
        exampleBoolean: false,
        exampleInteger: 15
    };

    return settingsDefaults;
});
</pre>

=== Model ===
<code>com.example/helloWorld/settings/model.js</code> contains an example of a simple default model, which you can use for your first settings

<pre class="language-javascript">
define('plugins/mail/AdvertOxMail/settings/model',
      ['settings!plugins/mail/AdvertOxMail'], function (settings) {

    'use strict';

    // Very simple default model
    var exampleModel = Backbone.Model.extend({
        initialize: function (options) {

        },

        save: function () {
            settings.save(this.attributes);
        },

        destroy: function () {

        }
    });
    return exampleModel;
});
</pre>

=== Register ===
Create a file called <code>com.example/helloWorld/settings/register.js</code> to extend the AppSuite settings and implement your own. 

The Head should look like this:
<pre class="language-javascript">
define("com.example/helloWorld/settings/register",
        ['io.ox/core/extensions',
         'settings!com.example/helloWorld'
         ],
         function (ext, settings) {
    'use strict';
</pre>

Extend the panel which stores the different setting categories:
<pre class="language-javascript">
    ext.point("io.ox/settings/pane").extend({
        id: 'com.example/helloWorld',
        title: 'Hello World Settings,
        ref: 'com.example/helloWorld',
        loadSettingPane: false,
        index: 400,
        lazySaveSettings: true
    });
</pre>

And now extend the extension point which was established through reffering to <code>com.example/helloWorld</code> above.
<code>(ref: 'com.example/helloWorld')</code>
<pre class="language-javascript">
    ext.point("com.example/helloWorld/settings/detail").extend({
        index: 50,
        id: 'extensions',
        draw: function () {
            var content=$('div').addClass('content');
            content.text('Add form elements to control your settings here');
            this.append(content);
        }
    });
});
</pre>

== Stuck somewhere? ==
You got stuck with a problem while developing? OXpedia might help you out with the article about [[AppSuite:Debugging_the_UI | debugging the UI]].