qooxdoo WYSIWYG UI Editor

Type: qooxdoo editor project to be used as dependency for own projects

(FYI: english description only)

Compatibility: qooxdoo 5.x

Playground: current editor build

Info

There are many HTML5/CSS3 UI frameworks out there, one of those is the qooxdoo framework. This framework supports among other things the development of HTML5/CSS3 SinglePage Web Applications and is especially easy to use because it provides the possibility to develop exclusively in Javascript/JSON which in itself doesn’t require any knowledge of HTML5/CSS3. Instead of HTML thinking the UI is developed using the more programmatical approach of containers, layouts and widgets. Furthermore the framework provides a reflection like concept for widget attributes, be those default or user specific ones, which is why an editor building on that reflection was possible in the first place. Using reflection of those attributes (properties in qooxdoo terms) the editor is able to handle custom built widgets with all the properties generically, without any special code.

Editor features:

  • free of charge (using qooxdoo, PouchDB if needed) and open source
  • What-You-See-Is-What-You-Get functionality providing the fastest possible way to try out and build new layouts
  • can and should be used as dependency project for own qooxdoo projects incorporating own themes and widgets
  • layout provider modules for handling of layouts incl. following default providers:
    • in-memory provider for testing only (volatile Javascript memory)
    • browser local cache provider for testing only (volatile user’s browser cache memory)
    • PouchDB provider using user’s browser cache for local layouts, but also supports synchronization with a remote CouchDB server
    • remote repository provider for communicating with a file service (also provided inside the sample project)
      • the service provides storing layouts as JSON files and baking a JS qooxdoo class containing all those layouts in production version environment
  • switching of qooxdoo themes (FYI qooxdoo theme switching at runtime can be quite limited, but after some adjusting of local qooxdoo version could still be very useful)
  • switching of locales auto-translating any string values starting with “trn:” (using the .po functionality of qooxdoo)
  • importing of existing qooxdoo layouts from running code (helps to migrate existing UI code to JSON layouts)
  • hierarchy tree view of current layout with drag&drop in the tree and with the copy&paste&etc. functionality usually found in UI editors
    • dummy content and using of nested layouts for better wysiwyg view of a layout (content is omitted on loading the layout in code)
  • sub hierarchy view for complex properties like “decorator” (e.g. provides a possibility to try a decorator in wysiwyg before defining it in the theme files)
  • generic property view of all widget properties with property “check” detection (i.e. a “string” will be represented by a textfield, “bool” by checkbox etc.)
    • provides a possibility to mark elements with an ID to get elements for runtime access later in code (better separation of UI and controlling)
    • provides wysiwyg Decorator/Color/Font view in the corresponding properties’ selectboxes
  • wysiwyg view of the current layout incl. viewport size and background color settings
    • provides possibility to view generated JSON code of current layout and/or currently selected hierarchy
    • provides possibility to view generated JS code of current layout and/or currently selected hierarchy

Editor limitations:

  • Complex and non-conform layouts and widgets can’t be used inside of the layout (e.g. Grid layout, Table widgets and similar)

Download

  • Current release
    • FYI expects qooxdoo 5.x to be found at ”../../../download/qooxdoo-5.0.1-sdk/qooxdoo-5.0.1-sdk” (alternatively edit config.json files)

Documentation

The editor should be self explanatory to some extent, but it’s role in the development process can vary in complexity depending on the expected impact. Following sections should provide some insight into how the editor is expected to be used and also a short tutorial regarding building a UI module in the editor.

Preferred Approach

The editor was built with the following development chain in mind:

  • Most layouts in the projects are to be designed using the editor
  • Developing Phase: Every single layout is to be saved as JSON file in the project
    • the JSON files are non-minified versions i.e. adding the files to versioning system is advisable and provides diff functionality
    • the JSON files should be added to development environment to be able to e.g. search globally for a resource or translation etc.
    • while creating layouts in the editor the elements later needed by the code should be marked with an ID (see tutorial further below) so that they can be extracted later in code
  • Production Phase: all JSON files are used to bake a single auto-generated JS file essentially generating a real qooxdoo class
    • the autogenerated JS file shouldn’t be added to versioning system and should be generated in the autobuild pre-project-build process
    • the autogenerated JS file, being a qooxdoo class, will be incorporated into the single JS script file on qooxdoo build which eliminates the need to do any requests at runtime in the Production version of the project

