Exporting to Developer Tools

Using Maqetta, the user create web application prototypes which are subsequently handed off to developers, who transform the prototype incrementally into a production application.

This article introduces the features in Maqetta that help with the designer-to-developer hand-off. The article starts by introducing some important concepts. The article then highlights the product's export-as-ZIP and workspace management features, including the ability to create Eclipse-compatible projects.

When you launch Maqetta for the first time, Maqetta creates a default workspace and a default project ("project1"). The picture below shows the default workspace:

Make the following adjustments to the Files palette

• Drag the horizontal divider that is just above the Files palette:

  

  upwards to increase the size of the Files palette until it is about 2/3 the height of the Maqetta browser window. (As a result, this will take size away from the Widgets and Review palettes.)
• Look at the lib entry in the Files palette. If it is closed (i.e., it has a "+" icon on the left size), then click on the "+' to open lib to show its children.
• Under lib, you should see a child entry for dojo. Look at the dojo entry in the Files palette. If it is closed (i.e., it has a "+" icon on the left size), then click on the "+' to open dojo to show its children.
• Look at the themes entry in the Files palette. If it is closed (i.e., it has a "+" icon on the left size), then click on the "+' to open themes to show its children

The Files palette should now look something like this:

Some things to note:

• In Maqetta's default workspace, JavaScript libraries are placed into the lib/ folder. The picture above shows multiple libraries, clipart/, custom/, dojo/, maqetta/ and shapes/.
  • The dojo/ folder contains a read-only version of the Dojo toolkit. Inside the outer dojo/ are the three main folders that make up a Dojo release, dijit (Dojo's desktop widget library), dojo (Dojo's core functions) and dojox (an extensive library of Dojo extensions).
    Notes:

    • By default, Maqetta includes a release distribution of Dojo in your workspace. A release distribution contains compressed versions of JavaScript and CSS files.
    • Dojo also provides a source distributions that contains uncompressed versions of JavaScript and CSS files and include various other files useful to developers, such as build utilities, demos, test files and documentation. Both release and full source distributions for the Dojo toolkit can be found at http://download.dojotoolkit.org/
    • Maqetta includes a "download as ZIP" feature (described below) where you can package up your HTML and CSS files, along with necessary libraries such as Dojo, into a ZIP file that can be expanded onto a web server, where your applications can run outside of Maqetta. However, Maqetta also offers a "download as ZIP" feature (described below) where you can package up your HTML and CSS files, along with necessary libraries such as Dojo, into a ZIP file that can be expanded onto a web server, where you applications can run outside of Maqetta. By default, Maqetta copies the release distribution of Dojo into the ZIP file, but the download dialog offers an option to include a full source version of Dojo into the ZIP file.
  • The clipart/ folder contains the widgets found in the Clip Art section of the Palette.
  • The custom/ folder is custom widgets are stored (when using the SaveAs Widget feature).
  • The maqetta/ folder includes a couple of Maqetta-supplied runtime JavaScript files, including AppStates.js that provides runtime support for Maqetta's application states feature.
  • The shapes/ folder contains the widgets found in the Drawing Tools section of the Palette.
• All CSS themes used by Maqetta are in the themes/ folder. Maqetta includes seven themes by default in each workspace, all of which are read-only. Maqetta includes two desktop themes:
  • The claro/ theme is the default theme used by the Dijit widget library in the Dojo toolkit.
  • The sketch/ theme restyles Dijit widgets to have a pseudo-hand-drawn look that is useful in early wireframing scenarios when designers prefer visually neutral rendition of UI so that reviewers will focus on the flow of the UI rather than focus on visual aspects such as fonts and colors.
  and five mobile themes:
  • The android/ theme provides styling that matches the native look-and-feel of Android devices.
  • The blackberry/ theme provides styling that matches the native look-and-feel of Blackberry devices.
  • The ipad/ theme provides styling that matches the native look-and-feel of the iPad.
  • The iphone/ theme provides styling that matches the native look-and-feel of the iPhone.
  • The custom/ theme is a generic, cross-platform theme that is designed for custom theme development for development teams that prefer highly customized visual styling instead of attempting to exactly match native device styling.
  There is also a dijit/folder for supplemental CSS files needed by the various Dojo themes:
• Any custom themes created with the "Create theme..." command (found on the Create menu at the top of the application) will be added to the themes/ folder. For example, if you create a new theme called "mytheme1": then the Files palette would show a mytheme1 subfolder under themes/:

