Lasso Documentation

Overview describes LassoApps and their benefits for distributing Lasso-based solutions.
Administration explains how to enable LassoApp serving and how LassoApps are cached.
Serving LassoApps explains how LassoApps are served including how to serve LassoApps from the Web server root and the LassoApps folder in the Lasso Professional 8 application folder.
Preparing Solutions documents how to prepare a Lasso-based solution for conversion into a LassoApp.
Building LassoApps explains how to use [code]LassoApp Builder [/code]in Lasso Site Administration or the [code][LassoApp_Create][/code] tag to build a LassoApp.
Tips and Techniques provides helpful information about how to create professional quality LassoApps.

[p]LassoApps allow entire Lasso-based solutions, including Lasso pages and image files, to be packaged into a single archive file with a [code].LassoApp [/code]extension. A compiled LassoApp can be easily distributed and executed on any machine running Lasso Professional 8. [/p]

[note][b]Important [/b]– Although it is difficult to extract the original LassoScript from a LassoApp it is possible to see the strings that are referenced within the LassoApp. LassoApps should be used to protect your LassoScript code, but are not a recommended method of storing passwords or other sensitive data. [/note]

[p]LassoApps offer the following benefits: [/p]

[def]Performance [/def]– LassoApps are loaded into RAM and cached for efficient serving. All Lasso pages within the LassoApp are pre-parsed and served without additional disk accesses. LassoApp solutions generally provide better performance than their non-LassoApp counterparts.
[def]Size [/def]– LassoApps are stored efficiently as a single file. The overhead associated with multiple format and image files is reduced. Redundant data within Lasso pages is optimized so only a single copy of duplicate strings is stored.
[def]Flexibility [/def]– LassoApps can be served from within the Web server root as normal Lasso pages or they can be served from within the [code]LassoApps[/code] folder in the Lasso Professional 8 application folder. LassoApps can also be loaded at startup or used as tag libraries.
[def]Security [/def]– The code within a LassoApp is stored securely in a byte-compiled form. It is not possible to extract Lasso pages and code from a LassoApp.
[def]Portability [/def]– A LassoApp is an ideal way to distribute a solution by copying and installing a single file with all internal paths intact. LassoApps are fully cross platform. They can be created on either Mac OS X or Windows 2000 and then deployed on either platform without modifications.

[p]LassoApps are stored in a custom binary file format with a [code].LassoApp [/code]extension. LassoApps can be created programmatically using the[code] [LassoApp_Create] [/code]tag or through the LassoApp Builder located in Lasso Site Administration. [/p]

[p]LassoApps can be used for any of the following purposes: [/p]

[def]Packaged Solutions [/def]– LassoApps enable developers to create packaged solutions that can be easily installed by end-users and served by any copy of Lasso Professional 8. LassoApps are placed in the Web serving folder and referenced like a Lasso-based Lasso page or served from the [code]LassoApps[/code] folder in the Lasso Professional 8 application folder.
[def]Client Solutions [/def]– LassoApps enable developers to deliver solutions to clients in a convenient, secure package. This is ideal so clients can evaluate the functionality of a solution without requiring access to the source code. LassoApps are placed in the Web serving folder and referenced like a Lasso-based Lasso pageor served from the [code]LassoApps[/code] folder in the Lasso Professional 8 application folder.
[def]Tag Libraries [/def]– LassoApps can define a set of tags in a particular namespace and be installed into the [code]LassoLibraries [/code]folder in the Lasso Professional 8 application folder. Lasso will automatically load the LassoApp and all the tags it contains if any of the tags within it are called.
[def]Startup Libraries [/def]– LassoApps can be installed into the [code]LassoStartup [/code]folder in the Lasso Professional 8 application folder. The default page of the LassoApp will be executed as a library when Lasso Service starts up and can define custom tags or perform initialization code.
[def]Secure Includes [/def]– LassoApps can be included into other Lasso pages using the [code][Include][/code] or [code][Library][/code] tag. LassoApps can be used to define custom tags or to provide HTML code in a secure manner.

[p]See the sections that follow for information about enabling LassoApps within Lasso Site Administration, preparing an existing solution for compilation as a LassoApp, and detailed instructions about building LassoApps. [/p]

Table 1: LassoApp Tags