Alternatively both phases could use e.g. the PouchDB provider module incl. synchronizing with a CouchDB server in which case in Production version every client could get all JSON layouts on every startup of the page and construct JS functions on the fly (it is of course strongly advised to use different CouchDB sub-hierarchies for different branch versions). This adds quite a bit of complexity, but also the possibility to slightly change layouts of runtime clients on the fly.

Conceptual Example

Let’s assume the preferred approach was used and the development chain is already working, this is how the process would look like in a team:

  • Task: create a layout for registering a user (name, surname, email, submit button)…
    • Developer: creates UI in editor and adds functionality
      • open editor
      • create new UI layout with only the needed elements and mark those elements by giving IDs “textfield_name”, “textfield_surname”, “textfield_email”, “btn_submit”
      • save new UI under a new name e.g. “registration_user”
        • the file service creates the corresponding file
        • the file service also starts the bake JS file process which creates/overwrites the qooxdoo class containing the layouts for runtime loading
          • this file now contains a static function with name “registration_user(…)”
      • add the created file “registration_user.json” to project and to versioning system
      • signal UI Designer and/or ART team
      • now build project, reload page and start writing the functionality as loading can already be done and the elements needed by the developer are already in place
    • UI Designer, ART team: after Developer signalled that the new UI is available…
      • update project, build, reload page, open editor
      • start working on the UI adding all the theming, decorating and flavor according to corporate design
      • make sure that the elements marked by the Developer are not removed from the UI
  • Result: the business process of creating a new UI layout and adding the functionality is optimized though separation of concerns and parallelization

Setup

The provided download (see above) contains following modules:

  • FYI please make sure to download the qooxdoo 5.x source and place it in the configured path (see config.json files in the projects) or alternatively edit the configuration
  • /editor/ – the Editor project, meant to be used as dependency in own qooxdoo projects
    • /<source | build>/library/<pouchdb-5.1.0.js | pouchdb-5.1.0.min.js> – PouchDB dependency needed by the LayoutProviderJsonPouchDb.js provider code
      • FYI this module is entirely optional
    • /source/class/editor/
      • /editor/ – qooxdoo code for the editor and layout providers
      • /theme/ – theming code for the editor (FYI extends qx.theme.modern theme and uses qx.theme.icon.Tango package, change it appropriately if needed)
      • /widget/ – some widgets used in the editor (FYI can also be used as reference to how custom widgets can be done and themed)
  • /editor_example_project/ – a sample project showing how to use/extend the editor project and including a couple of tests providing code insight into loading layouts
    • /fileservice/ – contains a service providing communication for LayoutProviderJsonService.js and functionality for baking JSON layouts to a single qooxdoo JS class file
      • see also autogenerate_qxlayoutfile.batplease_adminmode_startservice.bat and fileservicecfg.json
      • FYI the service is started manually as command line application and can be stopped by any input (followed by ENTER), it is NOT a Windows service
      • FYI fileservicecfg.json provides enough reference to see what the service is writing to, make sure your project is configured correspondingly
    • config.json – check this out and other qooxdoo configuration files to make sure your project is configured in a similar way
    • /source/class/editor_example_project/
      • /theme/ – check this out for reference of how to use extend own theme(s) using the editor theme
        • the editor’s theme is basically an interim theme between default qooxdoo and your custom themes
      • /widgets/WidgetAnimatedContent.js – this widget class is used to show that the editor can work with custom widgets and its’ properties
      • /layout/ – due to configuration in fileservicecfg.json contains the JSON layout files as well as the baked JS qooxdoo class file
      • Application.js – check this out for in-code test descriptions and code

This should be enough to get started with an own project which can be configured properly with the editor_example_project as point of reference.

Short Tutorial

