Lasso Server-Side JavaScript Tutorial

This tutorial describes how to use server-side JavaScript and Lasso.

What You Should Already Know

Introduction

JavaScript is Netscape's cross-platform, object-based scripting language for client and server applications. Using JavaScript, you can easily create DHTML (Dynamic HTML) format pages which process user input and return database data.

Client-Side JavaScript

Most Web browsers can process client-side JavaScript statements which are embedded in HTML pages. When a browser (or client) requests such a page, the server sends the whole content of the document, including all HTML and JavaScript statements, to the client. The client then reads the page, from top to bottom, visually displaying the HTML results and executing JavaScript statements as it goes.

Server-Side JavaScript

On the server, JavaScript can also be embedded in HTML (or format) pages. The server-side statement can also be used to connect, retrieve and modify data from various datasources using Lasso. Format pages containing server-side JavaScript can, of course, also include client-side JavaScript.

A Very Simple Sample Format Page

In this section, you will create the "Hello World" page, a very simple sample page and get an introduction to embedding server-side JavaScript in HTML. To get started use your favorite text editor to create a text file called "hello.lasso" in your web root serving folder. The content of the file should read as follows:

<HTML>
<HEAD>
<TITLE>Hello World</TITLE>
</HEAD>
<BODY>
<H1>Hello World</H1>
<P><SERVER>write('Hello World!');</SERVER>
</BODY>
</HTML>

As you probably guessed, the SERVER tags enclose the server-side JavaScript statements that will be executed by Lasso. In this case, the statement write('Hello World!') displays the "Hello World!" string. The write function is very important in server-side JavaScript as it is used to add the values of JavaScript expressions to the HTML page sent back to the client.

All JavaScript statements contained between the opening and closing SERVER tags are processed by Lasso. This process happens before any data is returned to the client. In this case the following HTML will be sent to the browser to be displayed:

<HTML>
<HEAD>
<TITLE>Hello World</TITLE>
</HEAD>
<BODY>
<H1>Hello World</H1>
<P>Hello World!
</BODY>
</HTML>

When you embed server-side JavaScript in an HTML page, Lasso will execute the statements it encounters as it processes the page. Most statements between the <SERVER> and </SERVER> tags will not appear on the HTML page sent back to the client. However, when you use the write function in a SERVER tag, Lasso will dynamically generate new HTML embedded in the format page sent to the browser.

(Please note that the regular ([Tag]) and extended (<LDML TAG="...">) LDML syntaxes will not be recognized if placed inside the opening and closing SERVER tags)

Working with a Database

In this section we'll work with a fictitious database called Contacts.db. The Contacts.db database is very simple and structured as follows:

 
Database Name
   Contacts.db
Table/Layout Name
   MyContacts
     
Column Name
   Column Type
Contact ID
   Number, Unique, Auto-Generated
First Name
   Text
Last Name
   Text
Address
   Text
City
   Text
State
   Text
Zip
   Number
Phone
   Text

Finding All Records (Rows)

The LassoSession object is the interface through which database activity is performed. In order to perform database action you must create a new LassoSession object, as follows:

var mySession = new LassoSession();

The variable mySession now references a new LassoSession object.

The InputParameters object is used to define the criteria of a database action, such as the database name, table or layout name, action type (search, update, delete, etc.), search parameters and other important variables used when a LassoSession is executed. The InputParameters object is obtained only through the LassoSession object which contains it. For example, to obtain our LassoSession's InputParameters object we'll use the getInputParameters method as follows:

var myInput = mySession.getInputParameters();

The variable myInput now references the InputParameters object of mySession. In order to find all records in our database we'll need to specify the following:

The database name is specified through the databaseName property of our Inputparameters object:

myInput.databaseName = 'Contacts.db';

The layout or table name is specified through the tableName property of our Inputparameters object:

myInput.tableName = 'MyContacts';

The Lasso action is specified through the action property of our Inputparameters object. In this case the action will be findall:

myInput.action = 'findall';

Now that everything is setup, we can execute our session in order to perform database activity:

mySession.execute();

Displaying The Result Set

Now that we've executed the search, we need to display its result. The result of database actions is placed in the ResultSet object of the current LassoSession. The ResultSet object is retrieved using the LassoSession's getResultSet method.

For example:

var mySet = mySession.getResultSet();

The variable mySet now contains a reference to the ResultSet object of mySession.

In order to display the result we must loop through each record (row). The ResultSet object's next method is used to advance to the next row (record). The next method will return true until there a no more rows (records) in the result set

For example:

while (mySet.next())
{

}

would loop through each record (row) of our found set.

Now that we know how to loop through the found records, we can display some data. Data contained in columns (field) is retrieved using the column name properties of the ResultSet object.

For example:

mySet[ "First Name" ]

would return the data contained in the "First Name" column.

We can now display data from the result set:

while (mySet.next())
{

write(mySet["First Name"], " ", mySet["Last Name"], ", ", mySet["Phone"], "\n");
}

which would output something like:

John Doe, 800-555-1212
Bill Gates, 206-666-1313
Steve Jobs, 415-777-1414
...

Using the skill we've just learned we can now assemble a HTML format file which will display some of the contents of our Contacts.db database:

<HTML>
<HEAD>
<TITLE>My Contacts</TITLE>
</HEAD>
<BODY>
<H1>My Contacts</H1>
<SERVER>

var MySession = new LassoSession();

var myInput = mySession.getInputParameters();

