Table of contents

About JUL Designer

JUL Designer is a RAD tool used to visually build a JavaScript application.
Given a component based application running in an event-driven environment, JUL Designer helps you to generate the component tree with the attached event listeners. It also generates the JavaScript code for the current component tree.

Features

  • visually building and live testing a JavaScript application
  • working with your preferred JavaScript component framework
  • can be used with tag based languages (HTML, XUL, SVG etc.)
  • generates the JavaScript code with option to separate UI layout and logic
  • copy, paste and undo operations for the components and their members
  • downloading generated code, exporting XML layout

System requirements

You may download the desktop application OR:

  • a CSS2 compliant web browser with JavaScript 1.5 or later engine
  • Node.js 0.10.0 or later installed
  • OR a web server with PHP 5.2.0 or later extension
  • 1024x768 minimum resolution

Installation for Node

Unpack the distribution archive to a directory of your choice. Run the following shell/command prompt commands:

npm install
npm start

Navigate to the address http://localhost:7770/ using a web browser. The examples and other assets will be automatically installed with the first use of the application.

Installation for PHP

Unpack the distribution archive to a directory of your web site. If necessary, give the web server process write permissions over the 'assets' directory (e.g. on Linux type as root: chmod 777 assets or chown www-data assets). Navigate to the installation directory using a web browser. The examples and other assets will be automatically installed with the first use of the application.

Back to top

Application, modules and projects

An application is an HTML page that loads a set of style and script resources to render a complete and useful user interface (UI). The parts of the UI that have an autonomous structure and behavior are called modules and usually reside inside separate source files. In JUL Designer, a module is a separate JavaScript file that generates a part of the UI. The module has a specific parser that iterates over a configuration tree to generate the interface. More details about generation of UI from a configuration can be found in the articles about JUL.
You can create an application from the "New application ..." menu. The default parser configuration of the application will be copied for any new module using the 'Switch module' menu. The application has a customizable template page that loads the module scripts in the appropriate order. It also has an initialization routine that can be customized and that, by default, calls each module's parser to create the module UI.
A module is identified by a namespace which is a dotted string representing the path to the JavaScript configuration root object of the module. The namespace can start with a dot, meaning that it is relative to the application's namespace. Each module corresponds to one JUL Designer project which is used to visually build the module source file. When switching to a new module, the 'New project' dialog appears to facilitate the creation of the project associated with the module.

Back to top

Building a new project

A project is a component tree that, when instantiated, creates the JavaScript application.
In order to achieve this, JUL Designer generates the required JavaScript code on the fly, at every step when you are building the project. You can see and copy the code from the menu Project -> View JavaScript.
Adding components to the component tree requires that you also configure the current framework to work with. To do this, please take a look at the topic about frameworks.

Project settings

The project settings are:

  • title (string) - the title of the project
  • ns (string) - a unique dotted path that is the JavaScript namespace of the project. See more at Namespaces topic.
  • init (function) - an entry point for launching the project. See the default value for a starting point.
  • suggestedFramework (string) - a dotted path which is the JavaScript namespace of the framework to open when opening this project.
  • listenersProperty (string) - for an event-driven environments, the event listeners for each component will be grouped under this property
  • noLogic (boolean) - do not separate logic from UI in the generated JavaScript code. This can be switched also during the project building from the menu Project -> Don't separate logic.

Parser settings

These are the settings that allow the JUL parser to create and instantiate the component tree.

  • classProperty (string) - the name of the class property of the component
  • defaultClass (string) - the name of the default class of the component when the class property is empty
  • childrenProperty (string) - the name of the component property that contains its children components
  • membersProperties (array) - Array of zero or more property names for other categories of component members
  • idProperty (string) - the name of the ID property of the component
  • bindingProperty (string) -  the name of the binding ID property of the component. See the JUL documentation for more details.
  • useTags (boolean) -  whether the components are identified by a tag name besides their class
  • tagProperty (string) - the name of the tag property if present
  • customFactory (function) - by default, the components are instantiated using the 'new' constructor with the name of their class. Use a custom factory that gets the component config as an argument to return your component instance.
  • topDown (boolean) - by default, the instantiation is done first for children, then for their parent. Set this true for a top-down instantiation.
  • parentProperty (string) - the name of the property that will contain the parent instance of the component. Only relevant for the top-down instantiation.

Choosing a template

A template is an HTML page used to generate live testing of the project. The page accepts several template variables that are replaced server-side with the actual values. Besides these variables, you should include in the page any scripts and styles required to actually draw the components of the project.
The template variables are:

  • jul_script - script tag of the JUL library
  • project_script - script tag referring to the current project code
  • project_<property> - variables that match the properties in the project settings
Back to top

Frameworks

Frameworks are configuration objects that describe collections of components such as widget libraries or component libraries.

Relation with a project

Using a framework allows the user to add its components to the current project. The available components will appear in the 'Add component' scroll box. Also, if the framework specifies the means to get the component bounding rectangle, the component tree and the test panel will visually hint the selected component with a red rectangle.
The current framework will filter the list of available components in the 'Add component' scroll box depending on the selected component in the project.

Configuring a framework

The framework settings are:

  • title (string) - the title of the framework
  • ns (string) - a unique dotted path representing the JavaScript namespace of the framework
  • prependNS (boolean) - if true, the components will be added to the project with their full namespace as the class name. This has no effect if the project is using tags.
  • getBoundingRect (function) - a custom function that gets the component instance as the parameter and returns its bounding rectangle
  • augments (string) - if present, the current framework will inherit the component configs from that. Can be cascaded miltiple times.