[table][tr][th]Tag[/th][th]Description[/th][th] [/th][/tr]

[tr][td][LassoApp_Create][/td][td]Creates a LassoApp. Requires three parameters: the -Root of the LassoApp, the -Entry page or default page, and the -Result path where to write the completed LassoApp. [/td][/tr]

[tr][td][LassoApp_Dump][/td][td]Removes a LassoApp from the cache. Removes a specific LassoApp if a name is specified or all LassoApps if no name is specified. [/td][/tr]

[tr][td][LassoApp_Link][/td][td]Defines a link to a file within a LassoApp. This tag must be used to mark all links in HTML anchor, form, and image tags and Lasso page references in [Include] and [Library] tags. [/td][/tr]

[tr][td]-ResponseLassoApp[/td][td]Returns a specific page from a LassoApp. [/td][/tr]

[/table]

Default LassoApps

[p]Lasso Professional 8 relies on LassoApps for all of its administration interfaces, online documentation, and server start-up code. Lasso Professional 8 ships with the following LassoApps. [/p]

[def]ServerAdmin.LassoApp [/def]– The Lasso Server Administration interface pre-installed in the [code]LassoApps [/code]folder within the Lasso Professional 8 application folder. This LassoApp is used to configure Lasso’s server-wide preferences and to create sites.
[def]SiteAdmin.LassoApp [/def]– The Lasso Site Administration interface pre-installed in the [code]LassoApps [/code]folder within the Lasso Professional 8 application folder. This LassoApp is used to configure Lasso Security, to establish the global preferences of a site, to browse existing databases, to monitor the email and event queues, and to create new databases and LassoApps.
[def]DatabaseBrowser.LassoApp [/def]– The database browser allows site visitors to browse through any databases that they have permission to access. This LassoApp is pre-installed in the [code]LassoApps [/code]folder within the Lasso Professional 8 application folder.
[def]GroupAdmin.LassoApp [/def]– The Group Administration interface is pre-installed in the [code]LassoApps [/code]folder within the Lasso Professional 8 application folder. This LassoApp allows group administrators to create users and assign them to groups and for users to change their passwords.
[def]LDMLReference.LassoApp [/def]– The Lasso Reference is the definitive source for information about each tag in Lasso Dynamic Markup Language. This LassoApp is pre-installed in the [code]LassoApps [/code]folder within the Lasso Professional 8 application folder.
[def]RPC.LassoApp [/def]– This LassoApp responds to incoming remote procedure calls using the XML-RPC format. This LassoApp is pre-installed in the [code]LassoApps [/code]folder within the Lasso Professional 8 application folder.
[def]Startup.LassoApp [/def]– This LassoApp defines custom tags and performs initialization for Lasso Security, the email sender, and the event queue. This LassoApp is installed in the [code]LassoStartup [/code]folder and must be present for Lasso Service to start.

[p]The code for each of these LassoApps can be found within the Documentation Folder > 2 - Language Guide > LassoApps[code] [/code]folder. This code is provided as-is without any warranty or support. [/p]

[note][b]Warning: [/b]Do not compile LassoApps with the same name as the LassoSoft supplied LassoApps (e.g. [code]Startup.LassoApp [/code]or Site[code]Admin.LassoApp[/code]). LassoSoft cannot provide any support for customized versions of these LassoApps or for Lasso Professional 8 installations which make use of customized versions of these LassoApps. [/note]

Administration

[p]This section discusses how to enable or disable LassoApp support and how administer the LassoApp cache using Lasso tags and within Lasso Site Administration. [/p]

Enabling LassoApp Support

[p]Lasso Site Administration includes a global setting to enable or disable LassoApp support. This setting can be found in the Setup > Global Settings > LassoApps section of Lasso Site Administration. [/p]

