Lesson 3: XMLRAD IDE Overview with the HelloWorld application

Objective

In this lesson, we will walk through the HelloWorld demo to discover XMLRAD and XSLStudio main features.
None of the options will be detailed very deeply. This lesson cover only a first tour of XMLRAD IDE.
Following lessons will describe in detail all elements announced in this lesson.

Knowledge

You will learn the following techniques:

How to navigate through XMLRAD
the different elements contained in an XMLRAD project: XMLModules, XMLServices, XSL, ...
How to design a simple HTML page with XSLStudio

Required Tools

Win95, 98, ME, NT, Win2K or XP.
a web browser: Internet Explorer 4.0, IE5, IE5.5, Netscape 6

Personal web Server or Internet Information Server (IIS).
XMLRAD

Click here to access XMLRAD on-line, you will be able to follow this lesson even if you don't have XMLRAD installed on your computer.

Click here to access XMLRAD Enterprise Edition which should be installed on your computer.

Required Knowledge

Web development basics: internet, HTML

Description

This lesson will review step-by-step major XMLRAD features.
You will need to click on the different link as shown on screen shots.
A little description will defines new terms, and architecture related knowledge required to understand this lesson.
You will manipulate XSLStudio basics to design an existing XSL page.

Step 1: Start XMLRAD

If you are using :

XMLRAD Professional: You can start XMLRAD from the Windows Start menu.
XMLRAD Professional is a standalone HTTP server running in the tray bar and listening on port 660.
Starting XMLRAD the first time will launch a web browser instance.
XMLRAD Enterprise: you need to check that IIS is running, then you can access http://xmlrad.com/XMLRADBin/XMLRAD.dll

XMLRAD main window

XMLRAD main window has 2 frames :

left frame: XMLRAD Explorer to access servers, projects, XMLModules, XMLServices, create a new Project, a new XMLModule, a new XMLService, acess to preferences.
main frame: also called the working area. It may contain Project Configuration, XMLGram Editor, XSLStudio, ...

From XMLRAD main window you have access to all registered projects on the current XMLRAD server. You are able to register an existing project, create a new project.

To access "About box", you will use XMLRAD Explorer, which displays the product version of your XMLRAD product: XMLRAD Enterprise or XMLRAD Professional.

XMLRAD "About Box"

You also have access through the other item in XMLRAD Explorer to XMLRAD on-line help by case-use and technical informations.
"Support" item let you access the internal task management tool of the e-delos.com R&D team to :

submit a new feature you would like to have in the following release
submit a bug

To access to a project click on the project item in the XMLRAD Explorer.

Step 2: Project Configuration page

Select the HelloWorld project :

Project Configuration Page

The Project Configuration Page defines the registered information of your project in XMLRAD.

Name: Name of the project
Path: will be used for all other files in the project which are relative to this path
XMLFile: main initialization file of the project. It contains all the imports of the other XML files: HelloWorld.Aliases.xml, HelloWorld.InitParams.xml, HelloWorld.GlobalParams.xml, HelloWorld.DataSources.xml, HelloWorld.XMLModules.xml, ...
InvokePath: used to invoke the application when you click on the run arrow icon, even more important when invoking the application to build XML OutputDoc for XSLStudio.
HTTPUserName/HTTPPassword: set these parameters if your http server requires some authentication when invoking an http url.

The project informations of this level are stored in the file:
C:\Program Files\e-delos\XMLRAD\Data\XMLRAD.Projects.xml.

The button Show Advanced Options will display the imported files of the main XMLFile.
Imported files are used to fill the XMLModules combobox in the top frame.

The Project Configuration Page has links to:

the Application Monitoring Page: access to the internal http dispatch engine of the XMLComponents Framework for the HelloWorld application
the Statistics Page: access to the internal statistics of the XMLComponents Framework for the HelloWorld application
Start and Stop the HTTP server: this option is used to restart IIS when recompiling Helloworld.

