Lesson 5: MyHelloWorld, your first project

Objective

In this lesson, you will build your very first XMLRAD application: MyHelloWorld.
You will manipulate XMLRAD and XSLStudio main features to build your first form.

Knowledge

You will learn the following techniques:

How to create a new project, a new XMLModule, a new XMLService
How to design a simple form using 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
XMLRAD IDE basics, please refer to lesson 3 and lesson 4.

Description

This lesson will describe more deeply every element of the structure of a project.
You will need to click on the different link as shown on screen shots.
You will manipulate XSLStudio basics to design a new XSL file.

Step 1: Creating the Project

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

To create a new project, you will use the "Create New Project" on the XMLRAD home page.

Create a new project

It will start a wizard.

Project wizard

Select the project template (Delphi 5 or 6, for instance). Expert training manual explains how to add your own project template.

Name the new project

Enter a unique name for this new project: "MyHelloWorld".

Entering an existing project name will cause some non-trivial behaviours in XMLRAD Explorer, even if you workaround.

Then click on the next button.

New project wizard, step 2

The second page of wizard prompt you to enter the path of the project and the XMLModule name "xmMyHelloWorld".

Entering a path which contains already an application may damage severely any file or application located at this location.

XMLRAD may also results in non-trivial behaviours.

The default project path is defined to the root folder where e-delos development tools have ben installed: C:\Program Files\e-delos\Projects\
To customize this default path, you will use the Preferences item in XMLRAD Explorer.
Preferences also handles all other default parameters.

If you select the option "Include 'portal' directory" it will include all skins, then you can unselect skins you don't want to copy in the new Portal directory.

Skins are used to render your application with graphics. The TabControl XSLComponent is using those skins to render the tabs and the page.
You can share skins using the SharedPortal.
You can define your own skins.

Then you can click on the "Create" button.

Project configuration page

Project creation involves following internal processings:

Copy the template directory to the destination directory. Project template contains the XMLServer.dll library (ISAPI DLL) which is used for design-time and run-time.
rename all files and their content according to the name the developer specified in the wizard. Rename XMLServer.dll to MyHelloWorld.dll.
copy the selected skins in the destination Portal directory
create the IIS aliases "MyHelloWorldBin" with eXecute permission, and MyHelloWorld alias with Read permission.

Project creation may take few seconds up to dozens of seconds.
This process is normal since it requires IIS to load all administrative component in order to register new aliases directly in IIS.
Otherwise, developers would have to do it by their own.

Anyway, developers should check that IIS aliases have been created correctly using Microsoft Management Console. this precaution may be done the first times.

Take time to review the generated parameters before going further.

Last recommendation would be to check that the application is running properly by clicking on the "Monitoring" link.

Since it is the first application and most of developers are in a rush, you will step recommendations :-)

Step 2: Creating a new XMLService

To create a new form, a new page, a new action, a new data selection or data update, you will create a new XMLService.
XMLServices are added in an XMLModule. An XMLModule is a container to group XMLServices.
You can add as many XMLServices as you want in an XMLModule, and you can create as many XMLModule as you want.
Recommendation: You will create a new XMLModule for every business module (group of XMLServices) working on the same group of data: Departments, Employees, Contacts, Workflow, Events, Planning, ...

The new XMLService you will create is the MyHelloWorld simple form to display "HelloWorld".

To create a new XMLService, select the XMLModule "xmMyHelloWorld" item in XMLRAD Explorer.
Right-click on the item, and select in the popup menu the option "Create a new XMLService".

Create a new XMLService

It will start the XMLService Wizard.

XMLService Wizard

The XMLService wizard will grant you the highest productivity you have ever seen.
XMLService Wizard propose to assist you during the creation of the following items :

List
DataGrid
ControlGrid
Empty Form
Simple Form
Master/Detail Form
Creation Form
Read-Only Form
Search Form
SOAP Request Form
SOAP Response Form
About
Delete, Insert, Update Statement

You will select the "Empty Form" option:

"Empty Form" Option

Click Next.

Naming step 1

Name the for MyHelloWorld, and use the "rename" button right to the "Name" text field:

Naming step 2

Click Next:

Generation

This last action will create the new XMLService and invoke XSLStudio to design the page:

it will generate on disk the XMLGram file
it will generate on disk the XSL file
it will register the XMLService in the project configuration file
it will invoke the DLL (MyHelloWorld.dll) to build the XML document and save it on disk. The XML document will be used by XSLStudio to design the XML document.
it will invoke XSLStudio with 2 parameters: XML document and XSL file

Once the XMLService is registered in the file MyHelloWorld.xmMyHelloWorld.XMLServices.xml the application MyHelloWorld.dll is ready to process HTTP request which invoke MyHelloWorld action.

Parameter XMLC_OutputFormat=XML is used to retrieve the XML document produced by this XMLService. http://xmlrad.com/HelloWorldBin/HelloWorld.dll/FormHelloWorld?XMLC_OutputFormat=XML
will produce equivalent XML document as MyHelloWorld.

You can invoke any XMLService with this additional parameter to retrieve only the XML stream.

Once the generation of the XSL file and its registration has been completed successfully, it will open XSLStudio within XMLRAD:

XSLStudio

Step 3: Customize your form using XSLStudio

You will follow the next steps to customize your first form:

Element selection

To select an element click on it in the main form. It will update the property inpsector below.

Element update

Type in the edit field the value you would like to customize, then click on the "Save" icon, or use Ctrl+S.

Customization saved

XSLStudio will update the XSL file, then process the newly updated XSL file with the existing XML document.

XSLStudio does not invoke the application MyHelloWorld.dll to retrieve the HTML page. XSLStudio processes it internally. It is using the actual XML document on disk.

If you would like to have different data in your XML document, you would need to update the file manually. But you need to know that this file can be overriden at any time if XSLStudio detects that the XMLGram is newer than the XML file on disk.

Step 4: Run the application

Now it is time to watch your first application running. In XMLRAD Explorer, select "MyHelloWorld" item, right click on the item, and select, in the popup menu, the option "run this XMLService":

Run the application

XMLRAD will open a new web browser to display the running application.

Run the application

This your first application with its first form running properly.

Recommendation: You should try to add few components in this form to get more familiar with XSLStudio and the different steps to update the XSL file and run the application.

Step 5: Review application params

Close the browser where is running your application, and get back to XMLRAD.

Let's review to the initialization parameters of the application. In XMLRAD Explorer, select the InitParams item:

Default Action

When creating the first form or XMLService, XMLRAD wizard will set the XMLC_DefaultAction parameter in the InitParams.XMLC section.
If you need to setup another DefaultAction, then select in the dropdown list a different XMLService.

Let's review the global parameters of the application. In XMLRAD Explorer, select the GlobalParams item.

XMLC_Skin customization

Change the skin to "msnblue", save the section and run the application one more time.

Run the application

In these steps, you will use the "Project Configuration Page" to start the application.
XMLRAD will open a new web browser to run your application.

MyHelloWorld with msnblue skin

Chaning the XMLC_Skin param in Global section changes the skin for the whole application. But it is only a default value.

Users can override this value passing in the http request params XMLC_Skin=graythin for instance.

Developers can automate custom skin support per user using cookies to store the skin selected by the user in a login box for example.

Close your web browser.

Try to access to the monitoring page, Statistics page from the "Project Configuration Page"

Summary

In this lesson:

you have created a new project and a new XMLModule,
you have created a new XMLService
You have customized your first form using XSLStudio
you changed the skin global parameter for the application