Let’s assume that the setup above is done and that the task from the conceptual example further above is to be implemented, here are the more detailed steps:

  • …open editor
  • Top section: click “New…” on the left
    • note: a Composite (VBox) is created as root
  • Left section: click “Widget: #” selectbox, type “textf”, select “qx.ui.form.TextField”, then click the icon button directly below with tooltip “Insert new…”
    • note: a TextField is added into the root and auto-selected
  • Middle section: in the “Special” area there is “Code ID:” textfield – enter “textfield_name”
    • note: the element is now green in the tree denoting it as extractable
    • note: on the bottom left there is a selectbox providing a quick goto selection for all elements marked by an ID
  • Middle section: in the “Properties” area search for “placeholder:” property and enter “Enter name…”
  • …add 2 more textfield elements setting IDs to “textfield_surname” and “textfield_email” and appropriate placeholders
  • Left section: click “Widget: #” selectbox, type “button”, select “qx.ui.form.Button”, then click the icon button directly below with tooltip “Insert new after…”
    • set ID “btn_submit”
    • set property “label:” to “Submit”
  • Top section: in the middle left of “Save” button enter the name “registration_user” and click “Save”
    • note: on success there is now a corresponding file in the project and the autogenerated files was also created/overwritten
  • …now open code and in the code section where the UI would usually be constructed and/or added:
    • var rootContainer = editor.editor.Loader.getInstance().getLayout(“registration_user”);
    • …you can now add this container to wherever it is needed
    • var tfName = editor.editor.Loader.getInstance().getElement(rootContainer, “textfield_name”);
    • var tfSurname = editor.editor.Loader.getInstance().getElement(rootContainer, “textfield_surname”);
    • var tfEmail = editor.editor.Loader.getInstance().getElement(rootContainer, “textfield_email”);
    • var btnSubmit = editor.editor.Loader.getInstance().getElement(rootContainer, “btn_submit”);
    • note: it is very advisable to use translation for the text values, the editor tries to auto-translate any string starting with prefix “trn:” in the editor views as well as on loading of the layout
      • translation chain explanation:
        • use “trn:…” as value in the corresponding property
        • save layout, layout gets baked into the JS qooxdoo class file
        • the JS file on next build and/or translate qooxdoo job will add the to be translated entries to the .po files
        • add translation in .po files
        • run build and/or translate again
        • when you load the layout after all of that the translation should be already visible
    • …and that is all that is needed to inflate the layout and to get the widgets that are needed, there is no more manual unnecessary UI constructing Javascript code
  • …now let’s assume that ART created assets and decorators (we’ll use one from the editor project) and the UI designer wants to implement the design
  • open editor and load the layout
  • Left or Right section: click on a textfield
  • Middle section: under Properties.Deco: area search for “appearance:” and set it to “uied-textfield” (it would be one of your appearances)
    • note: you have to know about qooxdoo theming at that point, but basically for an interactive widget like a textfield there are a couple of decorators which are static looks and an appearance which switches those decorators according to widget states (i.e. there are decorators for hovered, focused, disabled etc. and combinations of those states)
    • note: sadly appearances can’t be viewed with a representable selectbox i.e. you have to know which are there to use for the current widget class
  • repeat for the other 2 textfields
  • select the button and set appearance “uied-button-standard”
  • select the root composite
    • under “Layout:” set “spacing:” to e.g. 3
    • under “Padding:” set paddings to e.g. 2
    • under “Deco:” select “decorator:” e.g. “uied-pane-dropdown”
  • save the layout
  • note: you can switch to JSON view in the right section where you can see that JSON attributes are only saved for non-default values saving a lot of space in the usually very verbose JSON

And that’s it for a short walkthrough. Feel free to try and see through all other sections and properties in the editor.

3 Responses to qooxdoo WYSIWYG UI Editor

  • Pingback: qooxdoo WYSIWYG UI Editor (HTML5/CSS3) | devdroy.com

  • very good.

    not found this section ………..

    …now open code and in the code section where the UI would usually be constructed and/or added:
    var rootContainer = editor.editor.Loader.getInstance().getLayout(“registration_user”);
    …you can now add this container to wherever it is needed
    var tfName = editor.editor.Loader.getInstance().getElement(rootContainer, “textfield_name”);
    var tfSurname = editor.editor.Loader.getInstance().getElement(rootContainer, “textfield_surname”);
    var tfEmail = editor.editor.Loader.getInstance().getElement(rootContainer, “textfield_email”);
    var btnSubmit = editor.editor.Loader.getInstance().getElement(rootContainer, “btn_submit”);

    …………………

    is possible to write one screencast and send by youtube.

    tanks

    • admin says:

      Heyho, I didn’t do anything with qooxdoo since the time the article went live, but I believe what I meant was: wherever your actual component code is – that’s the place you load the rootContainer and then add the rootContainer to your component.

Leave a Reply

Your email address will not be published. Required fields are marked *

*

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>