When using XMLRAD Enterprise Edition, stopping Internet Information Server will cause to stop XMLRAD. You will have to restart manually IIS.

Step 3: XMLComponents Framework Administration Pages

You can access to the Application Monitoring Page. It will launch a new web browser to display the XMLComponents Framework administration pages of HelloWorld application.

XMLComponents Framework Monitoring Page

Application Monitoring Page displays the concurrent modules prepared for execution.
A module may have 2 status :

green when available
red when running an http request. In this case you would see on the right cell, the callstack of the running http request.

Modules are implemented as XMLCollection.
An XMLCollection may contain multiple XMLModule, database connections, ...

One module handles one http request and only one.

When executing administration actions, it does not use one of the user modules.
It uses a specific XMLCollection reserved for administration actions.

XMLComponents Framework HTTP Monitoring Options Page

You can access to the Application Statistics from the XMLComponents Framework administration page, or through XMLRAD Project Configuration Page.

XMLComponents Framework Statistics Page

The Application Statistics Page displays the concurrent modules as columns and the multiple actions group by XMLModule as rows.
Since it is the first time you run the application, there is not yet any action executed.

You can close this web browser window.

Step 4: Project Configuration Pages

Let's get back to XMLRAD and to the Project Configuration pages.

Project Configuration Page

You can access the Advanced Options by clicking on the button "Show Advanced Options":

Project Configuration Page, Advanced Options

It displays all the imported files, within the main XMLFile: HelloWorld.xml.

There is no limit in number of files you may import in the main XMLFile, as well as their structure.

However, XMLRAD is using some heuristics to determinate where are located XMLModules, DataSources, Aliases, InitParams, GlobalParams, XMLServices. Changing default values may result in non trivial behaviours.

Click on the InitParams item to access the application initialization parameters:

Application Initialization Parameters

The main parameters are :

XMLC_InstanceName=HelloWorld: all the XMLComponents Framework is based on this value to process XML files and XSL files.
XMLSupervisorEMail and XMLC_SupervisorPassword: default values are blank. As soon as you will have setup new values, you will need to add these parameters and their values when accessing to the XMLComponents Framework administration pages.

InitParams are used to initialized the application, such as concurrent modules, administration path, ...
InitParams are not present in the Context, but can be accessed through XMLApplication.InitParams.Values['XMLC_InstanceName'].

Click on GlobalParams item to visualize global parameters:

Application Global Parameters

In this example, there are 2 GlobalParams, however, you may find in this page the values :

XMLC_Skin: users can override this value with blue2000, bluethin, graysquare, graythin, msnblue, msngray, msngreen, or any skin of their preferences.
UserLanguage: users can override this value with ENGLISH, DEUTSCH, FRENCH, ESPANOL, ITALIAN, ...

Application DataSources

In this example, there is no DataSource setup. This section will be reviewed in the next lesson.
There is no limitation in number of datasources in an XML application.

Click on Aliases tab:

Application Aliases

Application Aliases are mainly used within XSL files to dereference the physical application binary.
XSL file reference HelloWorld application as: <xsl:select value-of="/document/Aliases/HelloWorld"/>

This feature has been introduced to compile multiple XMLModules either in multiple binaries, or in a single binary.

Compiling multiple XMLModules in a single binary reduces significantly the overhead of binaries, memory and resources (database connections, handles, ...)

Click on Generators Item:

Application Generators

Generators are auto-increment values which can be used to generate unique identifiers when inserting new records.
This feature will be described in next lessons.

Click on EventLog item:

Application EventLog

This page list all errors which occured in the application.
For each error, you will find the complete description of the error, the callstack, the Cookies, the HTTP Params, and the current Context.
You can replay the error with the complete context to reproduce the error.
You can use EventLog also for non-regression tests.

Step 5: XMLModule Configuration Page

Select in XMLRAD Explorer, the XMLModule xmHelloWorld:

XMLModule Configuration Page

An XMLModule is a container ofr multiple XMLServices(the actions invoked within http requests).
The XMLModule Configuration Page contains:

the Name of the XMLModule. Warning: renaming the XMLModule may engage some behaviours.
the Path: is relative to the path of the main Application XMLFile. This path is used to load and store XMLServices contained in this XMLModule.

Click on the button Show Advanced Options:

XMLModule Configuration Page, Advanced Options

It displays the imported XMLServices files.

There is no limit in number of files you may import in the XMLModule file, as well as their structure.

However, XMLRAD is using some heuristics to determinate where are located XMLServices. Changing default values may result in non trivial behaviours.

Step 6: XMLService Pages

Select in XMLRAD Explorer, the XMLService HelloWorld:

XMLService Configuration Page

An XMLService is the action invoked in the http requests.
The following http request will invoke this action : http://xmlrad.com/HelloWorldBin/HelloWorld.dll/FormHelloWorld

The XMLService Configuration page displays:

Name of the XMLService. Note: to rename the XMLService, you need to click on the right green icon with the equal symbol. It may prompt you to rename XMLGram and XSL files. Renaming an XMLService may generate behaviours in your applications.
NextAction: used after a transactional action to redirect to an XMLService which will display a new page.
XMLGram: contains the description of the data manipulation to operate. XMLGram contains SQL statements used to build the XML document.
XML: the XML data file used to design the XSL page.
XSLFile: is an XML file which contains the transformation elements to display the HTML page to client web browser. This file is used by XSLStudio. XSL file is equivalent to DFM for Delphi, FRM for VB, ASPX for WebForms.
Scope: default is Public values, no restriction applies. Private requires to add the http params XMLC_SupervisorEMail and XMLC_SupervisorPassword.

Icons right to the XMLGram, XML and XSL edit fields launch the XML editor XMLSpy. Only accessible in XMLRAD Professional version. You can configure your own XML editor.

XMLService Process Diagram

This diagram shows the main steps in the internal process of the XMLService to create the resulting html page :

HTTP request is dispatched to the XMLService by XMLApplication
XMLGram describes all the data operations to execute against the SQL server. In this example there is no SQL connection.
XMLGram processing builds the XML document. In this example, XMLGram builds the minimum XML document.
XML document is transformed into HTML using an XSL document
the resulting HTML page is sent back to the client browser through IIS

In XMLRAD Explorer, click on WSDL item:

XMLService WSDL Page

InputParams may be used to generate XML document at design time.
InputParams may be used to generate WSDL for your entire application at run-time, per XMLModule or per XMLService WSDL.
InputParams values are not used at run-time.
InputParams are used when you click on the run icon.
InputParams are stored in the XMLServices file.

Click on FormHelloWorld.xml item:

XML DataViewer Page

It displays the XML document produced by the XMLGram. While there is no XMLGram specified here, the XMLComponents Framework provides a basic XML document.
This XML document will be used by XSLStudio.

Step 7: XSLStudio

Click on FormHelloWorld.xsl item to display XSLStudio:

XSLStudio

XSLStudio is a tool to edit XSL pages within the web browser.
XSLStudio is a integrated designer very much like Delphi, VB or VS.Net.
XSLStudio runs inside XMLRAD and contains multiple frames :

The left frame contains the component palettes: HTML, HTML form, DHTML, Data, XSLT, XSLComponents.
The middle frame contains the designed page
The bottom frame is a multi-level hierachical property inspector

Over 50 components are delivered with XSLStudio. In the first component palette, you will find all basic HTML elements.
Lets review the other component palette:

XSLStudio, HTML form palette

XSLStudio, DHTML palette

XSLStudio, Data palette

XSLStudio, XSLT palette

XSLStudio, XSLComponents palette

Click in the bottom frame, on the Source tab:

XSLStudio, Source Page

This page displays the complete XSL source code of the current selected item.