• Maqetta automatically includes a reference to an application CSS file (i.e., app.css) with each new HTML file created by a Create command.

  You can insert application-specific CSS style rules in the app.css file either by using some of the advanced features in the Properties palette or by double-clicking on app.css in the Files palette to bring up the source editor, where you can type CSS style rules by hand. (See Creating Style Rules with app.css.)

  At the top of the default app.css file, you will find a large CSS comment block that explains the purpose of the file and some hints about how to use it:

  app.css default contents

  /*
   * This file is provided for application-specific style rules.
   *
   * By default, Maqetta includes this CSS file within HTML pages
   * authored in Maqetta.
   *
   * This file is typically used to override style rules found in
   * theme CSS files. For example, suppose the theme CSS file has:
   *
   * .claro .dijitButton .dijitButtonNode {
   *		padding:2px 4px 4px 4px;
   * }
   *
   * But for your application suppose you want to tighten the padding
   * for buttons. Then, you might include the following style rule
   * in this file (assuming that you accept Maqetta's default where
   * id "myapp" is present on the BODY element, and assuming
   * that you are using the "claro" theme):
   *
   * #myapp.claro .dijitButton .dijitButtonNode {
   *		padding:1px 3px 3px 3px;
   * }
   *
   * Because of CSS precedence rules (see [1]), the above style rule
   * (which begins with #myapp.claro) will "win the cascade" versus 
   * the style rule from the theme CSS file due to the use of the
   * ID select (#myapp), which has higher specificity than the class
   * selectors used throughout the Claro theme.
   *
   * [1] http://www.w3.org/TR/CSS21/cascade.html#cascade
   */
  html,body {
  	height: 100%;
  	width: 100%;
  }
  	

• Maqetta also automatically includes a reference to an application JavaScript file (i.e., app.js) with each new HTML file created by a Create command. This file is a convenient place for you to insert custom runtime JavaScript logic.

  app.js default contents

  /*
   * This file is provided for custom JavaScript logic that your HTML files might need.
   * Maqetta includes this JavaScript file by default within HTML pages authored in Maqetta.
   */
  require(["dojo/ready"], function(ready){
       ready(function(){
           // logic that requires that Dojo is fully initialized should go here
  
       });
  });
  	

This part of the article provides an overview of some technical details about the HTML files that Maqetta creates:

• Go to the Create menu at the top of the application, and issue a "Create Desktop Application" command. You can either accept the default filename (e.g., file1.html) or enter a custom filename. Click on the Create button.

• On the toolbar, look for the "Split horizontally" command on the dropdown menu to the right of the "Design" and "Source" buttons. Your screen should look like this now:

  

• Drag/drop a Button widget onto the page. In the top pane, you should see a Button widget rendered on the canvas. In the bottom pane (source view), you should see the following:

  HTML source file contents

  [01] <!DOCTYPE html>
  [02] <html>
  [03] <head>
  [04] <meta charset="utf-8"/>
  [05] <title>Untitled</title>
  [06] <script type="text/javascript" src="lib/dojo/dojo/dojo.js" data-dojo-config="'parseOnLoad':true,'async':true,'packages':[{'name':'gridx','location':'../gridx'},{'name':'clipart','location':'../../clipart'},{'name':'maqettaSamples','location':'../../../samples'},{'name':'maqetta','location':'../../maqetta'},{'name':'shapes','location':'../../shapes'},{'name':'widgets','location':'../../custom'}]"></script>
  [07] <script type="text/javascript">
  [08] require([
  [09]   "dijit/dijit",
  [10]   "dojo/parser",
  [11]   "maqetta/space",
  [12]   "maqetta/AppStates",
  [13]   "dijit/form/Button"
  [14] ]);
  [15] </script>
  [16] <style>@import "themes/claro/document.css";@import "themes/claro/claro.css";@import "app.css";
  [17] </style>
  [18] <script type="text/javascript" src="app.js"></script>
  [19] </head>
  [20] <body class="claro" data-maq-flow-layout="true" data-maq-ws="collapse" id="myapp" data-maq-appstates="{}">
  [21]  <input type="button" data-dojo-type="dijit.form.Button" intermediateChanges="false" label="Button" iconClass="dijitNoIcon"></input>
  [22] </body>
  [23] </html>
  

