How to Use MARIAE

Please note that these explanation notes basically refer to MARIAE version 1.2.7 onward.

  1. General
    1. How to Install and Run the Tool
    2. Explanations of MARIAE menus
  2. Handling Projects in the tool
    1. How to Create a New Project
    2. How to Open an Existing Project
    3. How to Set the Main Project
  3. Handling MARIA UI Models (in General)
    1. How to Create a New AUI Model/CUI Model
    2. How to Open a UI Model in the Tool
    3. How to Import a UI Model within the Main Project
  4. Handling CTT Task Models
    1. How to Generate a CTT Task Model from a WSDL
    2. How to Select and Apply Heuristics to Obtain an AUI
    3. How to Obtain an AUI from a CTT Task Model
  5. Handling AUI Models
    1. How to Modify an AUI Model
    2. How to Add a New AUI Element into an AUI Presentation
    3. How to Change the Attributes of an AUI Interactor
    4. How to Obtain a CUI from an AUI Model
  6. Handling CUI Models
    1. How to Modify a CUI Model
    2. How to Add a New CUI Element into a CUI Presentation
    3. How to Change the Attributes of a CUI Interactor
    4. How to Obtain a Final UI (FUI) from a CUI Model
  7. How to run the scenarios
    1. How to run the home and weather scenario
    2. How to run the educational scenario
    3. How to run the car rental scenario
    4. How to run the multimodal scenarios


1. General

1.1 - How to Install and Run the Tool

  1. Download the latest version of the tool from its download page
  2. Unzip the downloaded file into a distribution folder (from now on, we call this folder as "mariae_home")
  3. Run the tool. There are two possible ways to do this:

1.2 - Explanation of MARIAE Menus

2. Handling Projects in the Tool

MARIAE is a tool for handling a number of multi-layer (task, abstract, concrete, implementation layer) UI descriptions of your interactive applications. Using MARIAE you will end up creating a number of UI models referring to the same scenario/example. For this reason, in order to easily handle the files referring to the same example/application/scenario, we provided you with the possibility to collect such models/files within the same project. Please note that MARIAE projects generally have a ".meprj" extension.

2.1 - How to Create a New Project

  1. Select Projects|New Project, then browse your hard disk to select the folder where you want to create a new project
  2. In the file chooser window that will appear, provide a name for your project (e.g. "museumApplication_project", "educational_scenario", ..)
  3. An empty project folder will be automatically created in the tool (see the Project tab in the left-hand part of the tool), with a set of nested sub-folders (e.g. ctt, aui, cui, annotations, etc.) that will contain each a different type of content. Correspondingly, a file directory with the same nested structure will be also created in your hard disk. At this point you can start populating your empty project by e.g. importing a UI model in your project

2.2 - How to Open an Existing Project

2.3 - How to Set the Main Project

Within MARIAE you could have multiple projects loaded at the same time (they are all listed when you select the “Projects” tab). In case of several projects loaded in the tool, you can easily identify the current main project, since the associated folder name is shown in bold letters within the tool (if just one project is loaded, by default this project is also the main project).

3. Handling MARIA UI models (in General)

Please note tha the UI models that are handled in the tool are the ones compliant with the specification of the MARIA language

3.1 - How to Create a New AUI model/CUI Model

Select File |New in the menubar. Then, in the window that will appear, double-click on type of UI model you want to create.

3.2 - How to Open a UI Model in the Tool

In the tool menubar select File | Open.. and then browse your hard disk and select the file corresponding to the model you want to open in the tool (e.g. a task model, an AUI model, ..). The content of the selected file will be opened and then rendered in the central panel of the tool.

3.3 - How to Import a UI Model within the Main Project

At a certain point you might want to import an existing model within your current main project load inthe tool (please note that the files corresponding to CTT task models, Abstract User Interface (AUI) models, and Concrete User Interface (CUI) models, will generally have a ".xml" extension).

4. Handling CTT Task Models

4.1 - How to Generate a CTT Task Model from a WSDL

4.2 - How to Select and Apply Heuristics to Obtain an AUI

Select Tools | CTT | Generate AUI from Presentation Task Sets. A window will open allowing you to select the heuristics to be applied to the Presentation Task Sets that have been automatically identified starting from the analysis of the task model. Apply as many heuristics as you want. When you have finished, click the "Finish" button: the AUI will be automatically generated and the first presentation of such AUI will be automatically displayed in the main panel of the tool.

4.3 - How to Obtain an AUI from a CTT Task Model

From the tool menubar, under the Tool | CTT menu, select the Generate AUI menu item

5. Handling AUI models

5.1 - How to Modify an AUI

Select the "Document" tab of the vertical tabbed panel shown in the left part of the tool: the list of the various concrete UI presentations will be displayed. By clicking on one of such presentation in the left part of the window, the content of the selected presentation will be displayed in the central panel of the tool. You can refine/customize such shown presentation in at least two possible ways:

Notes:

5.2 - How to Add a New AUI Element into an AUI Presentation

