Three steps for efficient theme development

The widgetbrowser application is used by the framework to showcase the widgets and the available themes. With the feature to switch the themes at run-time you can quickly get an overview of the theming capabilities of the desktop widget set.

So this should be a perfect match if you like to develop an own custom theme, right? Every widget is displayed within the widgetbrowser and this would help a lot to develop an own custom them from scratch.

To turn this into reality the widgetbrowser application got some enhancements and now it is very easy to use it for theme development. This little tutorial will show you the three steps you need.

Kickoff: Create a new application

We will demonstrate a desktop theme so we will create a desktop app here and integrate the widgetbrowser. If you are writing a theme for a different kind of app, then you have to use the corresponding type (i.e. mobile or website) during app creation and corresponding showcase app (i.e. Mobile Showcase or Website Widget Browser).

Creating a desktop skeleton is one command away:

# -t desktop could be omitted cause it's the default
create-application.py -t desktop -n <NAME_OF_YOUR_THEME>

Integration: How the widgetbrowser joins the game

Pulling in the widgetbrowser into your application is done by editing two files: the config.json and the Application.js of your demo application.

The configuration has to be edited like this (original values are commented out):

// Point the top-level include to the widgetbrowser configuration
"include" :
[
  {
    //"path" : "${QOOXDOO_PATH}/tool/data/config/application.json"
    "path" : "${QOOXDOO_PATH}/application/widgetbrowser/config.json"
  }
],


// Change the default theme of your application
"let" :
{
  // ...

  //"QXTHEME"      : "NAMESPACE.demo.theme.Theme",
  "QXTHEME"      : "NAMESPACE.theme.modern.Theme",

  // ...
}


// Add the widgetbrowser as library at the 'libraries' job
"libraries" :
{
  "library" :
  [
    {
      "manifest" : "../../Manifest.json"
    },

    {
      "manifest" : "${QOOXDOO_PATH}/application/widgetbrowser/Manifest.json"
    }
  ]
}


// Add a custom 'common' job right after the existing 'libraries' job
"common" :
{
  "packages" :
  {
    "parts" :
    {
      "boot" :
      {
        "include" : [ "${APPLICATION}.Application", "${QXTHEME}" ]
      }
    }
  }
}

With these modification you pulled the configuration of the widgetbrowser into your own application. Basically your application is now a kind of copy of the widgetbrowser. But wait: how about the JavaScript part?

Well this is done by editing the Application.js of your application. To keep it simple just replace your existing class by this:

qx.Class.define("NAMESPACE.demo.Application",
{
  // use the application class of the widgetbrowser as parent class
  extend : widgetbrowser.Application,

  /*
  *******************************************************************
     MEMBERS
  *******************************************************************
  */

  members :
  {
    // extend the 'getThemes' method and add your own theme to the list
    getThemes: function() {
      return ([
        {"Indigo" : "qx.theme.Indigo"},
        {"Modern" : "qx.theme.Modern"},
        {"Simple" : "qx.theme.Simple"},
        {"Classic" : "qx.theme.Classic"},
        {"new theme" : "NAMESPACE.theme.modern.Theme"}
      ]);
    }
  }
});

That's it! Run generate.py within the demo folder and open it in your favorite browser.

Final touch: Add your theme name and version

At the right upper corner of the widgetbrowser application you can easily replace the default name and version with your own to inform the user about the name of the theme and its version.

This is an additional minor adjustment in the config.json file:

// ...

// Add these lines to your 'common' job and adapt it to your needs
"environment" :
{
  "versionLabel.name" : "YOUR THEME NAME",
  "versionLabel.version" : "YOUR THEME VERSION"
},

// ...

Re-run the generate.py script to get this update into your application and enjoy!