Click on the caption of the tab in the middle frame:

XSLStudio, Source Page with a Selected Element

Selecting an element displays its XSL description.

Click on the Normal tab to get back to the property inspector:

XSLStudio, Normal Page with a Selected Element

The property inspector displays in a synthetic way the updatable values.
You can type in the edit field the following value: "HelloWorld ! by XSLStudio".
To save the update, you can click on the Save button or press Ctrl+S:

XSLStudio, Update element and save.

Once you clicked on the Save button, XSLStudio send the request to XMLRAD to update the element in the XSL file.
Then it displays back the page with the new values.

Select the element "This page was generated at", and select the "Horizontal Line" component by clicking on it:

XSLStudio, Select a component

Once you selected the "Horizontal Line" component, it is outlined.

XSLStudio, Component selected

to insert the component before the selected element, you will click in the property inspector (in the bottom frame) on the "p" element, to make it as selected.
Then you will right click on it to display the popup menu, and select the option "Insert Before":

XSLStudio, new component inserted

In the popup menu, once you selected the option "Insert Before", it will send the request to XSLStudio to insert in the XSL file the selected component "Horizontal Line".
It will displays the page with the new component added, before the paragraph "The date is ...".
The new component added is the selected element.

Step 8: Running HelloWorld

To run the application you can either

select the HelloWorld project item, and in the project configuration page click on the "run project" link
or select the appropriate XMLService item, right click on the XMLService item, and select in the popup menu the option Run this XMLService

HelloWorld invocation

It will open in a new browser the result page:

HelloWorld invocation

It launches a new web browser window, invokes the url: http://localhost/HelloWorldBin/HelloWorld.dll/FormHelloWorld.
The application displays the page with your last modifications.

Close the web browser, and lets get back to the Project Configuration page. Click, in the XMLRAD Explorer, on the HelloWorld project item:

Getting back to the Project Configuration Page

In the Project Configuration Page, click on the Statistics link:

Project Configuration Page

It will launch a new web browser window:

Application Statistics Page

The Statistics page displays that the first request last 47ms.
This time includes:

loading the application
creating 2 concurrent XMLCollection
initializing the XMLService HelloWorld
processing the HelloWorld page

If the action HelloWorld had an XMLGram, you could have a more detailed description about the elapsed time:

Application Advanced Statistics Page for XMLService HelloWorld

You can close this web browser window.

Step 9: Changing the Skin

To change the default skin of the application HelloWorld you will change the global parameters.
In XMLRAD Explorer, select GlobalParams item:

GlobalParams page

On the GlobalParams page, the default skin selected is graysquare:

Select "blue2001" skin

You will select the "blue2001" skin in the combobox.

Save the settings

Once you have selected the skin, save the settings, using the button "Save XMLC".

Saving values into the XML files will force XMLComponents Framework to reload the XML file and reinitialize the whole HelloWorld application on the next htp request invoking an XMLService in this application.

Any update to the XML file are instantaneously available for the next http request to the application.

Execute Project

In XMLRAD Explorer, select the HelloWorld project item, right click on the item, and select in the popup menu "Run Project" option.

It will launch a new web browser window:

HelloWorld with "blue2001"skin

Notice the new skin of the XMLApplication HelloWorld.

Close this web browser window.

Getting back to the Project Configuration Page

Get back to the Project Configuration Page, by selecting in XMLRAD Explorer the "HelloWorld" project item.

Access to the XMLComponents Framework HTTP Monitoring page:

Project Configuration Page

It will launch a new web browser window to display the XMLComponents Framework HTTP Monitoring Page:

XMLComponents Framework HTTP Monitoring Page

Notice the skin is also changed for XMLComponents Framework administration pages.

Summary

In this lesson:

you have reviewed step-by-step major XMLRAD features.
you manipulated XSLStudio basics to design an existing XSL page
you have run the application and inspect statistics
you changed the skin configuration for an application