Zuble Application Files

Application Directory Structure and Files

Application Directory

Zuble applications consist of a directory hierarchy containing QML source files, XML configuration files, and JSON data files. Optionally QML plugin modules may be included.

Each Zuble application has an application root directory that occupies the top directory level. All Zuble application root directories for a SNAP deployment are contained in the same parent directory. Within each application root directory three optional files control the configuration and initial execution of a Zuble application program. These are zblconfig.xml, main.qml, and settings metadata files.

The application directories are contained in the read-only area of the SNAP.

zblconfig.xml

This file determines what application resources to load for a Zuble application instance.

This XML file is loaded by zbl and by the QML documents zblmain, ContentPane and ContextPane. It specifies the following application components to be loaded at startup:

• Resource Bundles
• Page Theme Files
• Control Modules
• Menu Tools
• Workpads

Example zblconfig.xml file:

<?xml version="1.0" encoding="UTF-8" ?>

<zblconfig
xmlns="http://zuble.org/schema/zuble/zblconfig"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://zuble.org/schema/zuble/zblconfig
    zblconfig.xsd">

<settings>
<setting_bundle xml:id="test-bundle-1">
    <meta_path>qrc:///org/zuble/config/myappsettings.xml</meta_path>
    <data_path>data://myappsettings.json</data_path>
</setting_bundle>
</settings>

<styles>
  <style_path>zbl://darker-background.json</style_path>
  <style_path>zbl://lighter-background.json</style_path>
</styles>

<controller>
   <modules>
      <control_module module_name="org.zuble.apps.zlogger">
        <module_path>zbl://ZLoggerControl.qml</module_path>
     </control_module>
   </modules>
</controller>

<toolbox>

<menu_map>
    <menu_label>File</menu_label>
    <menu_name>stock.FileMenu</menu_name>
    <menu_path>FileMenu.qml</menu_path>
    <menu_mode>modeless</menu_mode>
</menu_map>
<menu_map>
    <menu_label>Details</menu_label>
    <menu_name>stock.logDetailMenu</menu_name>
    <menu_path>LogDetailMenu.qml</menu_path>
    <menu_mode>modeless</menu_mode>
</menu_map>
<menu_map>
    <menu_label>Search</menu_label>
    <menu_name>zlogger.searchMenu</menu_name>
    <menu_path>zbl://LogLinkMenu.qml</menu_path>
    <menu_mode>modeless</menu_mode>
</menu_map>
<menu_map>
    <menu_label>Style</menu_label>
    <menu_name>stock.StyleEditor</menu_name>
    <menu_path>StyleEditMenu.qml</menu_path>
    <menu_mode>modeless</menu_mode>
</menu_map>
<menu_map>
    <menu_label>About</menu_label>
    <menu_name>zlogger.AboutMenu</menu_name>
    <menu_path>zbl://MyAbout.qml</menu_path>
    <menu_mode>modeless</menu_mode>
</menu_map>
</toolbox>

<workspace>

    <workpad closeable="true">
    <!-- Zuble application settings -->
        <content_name>stock.AppSettings</content_name>
        <url>qrc:///org/zuble/qml/workspace/AppSettings.qml</url>
        <bk_color>green</bk_color>
        <menus>zlogger.AboutMenu</menus>
        <workpad_label>Settings</workpad_label>
    </workpad>

    <workpad>
        <content_name>stock.LogProfile</content_name>
        <url>qrc:///org/zuble/qml/workspace/LogProfilePage.qml</url>
        <bk_color>#25ad34</bk_color>
        <menus>stock.logCategoryMenu zlogger.AboutMenu</menus>
        <workpad_label>Log Control</workpad_label>
        <workpad_json>{"logController": "true"}</workpad_json>
    </workpad>

    <workpad>
        <!-- Histogram log view -->
        <content_name>stock.LogView</content_name>
        <url>qrc:///org/zuble/qml/workspace/LogView.qml</url>
        <bk_color>blue</bk_color>
        <menus>stock.logDetailMenu zlogger.searchMenu zlogger.bookmarkMenu zlogger.AboutMenu</menus>
        <workpad_label>Histogram</workpad_label>
        <workpad_json>{"logRecordMenuName": "stock.logDetailMenu", "histogram": true}</workpad_json>
        <menu_action>
            <action_target>stock.logDetailMenu</action_target>
            <action_label_open>Details</action_label_open>
            <action_label_close>Done</action_label_close>
            <action_visible>true</action_visible>
        </menu_action>
    </workpad>