myInput.databaseName = 'Contacts.db';
myInput.tableName = 'MyContacts';
myInput.action = 'findall';

mySession.execute();

var mySet = mySession.getResultSet();

while (mySet.next())
{

write(mySet["First Name"], " ", mySet["Last Name"], ", ", mySet["Phone"], "<BR>\n");
}

</SERVER>
</BODY>
</HTML>

Specifying Search Parameters

Now that we know how to find all records in a database, we'd like to be able to find records which match a certain search criteria. This is accomplished by specifying a search parameter. In this case, we'd like to find all records of people living in the Sate of New Jersey.

Search parameters are specified using the SearchColumn object. The SearchColumn object holds a name, value and operator. For example:

var mySearch = new SearchColumn("State", "NJ", lasso.opEquals);

The var mySearch nows holds our search criteria (i.e.: State = NJ)

We then need to add our search parameter to our InputParameters object searchColumns property. For example:

myInput.searchColumns.push(mySearch);

We can now change our HTML format page to include our search parameter:

<HTML>
<HEAD>
<TITLE>My Contacts in New Jersey</TITLE>
</HEAD>
<BODY>
<H1>My Contacts in New Jersey</H1>
<SERVER>

var mySession = new LassoSession();

var myInput = mySession.getInputParameters();

myInput.databaseName = 'Contacts.db';
myInput.tableName = 'MyContacts';
myInput.action = 'search';

var mySearch = new SearchColumn("State", "NJ", lasso.opEquals);
myInput.searchColumns.push(mySearch);

mySession.execute();

var mySet = mySession.getResultSet();

while (mySet.next())
{

write(mySet["First Name"], " ", mySet["Last Name"], ", ", mySet["Phone"], "<BR>\n");
}

</SERVER>
</BODY>
</HTML>

Please note that the Lasso action was also changed from findall to search, as we only want to display the records of people located in New Jersey.

Adding A Record

Adding a record (row) to our Contacts.db database is accomplished in a very similar way to what we've learned so far. We will need to specify the values to be added as input parameters and change the Lasso action to add.

For example to add the following

John Morris
12345 Elm Street
San Francisco, CA 94123
510-555-1616

to our Contacts.db database:

var mySession = new LassoSession();

var myInput = mySession.getInputParameters();

myInput.databaseName = 'Contacts.db';
myInput.tableName = 'MyContacts';
myInput.action = 'add';

myInput.searchColumns.push(new SearchColumn("First Name", "John"));
myInput.searchColumns.push(new SearchColumn("Last Name", "Morris"));
myInput.searchColumns.push(new SearchColumn("Address", "12345 Elm Street"));
myInput.searchColumns.push(new SearchColumn("City", "San Francisco"));
myInput.searchColumns.push(new SearchColumn("State", "CA"));
myInput.searchColumns.push(new SearchColumn("Zip", "94123"));
myInput.searchColumns.push(new SearchColumn("Phone", "510-555-1616"));

mySession.execute();

Please note that a Contact ID was not specified as it is generated automatically by our database.

Updating A Record

Once again updating a record (row) is accomplished using the same principles as described earlier in this tutorial.

In order to be able to update a record we need to specify a field (column) and value that will allow Lasso to find the correct record. A column (field) containing a unique value is referred to as the primary key column, the value it contains is referred to as the primary key value. It is important to ensure that the primary key value is unique or Lasso may not be able to find the record in the database. In this case, we've designed our Contacts.db database with a field containing a unique number for each record, the Contact ID.

To primary key column and primary key value are specified using the InputParameters object primaryKeyName and primaryKeyValue properties. For example to change the address in a record whose Contact ID is 16578:

var mySession = new LassoSession();

var myInput = mySession.getinputparameters();

myInput.databaseName = 'Contacts.db';
myInput.tableName = 'MyContacts';

myInput.primaryKeyName = 'Contact ID';
myInput.primaryKeyValue = '16578';

myInput.action = 'update';

myInput.searchColumns.push(new SearchColumn("Address", "12345 Elm Street, #F"));

mySession.execute();

Once the session is executed the Address column (field) of the record with a Contact ID of 16578 will be changed to 12345 Elm Street, #F.

Deleting A Record

The process of deleting a record (row) from a database is identical to the one used for updating. Of course, input parameters are not needed when deleting records, and the Lasso action must be changed to delete. For example, to delete the record we just updated:

var mySession = new LassoSession();

var myInput = mySession.getinputparameters();

myInput.databaseName = 'Contacts.db';
myInput.tableName = 'MyContacts';

myInput.primaryKeyName = 'Contact ID';
myInput.primaryKeyValue = '16578';

myInput.action = 'delete';

mySession.execute();

Once the session is executed the record with a Contact ID of 16578 will be deleted from the Contacts.db database.

Where To Go From Here

By completing this tutorial you have acquired the necessary skills to use server-side JavaScript and Lasso. You will now be able to browse through the Lasso JavaScript Objects Reference with a higher understanding of the concepts and features of the Lasso Server-Side JavaScript Module. But this is only the tip of the iceberg...

Lasso is a very powerful tool. As such, you should carefully read its reference manual and user guides. Especially considering that Lasso substitution tags can be called directly using server-side JavaScript.

A Server-Side JavaScript version of Lasso's Instant Web Publishing is available in the SSJS directory. The format files are fully commented line-by-line and provide an in-depth look at a full-featured Lasso solution built using Server-Side JavaScript.