[p]When LassoApp support is disabled only the LassoApps which ship with Lasso Professional 8 can be served (including [code]Admin.LassoApp[/code], [code]GroupAdmin.LassoApp[/code], [code]LDMLReference.LassoApp[/code], and [code]Startup.LassoApp [/code]in the [code]LassoStartup [/code]folder. [/p]

[p]Please see the Site Utilities chapter of the Lasso Professional 8 Setup Guide for more information about enabling or disabling LassoApp support. [/p]

LassoApp Cache

[p]LassoApps are cached in RAM for efficient serving. Each LassoApp only needs to be read from disk once and from then on is served from high-speed memory. LassoApps are read from disk automatically the first time they are called so there is no need to pre-load them (unless the fastest performance is required on the first load). [/p]

[p]Since LassoApps are only read from disk the first time they are called it is necessary to ask Lasso to dump any LassoApps that need to be re-read from disk. For example, this is necessary if a new version of a LassoApp is copied into the Web serving folder. [/p]

[p]LassoApps can be removed from the cache using the Cache page in the Setup > Global Settings > LassoApps section of Lasso Site Administration. See the Site Utilities chapter of the Lasso Professional 8 Setup Guide for more information. LassoApps can also be removed from the cache programatically using the following steps. [/p]

To remove a LassoApp from the cache:

[p]Use the [code][LassoApp_Dump] [/code]tag with the name of the LassoApp. The following example shows how to remove a LassoApp named [code]MySolution.LassoApp [/code]from the cache. The LassoApp will be read from disk the next time the LassoApp is called. [/p]

[pre][LassoApp_Dump: 'MySolution.LassoApp'] [/pre]

To remove all LassoApps from the cache:

[p]Use the [code][LassoApp_Dump] [/code]tag without any parameters The following example shows how to remove all LassoApps from the cache. Each LassoApp will be read from disk the next time it is called. [/p]

[pre][LassoApp_Dump] [/pre]

To preload a LassoApp into the cache:

[p]LassoApps can be preloaded into the cache by calling them from a Web browser or by using the [code][Include_URL][/code] tag. The following example shows how to preload a LassoApp named [code]MySolution.LassoApp [/code]using[code] [Include_URL][/code]. [/p]

[pre][Include_URL: 'http://www.example.com/Lasso/MySolution.LassoApp'] [/pre]

[p]If a LassoApp will be used frequently on the server it can be preloaded using the [code][Event_Schedule][/code] tag in a Lasso page in [code]LassoStartup[/code]. The following code would preload a LassoApp named [code]MySolution.LassoApp [/code]five minutes after Lasso Service is started. The delay is specified so the other initialization steps have a chance to complete before the LassoApp is loaded. [/p]

[pre][Event_Schedule: -URL='http://www.example.com/MySolution.LassoApp',
-Delay=5] [/pre]

Serving LassoApps

[p]LassoApps can be served the same way as Lasso pages. They can be served from the Web server root or the [code]LassoApps[/code] folder in the Lasso Professional 8 application folder, included in other Lasso pages, or placed in the [code]LassoStartup [/code]folder and executed at startup. This section includes information about how to use LassoApps in each of these situations. [/p]

Web Serving Folder

[p]LassoApps which are placed in the Web serving folder are served like any Lasso-based Lasso pages. When they are referenced by name in HTML anchor tags, HTML form actions, [code][Include][/code] or [code][Library][/code] tags, or as the target of a [code]-Response…[/code] tag. The entry page for the LassoApp is always the page that is served. [/p]

[p]Since LassoApps are cached, only one copy of each named LassoApp can be served from a single site in Lasso Professional 8. If a second LassoApp with the same name is called the cached copy of the first LassoApp will be served in its place. It is important to ensure that multiple copies of the same LassoApp are identical or unexpected results can occur. [/p]

LassoApps Folder

[p]LassoApps which are placed in the LassoApps folder in the Lasso Professional 8 application folder are served when they are referenced by name in HTML anchor tags, HTML form actions, [code][Include][/code] or [code][Library][/code] tags, or as the target of a [code]-Response…[/code] tag. The entry page for the LassoApp is always the page that is served. [/p]

LassoApp Links

[p]The links in the entry page must be marked with the [code][LassoApp_Link][/code] tag in order to reference other files contained within the LassoApp. See the section on Preparing Solutions for more details. [/p]

[p]The [code][LassoApp_Link][/code] tag modifies internal links to be of the form [code]LassoAppName.FileNumber.LassoApp[/code]. For example, the link to the entry page of a LassoApp named [code]MySolution.LassoApp[/code] would be formated as follows in the source of the LassoApp. [/p]

[pre]<a href="[LassoApp_Link: 'default.lasso']"> Entry Page </a> [/pre]

[p]After the LassoApp is compiled, this link will be changed to the following code. The number referenced in the link is determined when the LassoApp is compiled. This number should not be relied on since it may change if the LassoApp is recompiled. [/p]

[pre]<a href="MySolution.0.LassoApp"> Entry Page </a> [/pre]

[p]The conversion of links marked [code][LassoApp_Link][/code] is handled automatically. No further action beyond marking internal links with the[code] [LassoApp_Link][/code] tag is required. The site visitor will be able to visit any pages which can be reached from the entry page within the LassoApp and will be able to view any linked images within the LassoApp. [/p]

To reference pages in a LassoApp from outside the LassoApp:

[p]Individual pages within a LassoApp can be referenced using the [code]-ResponseLassoApp[/code] tag as a parameter to the LassoApp name. For example, the entry page (e.g. [code]default.lasso[/code]) of the [code]MySolution.LassoApp [/code]LassoApp could be referenced explicitly using the following link. [/p]

[pre]<a href="MySolution.LassoApp?-ResponseLassoApp=default.lasso"> Entry Page </a> [/pre]

[p]The path specified for the[code] -ResponseLassoApp[/code] tag should be relative to the folder which was compiled into the LassoApp. The [code]-ResponseLassoApp[/code] tag should not be used as part of a database action or to specify the response file for a database action. It should only be used to return a specific Lasso page or image file from within a LassoApp. [/p]

[note][b]Note: [/b]By using this technique, even files and images within a LassoApp which cannot be reached from the entry page can be viewed if the visitor knows the path to the file they want to view within the LassoApp. [/note]

Database Action Responses

[p]The entry page of a LassoApp can be used as the response to a database action by specifying the path to the LassoApp as the parameter for any of the [code]-Response…[/code] command tags. The following form returns the entry file of [code]MySolution.LassoApp [/code]as the response to a [code]-FindAll [/code]action. [/p]

[pre]<form action="Action.Lasso" method="POST">
<input type="hidden" name="-FindAll" value="">
<input type="hidden" name="-Database" value="Contacts">
<input type="hidden" name="-Table" value="People">
<input type="hidden" name="-Response" value="MySolution.LassoApp">
<input type="submit" name="-FindAll" value="Find All People">
</form> [/pre]

[note][b]Note: [/b]The [code]-ResponseLassoApp[/code] tag cannot be used in conjunction with a database action to return a particular page from within a LassoApp. Only the entry page of a LassoApp can be returned as the result of a database action. [/note]

Lasso Libraries Folder

[p]A LassoApp can define a set of custom tags which are all in the same namespace for on-demand loading. The LassoApp should be named with the same name as the namespace of the tags. For example, a LassoApp named [code]Example.LassoApp[/code] could define a set of custom tags in the [code]Example_[/code] namespace [code][Example_TagOne][/code], [code][Example_TagTwo][/code], etc. [/p]

[p]When Lasso is asked to execute a tag that has not yet been defined it checks in the LassoLibraries folder for a tag library with the name of the namespace of the desired tag. The entry page of a matching LassoApp will be loaded defining all of the tags within. [/p]

[note][b]Note: [/b]All of the tags must be defined within the entry page of the LassoApp. [/note]

Lasso Startup Folder

[p]The entry page of a LassoApp can be executed when Lasso Service starts up by placing the LassoApp file within the [code]LassoStartup [/code]folder inside the Lasso Professional 8 application folder. The entry file can include as many other files within the LassoApp as it needs in order to perform the desired actions. For example, the [code]Startup.LassoApp[/code] LassoApp located in the [code]LassoStartup [/code]folder executes code which defines a number of custom tags (e.g. [code][Email_Send][/code], [code][Include_URL][/code]) in Lasso Professional 8. Because [code]Startup.LassoApp[/code] is located in the [code]LassoStartup[/code] folder, these custom tags are automatically available upon startup. [/p]

Preparing Solutions

[p]Any Lasso-based solution can be compiled into a LassoApp following these preparation instructions. These steps require changes to be made to each Lasso page which needs to link to another file within the LassoApp and requires files that need to remain user customizable to be stored and referenced outside the LassoApp. [/p]

[p]The following steps need to be performed to prepare a solution for compilation as a LassoApp. [/p]

The entire solution must be contained in a single folder including all Lasso pages and image files which will be compiled into the LassoApp. The folder should only contain text and GIF or JPEG image files.
The solution must have a single entry point. One file will be loaded when the LassoApp is called, this file must reference other files within the LassoApp either through HTML links, HTML form actions, redirects or [code][Include][/code] tags.
All links to files or images within the LassoApp must be marked with the [code][LassoApp_Link][/code] tag. This tag changes relative paths to a LassoApp specific format.

Preparing Links

[p]The biggest change required to make most solutions ready to be compiled as a LassoApp is to mark all of the links which reference other files within the solution with the [code][LassoApp_Link][/code] tag. All HTML anchor [code]<a ref=" … "> … </a>[/code], image [code]<img>[/code], and form [code]<form> … </form> [/code]tags which reference other files within the LassoApp need to be marked as well as[code] [Include][/code] and[code] [Library][/code] tags. The [code][LassoApp_Link][/code] tag is processed when the solution is compiled into a LassoApp. [/p]

[p]Named anchors, links to targets within the same file, [code]mailto [/code]links to email addresses, and links to Web sites on other servers do not need to be marked with the [code][LassoApp_Link][/code] tag. [/p]

[p]The [code][LassoApp_Link] [/code]tag can be safely used in any Lasso solution whether it is compiled into a LassoApp or not. When used in a non-compiled solution the [code][LassoApp_Link] [/code]simply returns the specified link value unchanged. [/p]

[note][b]Note: [/b]The[code] [LassoApp_Link][/code] tag cannot be used within custom tags or custom data types. Since a custom tag could be called from a different LassoApp than the one in which it is defined (e.g. if a custom tag is defined in the [code]LassoStartup [/code]folder, there is no way for Lasso to determine to which LassoApp the [code][LassoApp_Link][/code] tag should refer. See the end of this section for tips on working with custom tags within LassoApps. [/note]

To prepare links to other files within the LassoApp:

Anchor tags which reference other files within the LassoApp need to be marked with the[code] [LassoApp_Link] [/code]tag. The [code][LassoApp_Link] t[/code]ag will accept any relative path which is legal within an HTML anchor tag including those which contain [code]../[/code] to reference files higher in the folder structure. The following example shows an HTML anchor tag that references a file named [code]default.lasso [/code]contained in a folder named [code]People[/code].

[pre]<a href="People/default.lasso"> People Page </a> [/pre]

After being marked with the[code] [LassoApp_Link] [/code]tag this anchor tag appears as follows.

[pre]<a href="[LassoApp_Link: 'People/default.lasso']"> People Page </a> [/pre]

[note][b]Note: [/b]Do not mark named anchors, links to targets within the same file, [code]mailto [/code]links to email addresses, or links to Web sites on other servers with the [code][LassoApp_Link][/code] tag. [/note]

Image tags should be marked with the [code][LassoApp_Link][/code] tag if the referenced image is contained within the compiled LassoApp. The following example shows an HTML image tag that references a file named [code]boat.gif [/code]contained in a folder named [code]Images[/code].

[pre]<img src="Images/boat.gif" height="288" width="288"> [/pre]

After being marked with the[code] [LassoApp_Link] [/code]tag this anchor tag appears as follows.

[pre]<img src="[LassoApp_Link: 'Images/boat.gif']" height="288" width="288"> [/pre]

The action parameter for HTML[code] <form> [/code]tags should be marked with the [code][LassoApp_Link] [/code]tag if it reference a Lasso page explicitly. The following example shows an HTML [code]<form> [/code]tag that references a file named [code]result.lasso [/code]which is contained in the same folder as the current page.

[pre]<form action="result.lasso" method="POST">
…
</form> [/pre]

After being marked with the[code] [LassoApp_Link] [/code]tag this HTML [code]<form> [/code]tag appears as follows.

[pre]<form action="[LassoApp_Link: 'result.lasso']" method="POST">
…
</form> [/pre]

If an HTML[code] <form> [/code]tag references [code]Action.Lasso [/code]as its action then the value parameter for the appropriate [code]<input> [/code]tag for the [code]-Response[/code] command tag should be marked with the [code][LassoApp_Link][/code] tag. The following example shows an HTML [code]<form> [/code]tag that references [code]Action.Lasso. [/code]The response for the form is specified as [code]response.lasso [/code]in a hidden input for the [code]-Response [/code]command tag.

[pre]<form action="Action.Lasso" method="POST">
<input type="hidden" name="-Response" value="response.lasso">
…
</form> [/pre]

After being marked with the[code] [LassoApp_Link] [/code]tag the hidden input appears as follows.

[pre]<form action="Action.Lasso" method="POST">
<input type="hidden" name="-Response"
value="[LassoApp_Link: 'response.lasso']">
…
</form> [/pre]

The file parameter for an [code][Include][/code] or[code] [Library][/code] tag needs to be marked using the[code] [LassoApp_Link][/code] tag. The following examples show an [code][Include][/code] tag for a file named [code]include.lasso [/code]and a [code][Library] [/code]tag for a file [code]library.lasso[/code].

[pre][Include: 'include.lasso'] [/pre]

[pre][Library: 'library.lasso'] [/pre]

After being marked with the[code] [LassoApp_Link] [/code]tag the tags appear as follows.

[pre][Include: (LassoApp_Link: 'include.lasso')] [/pre]

[pre][Library: (LassoApp_Link: 'library.lasso')] [/pre]

The response parameter for a[code] [Link_…] [/code]tag needs to be marked using the [code][LassoApp_Link][/code] tag. For example, the [code][Link_DetailURL][/code] tag accepts a [code]-Response[/code] parameter which specifies the Lasso page that should be returned when the link is selected. The following example shows a [code][Link_DetailURL] [/code]tag used within an HTML anchor [code]<a>[/code] tag.

[pre]<a href="[Link_DetailURL: -Response='response.lasso', -Table='People']"> … </a> [/pre]

After being marked with the[code] [LassoApp_Link][/code] tag, the [code][Link_DetailURL][/code] tag appears as follows.

[pre]<a href="[Link_DetailURL: -Response=(LassoApp_Link: 'response.lasso'),
-Table='People']"> … </a> [/pre]

Notice that only the name of the response page is marked with the [code][LassoApp_Link][/code] tag, not the entire [code]href [/code]attribute of the anchor tag.

To reference files within a LassoApp from a custom tag:

[p]The[code] [LassoApp_Link][/code] tag cannot be used within custom tags and custom data types. The following techniques can be used to reference files within a LassoApp from custom tags or custom data types. [/p]

References to files can be stored in variables and referenced by variable name within a custom tag. In the following example a reference to a file [code]include.lasso [/code]is stored in a variable named [code]IncludeFile[/code]. This variable is then referenced within a custom tag.

[pre][Variable: 'IncludeFile' = (LassoApp_Link: 'include.lasso')]
…
[Define_Tag: 'myInclude']
[Return: (Include: $IncludeFile)]
[/Define_Tag] [/pre]

References to LassoApp files can be passed into custom tags as parameters. In the following example a reference to a file [code]include.lasso [/code]is passed as a parameter to a custom tag.

[pre][Define_Tag: 'myInclude', -Required='IncludeFile']
[Return: (Include: #IncludeFile)]
[/Define_Tag]
…
[myInclude: (LassoApp_Link: 'include.lasso')] [/pre]

Building LassoApps

[p]LassoApps can be built programmatically using the [code][LassoApp_Create] [/code]tag or can be built using [code]LassoApp Builder [/code]provided in the Build > LassoApp Builder section of Lasso Site Administration. [/p]

Lasso Site Administration

[p]In order to build a LassoApp using [code]LassoApp Builder[/code], the folder containing the files which will be compiled into the LassoApp must be within the Web server root or placed in the [code]Lasso Admin/BuildLassoApps [/code]folder within the site folder of the current site (located within the Lasso Professional 8 application folder). [/p]

[p]The path to the root of the LassoApp is entered or the name of the folder to be converted to a LassoApp is selected from a pop-up menu. The name of the entry file within the folder must also specified. Any errors which occur are reported within the interface. If successful, the completed LassoApp is created in the parent of the source folder. The LassoApp will have the same name as the source folder with [code].LassoApp[/code] appended. [/p]

[p]See the Site Administration Utlities chapter of the Lasso Professional 8 Setup Guide for complete documentation of [code]LassoApp Builder[/code]. [/p]

To create a LassoApp using LassoApp Builder:

Place all of the files which will be compiled into the LassoApp into a single folder. The folder should only contain Lasso pages and image files. All of the Lasso pages should have been prepared following the instructions in the Preparing Solutions section of this chapter.

For example, place the Lasso pages within a folder named [code]MySolution[/code]. This folder contains the entry file [code]default.lasso[/code], a folder of included sub-files, and a folder of images.

[note][b]Note: [/b]All of the files within the source folder will be compiled into the LassoApp even if some of the files are never referenced. In order to create the smallest LassoApps possible, any files which are not needed should be removed from the source folder prior to compiling a LassoApp [/note]

Note the location of the [code]MySolution[/code] folder within the Web server root or place the folder [code]MySolution [/code]into the [code]Admin/BuildLassoApps [/code]folder within the Lasso Professional 8 application folder.

Load Lasso Site Administration in a Web browser and go to the Build > LassoApp Builder section.

[pre]http://www.example.com/SiteAdmin.LassoApp [/pre]

Enter the path to the [code]MySolution[/code] folder or choose [code]MySolution [/code]from the pop-up menu and ensure that the entry file is [code]default.lasso[/code]. Select the Create LassoApp button to create the LassoApp in the [code]Admin/BuildLassoApps[/code] folder. Or, select the Download LassoApp button to download the created LassoApp through the Web browser.
[note][b]Note: [/b]If the name of the source folder is not present in the pop-up menu select the [code]Refresh [/code]button. [/note]

If any errors are reported, correct them within the Lasso pages of the solution and then return to Lasso Site Administration to build the LassoApp again. The [code]LassoApp Builder [/code]must complete without any errors in order for a LassoApp file to be created.

The completed LassoApp will be in the [code]Admin/BuildLassoApps [/code]folder named [code]MySolution.LassoApp[/code] or will be downloaded through the Web browser. This file should be copied into the Web serving folder and can then be loaded through a Web browser. If this solution were placed at the root of the Web serving folder it could be loaded through the following URL.

[pre]http://www.example.com/MySolution.LassoApp [/pre]

[LassoApp_Create] Tag

[p]In order to build a LassoApp using the [code][LassoApp_Create][/code] tag the files which will be compiled into a LassoApp need to be placed in a single folder on the same machine as Lasso Service. [/p]

[p]The parameters for the [code][LassoApp_Create][/code] tag are detailed in Table 2: [LassoApp_Create] Tag Parameters. An example of using the tag to create a LassoApp follows. The [code][LassoApp_Create][/code] tag will return [code]0 [/code]if it is successful creating a LassoApp or an error message otherwise. The tag will replace an existing LassoApp file if the[code] -Result[/code] parameter specifies a file that already exists. [/p]

Table 2: [LassoApp_Create] Tag Parameters

[table][tr][th]Parameter[/th][th]Description[/th][th] [/th][/tr]

[tr][td]-Root[/td][td]The folder which contains the files that will be compiled into the LassoApp. [/td][/tr]

[tr][td]-Entry[/td][td]The default Lasso page within the LassoApp which will be loaded when the LassoApp is called. Should be specified relative to the root folder. [/td][/tr]

[tr][td]-Result[/td][td]The destination file name for the created LassoApp. Must end in the file suffix .LassoApp. [/td][/tr]

[/table]

To create a LassoApp using the [LassoApp_Create] tag:

Place all of the files which will be compiled into the LassoApp into a single folder. The folder should only contain Lasso pages and image files. All of the Lasso pages should have been prepared following the instructions in the Preparing Solutions section of this chapter. This folder contains the entry file [code]default.lasso[/code], a folder of included sub-files, and a folder of images.

Create a Lasso page which contains the following [code][LassoApp_Create] [/code]tag. This tag will build a LassoApp named [code]MySolution.LassoApp [/code]stored at the same location as the root folder defined above. The entry file for the LassoApp will be [code]default.lasso [/code]immediately inside the [code]MySolution [/code]folder.

The [code][LassoApp_Create][/code] tag would be as follows.

[pre][LassoApp_Create: -Root='/MySolution/',
-Entry='default.lasso',
-Result=''/MySolution.LassoApp'] [/pre]

If any errors are reported, correct them within the Lasso pages of the solution and then reload the Lasso page to build the LassoApp again.

The completed LassoApp should have been created within the Web serving root and can be loaded through the following URL.

[pre]http://www.example.com/MySolution.LassoApp [/pre]

Tips and Techniques

[p]This section presents a number of tips and techniques which can make creating professional quality LassoApps easier. [/p]

Naming Conventions

[p]LassoApps should be named with the identifier of the company that created the LassoApp followed by the name of the solution. For example, if LassoSoft shipped a phone book LassoApp it could be named [code]LS_PhoneBook.LassoApp[/code]. This ensures that the LassoApp name will not conflict with LassoApps created by other companies. [/p]

[note][b]Warning: [/b]Do not compile LassoApps with the same name as the LassoSoft supplied LassoApps (e.g. [code]Startup.LassoApp [/code]or [code]Admin.LassoApp[/code]). LassoSoft cannot provide any warranty or support for customized versions of these LassoApps or for Lasso Professional 8 installations which make use of customized versions of these LassoApps. [/note]

Run-Time Errors

[p]Errors which occur when a LassoApp is executing are reported the same way they are for any Lasso pages. It is important to thoroughly test a LassoApp to ensure that all errors are caught and properly reported to the site visitor. The[code] [Protect] … [/Protect][/code], [code][Handle] … [/Handle][/code] and[code] [Fail][/code] tags can be used to trap for errors and handle them so that the errors are not reported to the site visitor. [/p]

Auto-Building Databases

[p]If a LassoApp requires a database table to store solution-specific data it can be created automatically by the LassoApp using the [code][Database_Create…][/code] tags. Using this technique ensures that a LassoApp can be shipped as a single file and cuts down on the installation required by the end-user. [/p]

LassoApps can safely create tables in the [code]Site [/code]database within any installation of Lasso Professional 8. This database is the appropriate place to store both preferences and solution-specific data.
Tables created in the [code]Site [/code]database should follow a naming convention which includes the name of the LassoApp in each table name. For example, a LassoApp named [code]MySolution.LassoApp [/code]could create tables named [code]MySolution_Preferences [/code]and [code]MySolution_Data[/code]. Using a clear naming convention ensures that the global administrator knows why individual tables were created and ensures that different LassoApps do not create tables with the same name.
If necessary, the LassoApp may need to ask for additional permissions in order to create new tables or to gain access to the tables that have been created. See the section on Lasso Security below for more information.
Always check to make sure that a table does not exist before creating a new table. A LassoApp should never overwrite data in the [code]Site [/code]table without explicitly ensuring that the administrator wants to do so.

Lasso Security

[p]LassoApps are executed with the permissions of the current site visitor the same as any Lasso pages. If a LassoApp needs to have access to databases, tables, or tags that can be secured in Lasso Site Administration then it should check that the appropriate permissions are present before executing. [/p]

Databases and Tables

[p]If a LassoApp requires access to certain databases or tables it should first check to be sure they are available to the current user before executing. The following code will check to be sure the [code]People [/code]table of the [code]Contacts [/code]database is available. [/p]

[pre][Inline: -Database='People', -Table='Contacts', -Show]
[If: (Error_CurretError) != (Error_NoError) || (Field_Name: -Count) == 0]
<br>Error: The People table of the Contacts database is required
in order for this LassoApp to execute. Please enable it within Lasso
Administration before proceeding.
[/If]
[/Inline] [/pre]

Groups and Users

[p]The [code][Admin_…][/code] tags can be used to create new users and assign them to a group. These tags are essential if Lasso Security is going to be used to handle multiple user accounts for a LassoApp. Since there is no tag to create a group and assign it permissions, the documentation for a LassoApp solution will need to walk a Lasso global administrator through creating a group with the proper name, assigning permissions, and creating a group administrator. [/p]

Lasso Startup

[p]If code needs to be executed when Lasso Service starts up, then a LassoApp can be placed within the [code]LassoStartup [/code]folder within the Lasso Professional 8 application folder. Usually, a solution that requires startup code would consist of two LassoApps, one that installs in [code]LassoStartup [/code]and a second that defines the user interface for the solution.[/p]