</workspace>
</zblconfig>

main.qml

If this file exists it is loaded and executed by zbl instead of loading zblmain.qml from Zuble's core resource file. Use this configuration to override Zuble's workpad/toolbox window hierarchy and provide your own custom application window hierarchy. This configuration is appropriate for applications that build their own QML stack.

Settings Metadata Files

A settings metadata file is an XML file that specifies the application's settings group/names and default values. These are used by the ZSettings object to link settings metadata to a specific settings file. Zuble checks for these settings at application startup time and creates them with default values if they don't already exist.

Zuble provides the AppSettings workpad that displays settings files automatically based on input from a settings metadata file.

[TBD: This design conflates the definition of settings data with its presentation in the metadata file. That might not be an issue for simple cases but it's bad practice in general so we might want to revisit this. -rsd]

The following table describes the settings metadata format:

• Settings Idenfication
• Groups
• Items

Example Settings Metadata file:

<?xml version="1.0" encoding="UTF-8" ?>

<appsettings
    xmlns="http://zuble.org/schema/zuble/settings"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://zuble.org/schema/zuble/settings
    zublesettings01.xsd">

  <organization>zuble.org</organization>
  <name>Zuble</name>
  <setgroups>
     <setgroup xml:id="group-1">
         <name>Group One</name>
     </setgroup>
     <setgroup xml:id="group-2">
        <name>Group Two</name>
     </setgroup>
  </setgroups>

  <settings>
     <setting xml:id="captureMessages" group="group-1">
        <name>Message capture.</name>
        <type>bool</type>
        <default>false</default>
        <status>
           <state value="false">Disabled</state>
           <state value="true">Enabled</state>
        </status>
        <desc>Redirects messges to the status feed.</desc>
     </setting>

     <setting xml:id="test-setting-1" group="group-1">
        <name>Test Setting One</name>
        <type>string</type>
        <default>Yogi Bear</default>
        <desc>This is test setting one. Default is Yogi Bear.</desc>
     </setting>

     <setting xml:id="test-setting-2" group="group-2">
        <name>Test Setting 2</name>
        <type>string</type>
        <default>Bambi</default>
        <desc>This is test setting 2. Default is Bambi.</desc>
     </setting>

     <setting xml:id="choiceList-1" group="group-2">
        <name>Fruit Choice:</name>
        <type>choice</type>
        <default>apple</default>
        <choiceItems>
           <choiceItem>
              <name>Pear</name>
              <desc>Fruit of the Pyrus communis tree</desc>
              <value>pear</value>
           </choiceItem>
           <choiceItem>
              <name>Apple</name>
              <desc>Keeps the doctor away</desc>
              <value>apple</value>
           </choiceItem>
           <choiceItem>
              <name>Orange</name>
              <desc>Florida sunshine citrus fruit</desc>
              <value>orange</value>
           </choiceItem>
        </choiceItems>
        <desc>Choose a fruit from the selection. Default is apple.</desc>
     </setting>
  </settings>
</appsettings>

zblsettings.xml

If this file exists it is loaded by Zuble's settings manager. It's a special settings metadata file that specifies the application's settings group/names and default values. If this file exists it should contain Zuble's basic set of settings plus that of the specific application. If this file doesn't exist Zuble uses its own internal version of the file. In either case Zuble creates the settings automatically with default values the first time the Zuble application starts.

Data Directory

Zuble creates a data directory in the home directory of each Zuble application user. This directory, named .zuble, contains a separate data directory for each Zuble application that the user runs. Zuble applications can access this directory by using the data:// file prefix.

Zuble creates a set of data files for each running Zuble application. These include the following:

• Workspace Files
• Style Files
• Log Files
• Data files

Workspace Files

A workspace file (workpad-settings.json) contains the workpad configuration data for each currently opened workpad.

Style Files

Zuble users can create custom style files. These are stored in the the data directory.

Log Files

The Zuble log manager creates its log files in logs directory under the application data directory.

Data Files

Application specific data files are stored under the Zuble application's data directory.

Workpad Persistence

[some stuff about how workpad configuration settings are saved in settings files.]