When you have an AUI and you would like to add a new AUI element element in one of its abstract UI presentation, you could this in at least two manners:

5.3 - How to Change the Attributes of an AUI Interactor

In order to change the attributes/properties of a certain AUI interactor included in an AUI model currently open/loaded in the tool (and then shown in the central panel of the window) you can do this in two different manners:

5.4 How to obtain a CUI from an AUI

From the tool menubar, under the Tool | AUI menu, select the proper item depending on the type of platform you want to address. For instance, please select Generate Desktop CUI if you want to obtain a CUI description for the desktop platform, select Vocal CUI if you want to generate a CUI for the vocal platform, and so forth for the other platforms.

6. Handling CUI Models

6.1 - How to Modify a CUI

Select the "Document" tab of the vertical tabbed panel shown in the left part of the tool: the list of the various concrete UI presentations will be displayed. By clicking on one of such presentation in the left part of the window, the content of the selected presentation will be displayed in the central panel of the tool. You can refine/customize such shown presentation in at least two possible ways:

Notes:

6.2 - How to Add a New CUI Element into a CUI Presentation

If you have a CUI model and you would like to add a new element in one of its CUI presentations, you could this in at least two possible manners:

6.3 - How to Change Attributes of a CUI Interactor

In order to change the attributes/properties of a certain CUI interactor included in a CUI model currently open/loaded in the tool (and then shown in the central panel of the window) you can do this in two different manners:

In particular, such window will enable you to edit two kinds of attributes associated with a certain CUI interactor:

6.4 - How to Obtain a Final UI (FUI) from a CUI Model

With this feature you can obtain an implementation UI starting from a CUI for a certain platform (for instance, you can generate HTML code from a CUI Desktop, or you can generate VoiceXML2.0 for a CUI vocal, ..). In order to do this, from the tool menubar, under the Tool menu, select the proper menu item depending on the type of platform for which you want to build an UI implementation (e.g. CUI Desktop, CUI Mobile Large,.). As you will see, various platforms are currently supported by the tool (desktop, mobile large, vocal, multimodal).

7. How to run the scenarios

7.1 How to run the home and weather scenario

The mariae_home folder is the location where you created unzipped the MARIAE package downloaded from the HIIS lab web site.

The scenarios demostrate the tool capability to generate applications from annotated WSDL definitions. The annotation files and the addresses of the WSDL definitions is contained into the sample projects. The selected scenario (homeScenario or weatherScenario) will be referenced as scenario

  1. Open the scenario.meprj project file in the mariae_home/examples folder from the menu Projects | Open Project... .
    When the project is loaded, set it as the main one, right-clicking its icon on the Project Panel and selecting Set as Main Project
  2. Generate the task model for the WSDL of the scenario web service from the menu Tools | CTT | Generate Task Model from WSDL. Select the HomeScenarioWSversion2 for the home scenario or GlobalWeather for the weather scenario from the drop down list. The generated CTT is automatically opened in the environment and saved into the current project. (You can browse the Web service definition through the WS panel on the right.
  3. It is possible to open other WSDL definition using the Web Services menu).
  4. Generate the abstract user interface (AUI) for the CTT generated at step 2 by selecting Tools | CTT | Generate AUI The generated AUI is automatically opened in the environment and saved into the current project
  5. Generate the desktop concrete user interface (desktop CUI) for the AUI generated at the step 3 by selecting Tools | AUI |Generate Desktop CUI
  6. Generate the final web application (Java Servlet + JSP) for the desktop CUI generated at step 4 by selecting Tools | CUI Desktop | Generate JSP with Web Service Support. It will create a NetBeans 6.9 web project that can be compiled and deployed on a Java Servlet and JSP server (e.g. Apache Tomcat). The project is located into the mariae_home/Output/generated folder. Open it from NetBeans and, after having configurated the server, you can run the application directly from the Netbeans IDE by right-clicking the project icon in the project panel and selecting Run.
  7. The home scenario application can be accessed with username guest and password user.

7.2 How to run the educational scenario

The mariae_home folder is the location where you created unzipped the MARIAE package downloaded from the HIIS lab web site.

The scenario demostrates the tool capability to generate applications from a CTT task model bound to specific Web Service operations. The task model has been created by a designer and it is contained into the CTT project folder. The operations have been annotated in advance by the service creator. The annotation file and the address of the WSDL definition is contained into the sample project.

  1. Open the educational.meprj project file in the mariae_home/examples folder from the menu Projects | Open Project... .
    When the project is loaded, set it as the main one right-clicking its icon on the Project Panel and selecting Set as Main Project
  2. Open the task model double clicking the educational-scenario-v-3.xml contained into the CTT node from the project panel on the left. The CTT model is automatically opened in the environment and you can browse the Web service definition through the WS panel on the right.
  3. Generate the abstract user interface (AUI) for the CTT generated at step 2 by selecting Tools | CTT | Generate AUI The generated AUI is automatically opened in the environment and saved into the current project. It is also possible to fine-tune the AUI generation by manually applying the heuristics selecting Tools | CTT | Generate AUI from Presentation Task Sets
  4. Generate the desktop concrete user interface (desktop CUI) for the AUI generated at the step 3 by selecting Tools | AUI |Generate Desktop CUI
  5. Generate the final web application (Java Servlet + JSP) for the desktop CUI generated at step 4 by selecting Tools | CUI Desktop | Generate JSP with Web Service Support. It will create a NetBeans 6.9 web project that can be compiled and deployed on a Java Servlet and JSP server (e.g. Apache Tomcat). The project is located into the mariae_home/Output/generated folder. Open it from NetBeans and, after having configurated the server, you can run the application directly from the Netbeans IDE by right-clicking the project icon in the project panel and selecting Run.
  6. The home scenario application can be accessed with username 54321 and password spano.