• Some notes about the above HTML file listing:
  • Line [06] - This line loads Dojo's JavaScript files. In general, everyone on this line is essential for pages to work either in the Maqetta page editor and/or when running in the browser outside of Maqetta. The 'packages' section of this line (many characters) provides information that allows Maqetta to load widgets properly.
    Note that Maqetta application will update the URL references to dojo.js and the packages in various scenarios. For example, if you save an HTML file into a nested folder, Maqetta will insert any necessary ../ references so that the HTML files will properly load Dojo's JavaScript files.
  • Lines [07]-[15] - These lines are Dojo-specific JavaScript. Dojo requires calls to require() for each Dojo module used by an HTML page. Maqetta automatically adds all necessary require() statements to the HTML page.
  • Lines [16]-[17] - These lines load the CSS files used by this HTML file:
    • themes/claro/claro.css - Reference to the CSS theme used by this page. (Default for Dojo/Dijit is the "claro" theme.)
    • app.css - Application-specific CSS style rules. (See discussion earlier in this article about app.css.)
    Note that Maqetta application will update the URL references to the above files automatically in various scenarios. For example, if you save an HTML file into a nested folder, Maqetta will insert any necessary ../ references so that the HTML files will properly load the CSS files.
  • Line [18] - Application-specific JavaScript logic. (See discussion earlier in this article about app.js.))
  • Line [20] - The <body> element often includes some Maqetta-specific attributes that provide essential authoring information to the Maqetta page editor and/or are required so that the application states feature can run outside of the Maqetta authoring environment:
    • class="claro" - The currently active theme name (in this case, "claro") appears in two places in the HTML source code: (1) within an @import command in the <head> and as a class name on the <body> element.
    • data-maq-flow-layout="true" - This attribute persists whether this HTML file is currently being editing using flow layout or absolute layout.
    • data-davinci-ws="collapse" - This attribute allows Maqetta to work around HTML/CSS white space complexities. Without this attribute, Maqetta would either have to create unreadable source code or fail to deliver on true WYWIWYG authoring.
    • id="myapp" - This attribute allows Maqetta to insert style rules within app.css file that reliably override style rules within the CSS themes. Typically, CSS themes use class selectors to style widgets and HTML. This allows Maqetta to create override CSS rules in app.css that reliably override the theme CSS rules because Maqetta's override CSS rules use id selectors, which have higher priority (i.e., "specificity") in CSS.
      Maqetta's override CSS rules always include #myapp at the beginning of the selector.
    • data-maq-appstates attribute - If an HTML page defines custom application states via the States palette, then the <body> element and various other elements within the page will include a data-maq-appstates attribute. The data-maq-appstates attribute is necessary to make the application states feature work when your HTML page runs outside of the Maqetta authoring environment.
  • Line [21] - This line provides the declarative markup for the Button widget. Typically, each widget on the page will be represented in the HTML file as a single line of HTML. Some widgets, however, expand into multiple lines of HTML.

Maqetta allows you to export your entire workspace or a subset of your workspace as a ZIP file that can be handed to developers, who can then incrementally transform the UI mockup created by Maqetta into a production application.

To export your entire workspace as a ZIP file:

• Click on the first icon in the Files palette, the Download Entire Workspace icon This brings up the following dialog:

  

• Accept all of the defaults, and click on the OK button to download your entire workspace as a ZIP file named workspace1.zip. This will initiate a browser download action, with the download process happening in the background.
• Invoke the browser's Download feature to look at all of the browser's recent downloads. In most browsers, the most recent download appears at the top. If the download is not yet completed, the browser usually will show download progress. Wait until the download is complete.
• Once the download has completed, using your local machine's features (e.g., Windows Explorer or Mac Finder), create a new empty folder and move or copy the downloaded ZIP file into that new folder, then unzip the ZIP file's contents into that folder.
  If you have a localhost web server on your machine, create the new empty folder somewhere within the web site contents area for your localhost web server. For example, we XAMPP or MAMP, the web site contents are stored in the htdocs/ folder. This will allow you to actually run the Maqetta-created web pages on your localhost server.
• Using either Windows Explorer or Mac Finder, examine the hierarchy of files after unzipping. You should see a local replica of your Maqetta workspace.

To export only selected files within a ZIP file:

• In the Files palette, select all files that you would like to include in the download other than the lib/ files. (The download dialog will allow you to include or exclude those files.)
• Click on the second icon in the Files palette, the Download Selected Files icon This will bring up a similar download dialog as the Download Entire Workspace icon.
• Then follow similar steps as described above for the Download Entire Workspace icon.

The download dialog provides the following options:

• Include/exclude particular libraries - The checkboxes to the left of the list of libraries controls whether the given resources should be included in the download ZIP file. By default, all JavaScript libraries (e.g., dojo) will be included in the download ZIP file.

  The decision whether to include particular JavaScript libraries in your download ZIP depends on the needs and constraints of the team that will receive the ZIP. Usually, you will want to collaborate with your development team to find out whether they want or do not want the libaries and/or themes within the ZIP. Three common scenarios:

  • You probably would include all JavaScript libraries if you want the contents of the download ZIP to be a totally self-contained, runnable application that you can install on an arbitrary web server or localhost server.
  • You probably would include particular JavaScript libraries if you have created an Eclipse-compatible project (see discussion of Eclipse-compatible projects below) and are handing the ZIP off to a development team that is using the Eclipse IDE. By including the JavaScript libraries, you will be providing a ZIP file that contains the equivalent of a self-contained Eclipse web project.
  • You probably would not include particular JavaScript libraries if you are handing the ZIP off to a development team that is not using Eclipse and is familiar with the JavaScript libraries you are using in the UI mockups. The development team might not want the JavaScript libraries included in the ZIP because they may already have copies of the JavaScript libraries on their development systems and it is wasteful to include these (usually quite large) components if not needed.


