8.1 Creating the Hello World Project

Requirement: Version 9.0 or later of Aqua Data Studio is required for this tutorial. You may download a free evaluation of Aqua Data Studio at http://www.aquafold.com/aquadatastudio_downloads.html

Using this Tutorial

You can proceed with this tutorial in one of two ways. Create and edit the project manually or download and import the project into Aqua Data Studio. Both approaches result in a functioning "Hello World" project in Aqua Data Studio and then follow the same steps from there on out.  

Downloading Pre-built Project Code

The “Hello World” project can be downloaded from the AquaFold website and imported to Aqua Data Studio. You will not need to create a new project nor write any AquaScript code.

1. Open the link: http://www.aquafold.com/aquaproject_solutions_examples.html

2. Download the “Hello World" project and follow instructions on the page to mount the project to Aqua Data Studio.

3. Once the project is mounted, proceed to the Step 5. “Using and Debugging the Project in Aqua Data Studio” section of this tutorial.

 

Creating and Editing Project Manually

If you want to manually create the "Hello World" project and write AquaScript code, start with the Step 1 section below.

 

Step 1. Create a New Project in Aqua Data Studio.

1. Launch Aqua Data Studio.

2. Click “Projects” tab at the bottom of the Aqua Data Studio application window.

3. Right-click in the "Projects” window and select “New Project” item from the popup menu.

 

4. In the “New Project” dialog, type the name and the file system path for the project. (You can use the browse button “…” to navigate through the file system.) For this example, the name of the project is “HelloWorld”, and the path is “C:\Users\aquadataserver\”.

5. Click the “OK” button, and Aqua Data Studio will create a new folder called “HelloWorld” in the “C:\Users\aquadataserver\” directory.

 

Aqua Data Studio will also automatically create three sub-folders in the “HelloWorld” folder, named “AquaScripts”, “Servers” and “User Files” as shown in the screen shot below.

 

Step 2.  Writing Your First AquaScript.

1. Expand the “HelloWorld” folder and Right-click on the “AquaScripts” subfolder. Select the “New” item from the dropdown list.

 

2. In the “Create New Script” dialog window, enter the name of the AquaScript file, “HelloWorld.xjs”. This will create a file with the corresponding name in the “AquaScripts” folder.

3. Expand the “AquaScripts” folder and double-click on the newly created script file.  In the text area on the right pane of the window, enter the following code:

aqua.response.write("Hello World!");
aqua.console.println("Hello World! Output to console.");

The first line of the code will render the script output to the browser window. The second line output will be visible only in the console below the script editor text area.

4. Click on the “Run” (green triangle) button in order to run the script in the console.

 

5. Click on the “Debug in Browser” button (green triangle with a globe symbol), two buttons to the right of the “Run” button. This will open a browser window, and Aqua Data Studio will return any script output to the browser.

 

Step 3. Building a Simple Interactive AquaScript with Basic GUI Controls.

1. Create a new AquaScript called "typeHelloWorld.xjs" in the AquaScripts folder by following the instructions in Step 2.

2. In the script editor, enter or copy the following code.

var myvar = aqua.request.getParameter("myinput");

try
{
             
     var f = aqua.form.newForm(1,1);
     f.setAction("", "get", "");
     f.setHeader("Type in the text filed and click 'Submit' button.","")
     f.addTextField(0,0,"myinput", myvar );
     f.addSubmitButton(0, 0, "myinput", "Submit");
     aqua.response.write(f);
    
     if (myvar != null)
     {
        aqua.response.write("You typed: " + myvar);
     }
}

catch (err)
{
    aqua.response.write("A server error occurred. Please contact your server administrator.");
    aqua.console.println(err.lineNumber + ": " + err );
}

This script will create an HTML form with a text input field and a “Submit” button. The text entered in the text field will be displayed on the web page upon clicking on the “Submit” button.

3. Click on the “Debug in Browser” button to run the script in the browser.  The output will be as follows.

 

This AquaScript does not produce any console output unless an error occurs. In case of an error, the script prints the line number where the error occurred along with the error message to the console, and the script prints “A server error occurred. Please contact your server administrator” error message in the browser. The final block of code handles this error situation:

catch (err)
{
    aqua.response.write("A server error occurred. Please contact your server administrator.");
    aqua.console.println(err.lineNumber + ": " + err );
}

 

Step 4.  Adding  a Toolbar for Navigation Between the Scripts.

We now have two scripts in the HelloWorld project.  Instead of executing each of them individually from the script editor, we have the ability to add a toolbar to our HTML page that allows us to directly invoke either script.

We can leverage the Aqua Open APIs to create such a toolbar with just a few additional lines of code.

 

Create and Save Image Files for Icons.

1. Download the Hello World project archive from the following page:  http://www.aquafold.com/aquaproject-solution-examples.html

2. Extract the ZIP file and take two image files green.png and blue.png that are images of green and blue squares. (Alternatively you may try to use or create your own image files.)

3. In the project “User Files” folder create the “Icons” subfolder and place the images in it.

Images can be referred in the code by the URL which is returned by the following API function:

 

aqua.project.getFileURL("Icons/green.png") // Returns a String URL to the image. Used in the dashboard.addToolbarButton() function.

 

4. In the script editor, add the following code to both scripts. (Refer to the screenshots below to see the exact places where to enter the following lines of code.)

var urlEntryPoint = aqua.project.getDashboardURL() + "/" ;

buildToolbar();

function buildToolbar()
{
   var dashboard = aqua.response.dashboard;
   dashboard.addToolbarButton ( urlEntryPoint + "HelloWorld.xjs", "Hello World", "", aqua.project.getFileURL("Icons/green.png") );
   dashboard.addToolbarSeparator();
   dashboard.addToolbarButton (urlEntryPoint + "typeHelloWorld.xjs", "Type-in Hello World", "", aqua.project.getFileURL("Icons/blue.png") );
}

 

HelloWorld.xjs

 

TypeHelloWorld.xjs

 

Note that the code handling the toolbar is identical in both scripts.

 

5. “Using and Debugging the Project in Aqua Data Studio” section.

1. Click on the “Debug in Browser” button to run the script in the browser. Either script can be started. The resulting HTML page will include a toolbar with links to the scripts “Hello World” and “Type-in Hello World”. Clicking on a link will launch the corresponding script.

 

Continue to 8.2 Creating a Project Container