7.3 How to run the car rental scenario

The mariae_home folder is the location where you created unzipped the MARIAE package downloaded from the HIIS lab web site.

The scenario demostrates the tool capability to generate applications a WADL service definition. Please note that the message exchange is supported only with XML serialization. The address of the WADL definition is contained into the sample project. Here we will list the steps for generating a vocal application for renting a car that exploits the REST web service. In addition, we demonstrate the MARIAE ability to convert the ASFE-DL abstract user interface definition into MARIA XML. The ASFE-DL is one of the markup languages submitted for the standardization for the W3C MBUI Working Group.

However, it is also possible to automatically generate a default application for the other platforms following the same steps listed for the home and weather scenarios.

  1. Open the carRentalScenario.meprj project file in the mariae_home/examples folder from the menu Projects | Open Project... .
    When the project is loaded, set it as the main one right-clicking its icon on the Project Panel and selecting Set as Main Project
  2. Import the ASFE-DL AUI definition selectingFile | Import ASFE-DL . From the Open file dialog, select the carRent.xml file in the mariae_home/examples/carRentalASFE_DL folder.
    The tool will automatically load the MARIA XML version of the AUI, and will save it into the current project.
  3. Generate the vocal concrete user interface (vocal CUI) from the AUI generated at the step 2 by selecting Tools | AUI |Generate Vocal CUI The tool will automaticall open the Vocal CUI and will save it into the current project.
  4. Now we will add a set of platform-dependent information to this CUI, applying an XSLT to the current displayed Vocal CUI.
    Select Tools | Apply XSLT... and select the PopulateVocalCUI.xsl file in the mariae_home/examples/carRentalASFE_DL folder.
    The tool will prompt you asking what kind of model the transformation will produce. Select cui vocal. After that, the tool will automatically load another version of the same VocalCUI file with more information, and it will save it into the current project.
  5. Generate the final web application (Voice XML + Java Servlet + JSP) for the vocal CUI generated at step 4 by selecting Tools | CUI Vocal | Generate VoiceXML 2.0 with Web Service Support. It will create a NetBeans 6.9 web project that can be compiled and deployed on a Java Servlet and JSP server (e.g. Apache Tomcat). The project is located into the mariae_home/Output/generated folder. Open it from NetBeans and, after having configurated the server, you can run the application directly from the Netbeans IDE by right-clicking the project icon in the project panel and selecting Run. You can browse the vocal application through the Voxeo Vocal Browser.
  6. The application can be accessed using the following credentials:

7.4 How to run the multimodal scenarios

The multimodal scenario project file is located in maria_home/examples/multimodalScenario.meprj. The scenario shows how it is possible to generate an HTML multimodal application or an X+V application from a multimodal CUI. In order to generate the application you should follow the following steps:

  1. Open the multimodalScenarioi.meprj project file in the mariae_home/examples folder from the menu Projects | Open Project... .
    When the project is loaded, set it as the main one right-clicking its icon on the Project Panel and selecting Set as Main Project
  2. Open one between the two multimodal-desktop CUI available in the Project tab. The two possible options are Multimodal_Desktop_domo_example and Multimodal_Desktop_flight_example
  3. Generate Multimodal HTML implementation of the model selecting Tools | CUI Multimodal | Generate Multimodal HTML . At the end of the transformation, a popup will specify the exact path of the generated files on your machine (by default they will be in the mariae_home/examples/multimodalScenario_files/MultimodalHtml/ folder)
  4. Open the transformation results with Chrome browser that supports the Web Speech API (W3C Web Speech API Specification) for desktop platform since v31. Regarding the mobile version of Chrome browser the Web Speech API are supported since v38.
    Here it is possible to verify the list of browser supporting the Web Speech API.
    If you are executing the generated page from a file (e.g. file://folder/generated.html) then Chrome will return an Not Allowed Exception during Speech Recognizing action; to solve this problem you have to execute chrome with the following param: --allow-file-access-from-files
  5. Generate the X+V implementation of the model selecting Tools | CUI Multimodal | Generate XHTML + Voice . At the end of the transformation, a popup will specify the exact path of the generated files on your machine (by default they will be in the mariae_home/examples/multimodalScenario_files/x+v/ folder)
  6. Open the transformation results with an X+V enabled browser (e.g. Opera - max v9.27)