The framework components are managed from the 'Components' tab. Several members of a component configuration can inherit from similar members of one or more components. These inheritable members are: 'getBoundingRect', 'members', 'events.
The members of a component configuration are:
  • description (string) - component description
  • restictParent array)_ - a name or an array of component names that can be the parent of the current component. Special value 'document' indicate the body element of the HTML page.
  • inherits (string) - a name or an array of component names this component inherits from. All the component members and events will be calculated through inheritance when the component is added to the project's component tree.
  • getBoundingRect (string) - the name of the component method or a custom function that returns its bounding rectangle. This inherits from the 'inherits' property and replaces the global function of the framework if specified.
The descriptions of the component members and events are managed in the 'Members' and 'Events' tabs for each component.
For a component member, the description is:
  • name (string) - member name
  • description (string) - member description
  • logic (boolean) - whether the member belongs to the logic part of the project
  • required (boolean) - whether the member is required or not
  • defaultValue (mixed) - a JavaScript value used for initialization
  • template (string) - a format string used as a hint for editing
For a component event, the description is:
  • name (string) - event name
  • description (string) - event description
  • template (string) - format string used as a hint for editing
Back to top

Advanced topics

JUL Designer uses a JUL parser to render the component tree. To better understand using the designer, one should get accustomed with the parser specifics.

UI and logic separation

By default, a project separates the UI and logic members of each component into two properties of the project named 'ui' and 'logic'. The separation can be turned off from the project settings or on the fly from the menu Project -> Don't separate logic.
The 'ui' property of the project contains the c9components as a tree of configuration objects. Each configuration object may have an ID or a binding ID which links the object with its logic part.
The 'logic' property of the project is a configuration object which has properties named the same as the IDs of the configuration objects in the 'ui' property. Inside these logic configuration objects, the designer puts all the members of the component marked as logic. Also, the listeners property goes in this place if not empty.
If the separation is turned off for some components, all their members go to the 'ui'  property of the project.

Class and tag names

There are two categories of frameworks the parser and, consequently, the designer works with: the frameworks where components are class instances, and XML based languages where components are identified by tags.
For the first category, the class name of a component is the name from the component configuration, optionally prefixed with the namespace of the framework (if prependNS is true). This name is also displayed as the label of the component in the component tree panel.
For the second category, the class name is always the XML namespace of the framework (e.g. 'html', 'svg', 'xul' etc.). In addition, each component has a tag property which is the component name from the framework. The 'prependNS' setting is ignored, but, in the component tree panel, the components with a different XML namespace than the default class of the project are prefixed with their class name and a colon (e.g. 'svg:path' ).
For both categories, if a component has the same class as the default class of the project, the class property will be stripped from the component configuration.

Namespaces

Both projects and frameworks are uniquely identified with their JavaScript namespaces.
A namespace is a string of identifiers or integers separated with dots.
Starting from the global object in the page (i.e. the window), these segments separated by dots are objects that can be found by resolving the current segment as the property of the current object.
The project uses its namespace to generate and to separate its JavaScript code from the other scripts. The project namespace also has the following properties:

  • 'parserConfig' - the parser configuration
  • 'ui' - the UI part of the project
  • 'logic' - the logic part of the project

The framework namespace is mostly informative to what concerns the generated code, but may be used to construct a full class name for the components.

Back to top

Elements of the interface

The interface manipulates JavaScript objects, so, some elements are specific to that scope.
Editing operations (copy, cut, paste, remove etc.), all work with JavaScript objects, aiming complete control over the generated code.

The value box

Several parts of the interface have a 'Value' column with value boxes, one for each row. The type of value box depends on the JavaScript type of the value behind it.
The types of value boxes are:

  • editable text box - for JavaScript types 'String' and 'Number'
  • check box - for JavaScript type 'Boolean'
  • read-only text box - for the rest of JavaScript types
When possible. the text for complex types is displayed in a friendly format.
If a field is empty but it has a default value, the text box will hint that value as italics text.
For the fields with read-only box, the only means of editing is the code button next to the value box.

The code dialog

The values in the value boxes can also be edited using the code buttons (...) in the 'Code' column. This launches the code dialog that allows editing a JavaScript expression.
You may fill any JavaScript code that evaluates to a valid expression. If the type of resulting value differs from the original, the corresponding value box will reflect the change.
Clearing the dialog box will delete the object member unless the field has a required default value which, in that case, will be assigned to the member.

The find box and the name box

At the top of the component tree, near the buttons 'Up', 'Down', 'Remove', 'Find', there is the find text box. It performs a cyclic search for the next component with an ID or a binding ID the same as that entered in the box.
At several parts in the interface, near the buttons 'Add', 'Remove', 'Change', there is the name text box. It acts on the items of the list box in the selected tab below. If an item is selected and you press 'Enter' in the name text box, the item name will change if possible. If no item is selected or if you press 'Shift+Enter' a new item is added. If the name isn't valid, it will be automatically generated.

The Component select boxes

At the top of the component tree, there is a series of three select boxes that spells: "Show 'children' in 'UI' as 'Array'".
The first select box chooses what category of descendents to show for the current component.
The second select box changes the belonging of the previous category either to UI or to logic.
The third select box changes the type of selected category either to 'Array' or to 'Object'. Look at the generated JavaScript to see the results.

Copy, paste and undo operations

The copy, cut, paste, remove operations are split in two groups. First group operates on the components in the component tree, the second one processes the members of a component.
A component is copied and pasted with all its descendant components. Also, any operation in the component tree takes a component together with its sub-tree.

The copy-paste operations on the component members allow copying and pasting multiple members to any component in the project. They exclude however certain special properties meaningful to the JUL parser such as: the class, the tag, the children property, other 'members' properties, ID properties.
The undo operation undoes the last altering operation regardless of its kind.

Back to top