• Relocate particular libraries - Sometimes the development team sets up their folder hierarchy differently than how Maqetta sets up user workspaces. For example, by default Maqetta places the Dojo libraries at ./lib/dojo, whereas the development team might place Dojo at a different location, such as ./js/dojo, ./dojo or perhaps ../../libraries/dojo. The editable textboxes within the dialog allow you to "relocate" the JavaScript libraries when the ZIP file is created to an alternate location than what you are using in your Maqetta workspace. For example, if Dojo is located at ./lib/dojo and your development team put the Dojo library at ./dojo, then you can change the textbox from lib/dojo to dojo. Maqetta will automatically fix up the cloned copies of all HTML files in the ZIP file such that all URL references to Dojo will point to ./dojo instead of ./lib/dojo.
  Note that changing the textboxes in the download dialog only affect the cloned files within the ZIP. Your Maqetta workspace files remain as they were.


• Download uncompressed source for selected libraries (if available) - By default, the downloaded zip will contain built, minified source for the selected libraries. Check this option if you want the original uncompressed source instead (currently only available for the Dojo and GridX libraries). Some tooling that you may wish to import your zip file into (such as IBM Rational Application Developer (TM) described below) work better with uncompressed source.


• Use Dojo Web Builder (experimental) This feature, still under development, will pass the downloaded workspace files through a web service which collects AMD-style Javascript module references across all HTML files and concatenates them into a single Javascript "layer" file to avoid network latency, and also minify symbols and remove comments and whitespace to reduce the size of the download. Initially, the processing is limited to Dojo modules and will attempt to replace the default dojo.js bootstrap file with a single file containing all the concatenated and minified code.

The third icon at the top of the Files palettes allows you to permanently modify the folder structure of your Maqetta workspace.

For example, by default, Maqetta places all JavaScript libraries within the ./lib folder, with the Dojo toolkit located at ./lib/dojo. These defaults usually work well for most Maqetta users. However, if your development team uses a different folder hierarchy, and you often create download ZIPs that you hand off to your developers, then sometimes it will be more efficient and less error-prone if you customize your Maqetta workspace to match the folder structure used by your developers. That way, when you create a download ZIP, you won't need to relocate JavaScript libraries for each new ZIP file. Maqetta will automatically fix up all HTML files in your workspace to take into account the new location(s) for your JavaScript libraries.

This section is relevant to web development teams that use the Eclipse IDE or IBM Rational Application Developer (RAD) 8.5 and want to export a fully self-contained Eclipse project that can be imported simply into the Eclipse IDE.

Here are steps for creating a self-contained, Eclipse-compatible project, exporting as a ZIP, unzipping into your Eclipse workspace, and then importing the project into Eclipse:

• Before you create your HTML and CSS content, invoke the "Create Project" command (found on the Create menu at the top of the application). In the dialog that appears, click on the "Eclipse support" checkbox.
  This will create a new project in your Maqetta workspace. Because of the "Eclipse support" checkbox, the new project will have a file hierarchy that matches the default file hierarchy used by the Eclipse IDE when creating a web project. In particular, Maqetta will create a WebContent/ folder. Additionally, Maqetta under the hood will create all of the hidden "dot files" (i.e., files whose name begins with a "." character) used by the Eclipse IDE when managing web projects.
• After creating your Eclipse-compatible new project in Maqetta, then use the Maqetta visual page editor to create HTML pages. Make sure that your HTML files are all within the WebContent/ folder becauses that is what Eclipse expects.
• Click on the Download Entire Workspace icon within the Files palette. If using RAD, then you may want to check the Download uncompressed source for selected libraries option. Otherwise, click OK in the dialog that appears to start the download process.
• Wait until the browser has completed the download. (Because Dojo is included in the ZIP, the download might take some time to complete.)
• In Eclipse, from the File menu, issue an Import command and choose "General>Existing Project Into Workspace". In the wizard that follows, choose the "Select archive file" option and then browse to your zip file. After selecting your zip file, click "Finish" at the bottom of the import wizard.
• At this point, you should be able to use Eclipse features to edit the project you just imported.

Previous / Next