=====================================
Configuring an XGEE Application
=====================================

An XGEE application is assembled from jsApplication plug-ins. The plug-ins
that are loaded at startup, and their application-specific options, are
configured in the ``PLUGIN CONFIG`` block in ``App/index.html``. This page
describes configuration that is useful for adapting the XGEE Example
Application to a new modeling project.


Configuring the Start Modelling Dashboard
------------------------------------------

The ``view.dashboard.startModellingDash`` plug-in adds a starting point for
modeling to a dashboard view. It lets users:

* browse models and directories
* open models in XGEE editors
* create new models from a template
* delete and rename models and directories

The dashboard observes the current workspace directory. Its model and
directory lists therefore update when the workspace changes.


Example configuration
~~~~~~~~~~~~~~~~~~~~~

Enable the plug-in in the ``PLUGIN CONFIG`` block in ``index.html`` and
configure at least one instance:

.. code-block:: javascript

    'view.dashboard.startModellingDash': {
        enabled: true,
        config: {
            instances: [
                {
                    name: 'System modeling',
                    modelSuffix: '.oaam',
                    existingSectionLabel: 'Continue modeling',
                    createNewSectionLabel: 'Create system model',
                    createTemplate: 'templates/OAAMTemplate.oaam',
                    preferredEditors: [
                        'Functions Editor',
                        'Hardware Editor',
                        'Allocations Editor'
                    ],
                    autoOpenOnlyClasses: [],
                    row: 0,
                    tiles: 6,
                    position: 1,
                    dashboardId: '#DASHBOARD',
                    ecoreSyncId: 'ecoreSync'
                }
            ]
        }
    },

Each object in ``instances`` creates a separate Start Modelling panel. This
makes it possible to place panels for different model types or workflows on
the same dashboard.


Configuration options
~~~~~~~~~~~~~~~~~~~~~

========================= ===================================================
Option                    Purpose
========================= ===================================================
``name``                  Heading displayed for the panel.
``modelSuffix``           File suffix used to select the workspace resources
                          shown in the panel, for example ``.oaam``.
``existingSectionLabel``  Heading above directories and existing models.
``createNewSectionLabel`` Heading above the actions for creating models and
                          directories.
``createTemplate``        Workspace path of a model which is copied
                          into every newly created model.
``preferredEditors``      Editor names in activation priority order. All
                          applicable editors are opened; the first matching
                          preferred editor becomes active.
``autoOpenOnlyClasses``   By default an empty list: editors for all supported 
                          classes are opened. If non-empty, only editors for 
                          these class names are opened. 
``row``                   Zero-based dashboard row containing the panel.
``tiles``                 Panel width in dashboard tiles, from 1 to 12.
``position``              Ordering within the row; lower values appear first.
``dashboardId``           Identifier of the dashboard that receives the
                          panel, including its leading ``#``.
``ecoreSyncId``           Identifier of the ``ecoreSync`` instance used to
                          read and modify workspace resources.
========================= ===================================================


Runtime behavior
~~~~~~~~~~~~~~~~

The panel initially shows the directories below the current workspace
location and resources whose names end in ``modelSuffix``. Hidden directories,
whose names start with a dot, are omitted. Selecting a directory navigates
into it; the parent entry navigates back up.

``Create new model`` chooses the first free name based on ``newModel`` and
``modelSuffix``. For example, it creates ``newModel.oaam`` and then
``newModel0.oaam`` if the first name is already in use. When
``createTemplate`` is set, the template's model contents are copied into the
new resource. The template itself is not modified. ``Create new sub
directory`` uses the same naming strategy with ``newSubdir``.

When an existing model is selected, the panel finds model elements supported
by the loaded XGEE editors. ``autoOpenOnlyClasses`` can restrict which element
classes are opened. After all applicable editor views have opened, the first
view matching ``preferredEditors`` is activated. If there is no preferred
match, the first opened editor is activated. XGEE displays a warning when the
model contains no elements supported by a specialized editor.

After changing ``index.html``, reload the application with the browser
cache disabled so that the updated startup configuration is used.