Chapter 15
URL Rewrite

[p]This chapter documents the [code]URL Rewrite[/code] section in Site Administration, which allows the site administrator to set up rewrite rules that can perform automatic includes or redirects. This chapter describes the following: [/p]

• Introduction describes how Lasso’s URL rewrite functionality works and compares it to Web server-based URL rewrite.
• Rules, Triggers, and Actions describes the triggers which are available to determine if a rule should run and the actions that can be performed by a rule.
• Setting Up Rules describes the interface in Site Administration which can be used to create and edit URL rewrite rules.

Introduction

[p]URLs can reference any resource which can be served by a Web server, but in practice they are most often used to reference specific files. URL rewrite functionality makes it possible to use URLs for their original purpose and to sever the one-to-one correspondence between URLs and files. [/p]

[p]For example, the following two URLs would traditionally reference a pair of files [code]rocket.html[/code] and [code]station.html[/code] which are located in the Web server root. [/p]

[pre]http://www.example.com/rocket.html
http://www.example.com/station.html [/pre]

[p]However, in a database driven Web site each of these pages may depend primarily on content which is stored in a database. The files on disk might just be templates into which dynamic content is placed for the files are served to the site visitor. In this case, it makes sense to create a single [code]template.lasso[/code] file which is used as the template for both files. The particular content which is to be served is passed in a URL parameter. The following two URLs might serve the same content as the URLs above. [/p]

[pre]http://www.example.com/template.lasso?page=rocket
http://www.example.com/template.lasso?page=station [/pre]

[p]URL rewrite can be used to map the original URLs into these dynamic URLs. This allows the site visitor to bookmark the simple URL and for Lasso to serve the page effectively using the URL referencing the template and selecting the particular page using a URL parameter. [/p]

[pre]/rocket.html /template.lasso?page=rocket [/pre]

Web Server Rewrite

[p]Most Web servers have built-in rewrite technology. Apache Web server includes the [code]mod_rewrite[/code] module which allows URLs to be rewritten by rules defined in the Apache configuration file. WebSTAR V includes similar rewrite technology accessible through its administration interface. Although Microsoft IIS does not have rewrite technology built-in, third-party modules are available which provide this capability. [/p]

[p]Deciding whether to use the Web servers built-in rewrite tools or Lasso’s URL rewrite tools depends on several factors. Some of the advantages of each method are described below. [/p]

Web Server Rewrite Advantages

• The primary advantage of Web server based rewrite is that it can work on any URLs, even those which are not automatically processed by Lasso. For example, Web server based rewrite can more easily process rules about image files or extensionless files which are not normally processed by Lasso.
• There may be a performance benefit to using Web server based rewrite since the server can intervene earlier in the file serving process, before the file has even been handed off to Lasso for processing.

Lasso URL Rewrite Advantages

• Lasso’s URL rewrite tools allow Lasso-specific actions which are not possible when using Web server based rewrite including using library or include files, setting Lasso variables, logging values, or triggering Lasso’s built-in error processing.
• Lasso’s URL rewrite technology is Web server independent. It allows the same rewrite rules to be used with a site no matter what Web server is being used to server the site.
• Lasso’s URL rewrite tools use familiar Lasso concepts to designate rules, triggers, and actions. There is an easier learning curve for these tools than with some Web server based rewrite methodologies.

[note][b]Note: [/b]Lasso’s URL rewrite tools are a potential replacement for the “error.lasso’ techniques which were used to trap file not found errors in earlier versions of Lasso. [/note]

Rules, Triggers, and Actions

[p]Lasso’s URL rewrite tools work be designating a series of rules. The rules are executed in order each time a page is processed by Lasso. The rules are processed prior to Lasso reading or parsing the designated Lasso page and can be used even for URLs which do not specify a literal Lasso page. [/p]

[p]Each rule has a set of one or more triggers which determine if the rule is run and a set of one or more actions which are only run if the rule is triggered. Rules can be set up to run only if all triggers’ criteria are met or if any one trigger’s criterion is met. After a rule’s actions are performed, either additional rules can be processed, or Lasso can be told to stop processing rewrite rules for that request. [/p]

[note][b]Note: [/b]The URL rewrite rules are programmed not to modify requests for Lasso’s built-in administration interfaces including [code]SiteAdmin.LassoApp[/code]. [/note]

Triggers

[p]Each trigger works like a comparison expression with a field, an operator, and a value. For example, a trigger to match any [code].lasso[/code] files would be [code][Response_FilePath] Ends With ".lasso"[/code]. The field [code][Response_FilePath][/code] and the operator [code]Ends With[/code] are selected from pop-up menus and the value [code].lasso[/code] is typed into a text input in the Site Administration interface. [/p]

[p]Other trigger examples include: [/p]

• [code][Response_FileExists"] Is False[/code] triggers if the requested file does not exist.
• [code][Client_IP] Equals "192.168.0.*"[/code] triggers if clients are within the specified IP range.
• [code][Cookie: "UserID"] Does Not Equal ""[/code] triggers if the cookie [code]UserID[/code] is not empty.
• [code][Client_Header: "User-Agent"] Contains "Safari"[/code] triggers if the client is using the Safari browser.

[p]The following table lists the triggers which are available for Lasso’s URL rewrite rules. [/p]

Table 1: Trigger Fields

[table][tr][th]Trigger Field[/th][th]Description[/th][th] [/th][/tr]

[tr][td][Client_URL][/td][td]The full URL which was used to trigger the current page load including protocol, server name, directories, Lasso page name, and URL parameters.
http://localhost/folder/file.lasso?name=value [/td][/tr]

[tr][td][Server_Name][/td][td]The name of the server which was referenced by the current request. [/td][/tr]

[tr][td][Server_Port][/td][td]The port which is being used to serve the current request. Either 80 for normal HTTP requests or 443 for HTTPS requests. [/td][/tr]

[tr][td][Response_FilePath][/td][td]The path to the file referenced by the current request including directories and Lasso page name. Note that this field returns the path to the referenced file even if it does not exist. [/td][/tr]

[tr][td][Response_FileExists][/td][td]True or false depending on whether the file referenced by [Response_FilePath] actually exists on the server or not. This field is usually used to redirect to a URL that does exit. [/td][/tr]

[tr][td][Client_IP][/td][td]The IP address of the client. [/td][/tr]

[tr][td][Client_Header][/td][td]References a header sent by the client with the current request. Requires the name of the header to be inspected (e.g. Content-Type, Accept-Encoding, or User-Agent). [/td][/tr]

[tr][td][Cookie][/td][td]References a cookie sent by the client with the current request. Requires the name of the cookie to be inspected. [/td][/tr]

[tr][td][Action_Param][/td][td]References any of the action parameters for the current request. Requires the name of the action parameter to be inspected. Note that the action parameters include both the URL and form parameters. [/td][/tr]

[tr][td][Client_GetParam][/td][td]References any of the URL parameters for the current request. Requires the name of the URL parameter to be inspected. [/td][/tr]

[tr][td][Client_PostParam][/td][td]References any of the form parameters for the current request. Requires the name of the form parameter to be inspected. [/td][/tr]

[tr][td][Error_Code][/td][td]References the current set error code. Note that this cannot be used to detect -9984 file not found errors. [/td][/tr]

[tr][td][Error_Msg][/td][td]References the current set error message. [/td][/tr]

[tr][td][Variable][/td][td]References a variable. Requires the name of a variable. [/td][/tr]

[tr][td][Global][/td][td]References a global variables. Requires the name of a global variable. [/td][/tr]

[tr][td][True][/td][td]Allows a trivial trigger which always executes to be created. [/td][/tr]

[/table]

[p]The following table lists the available operators for use in URL rewrite triggers. These correspond closely to Lasso string comparison symbols and Lasso database search operators. [/p]

Table 2: Trigger Operators

[table][tr][th]Rule[/th][th]Description[/th][th] [/th][/tr]

[tr][td]Is True[/td][td]Matches if the trigger field returns true or is non-empty. [/td][/tr]

[tr][td]Is False[/td][td]Matches if the trigger field returns false or is empty. [/td][/tr]

[tr][td]Equals[/td][td]Matches if the trigger field matches the specified value Case insensitive. [/td][/tr]

[tr][td]Not Equal To[/td][td]Matches if the trigger field does not match the specified value. Case insensitive. [/td][/tr]

[tr][td]Contains[/td][td]Matches if the trigger field contains the specified value. Case insensitive. [/td][/tr]

[tr][td]Does Not Contain[/td][td]Matches if the trigger field does not contain the specified value. Case insensitive. [/td][/tr]

[tr][td]Begins With[/td][td]Matches if the trigger field begins with the specified value. Case insensitive. [/td][/tr]

[tr][td]Ends With[/td][td]Matches if the trigger field ends with the specified value. Case insensitive. [/td][/tr]

[tr][td]Matches Regular Expression[/td][td]The value specifies a regular expression which is run against the trigger field. Matches if the regular expression matches any substring of the trigger field. Note also that the sub-patterns of the regular expression are stored and can be used within an action. [/td][/tr]

[tr][td]Does Not Match Regular Expression[/td][td]The value specifies a regular expression which is run against the trigger field. Matches if the regular expression does not match any substring of the trigger field. [/td][/tr]

[tr][td]Less Than[/td][td]Matches if the trigger field is less than the value. The comparison is either numeric or alphabetic. [/td][/tr]

[tr][td]Less Than or Equal[/td][td]Matches if the trigger field is less than or equal to the value. The comparison is either numeric or alphabetic. [/td][/tr]

[tr][td]Greater Than[/td][td]Matches if the trigger field is greater than the value. The comparison is either numeric or alphabetic. [/td][/tr]

[tr][td]Greater Than or Equal[/td][td]Matches if the trigger field is greater than or equal to the value. The comparison is either numeric or alphabetic. [/td][/tr]

[/table]

[p]Most of the operators are used to compare the trigger field with a value. The [code]Is True[/code] and [code]Is False[/code] operators do not require values. The [code]Matches Regular Expression[/code] and [code]Does Not Match Regular Expression[/code] operators require a valid regular expression in the value. If the regular expressions have sub-patterns then the values of those sub-patterns can be retrieved using the [code][Trigger][/code] token within the action. See below for examples. [/p]

Actions

[p]The actions of a rule are performed if the triggers of the rule match their respective criteria. Actions can be used to redirect the site visitor to another URL, to include a file which is processed before the code in the Lasso page itself is processed, to set variables or global variables, or to serve an entirely different page than that referenced in the URL. Actions can be predefined or can use the values from the triggers as part of their parameters [/p]

[p]Some action examples include: [/p]

• [code]Redirect_URL: http://www.example.com[Response_FilePath][/code] which redirects the client’s Web browser to a URL based on the URL which they were trying to access, but on a different server.
• [code]Redirect_URL: /default.lasso?page=[Trigger: 1][/code] which redirects the client’s Web browser to a specific Lasso page with the value of the first trigger as a parameter.
• [code]Include: /header.lasso[/code] includes a file which is processed before any code in the file referenced by the URL request is processed.
• Rule actions can be chained together. The following five rules would set three variables to sub-patterns of the first trigger, include a file [code]onefile.lasso[/code] and then abort. The trigger in this case might be of the form [code][Response_FilePath] Matches Regular Expression "/(.*?)/(.*?)/(.*?)/.*"[/code] which uses a regular expression with three sub-patterns to parse the incoming URL.

[pre]Variable: 'tab1' = "[Trigger: 1,1]"
Variable: 'tab2' = "[Trigger: 1,2]"
Variable: 'tab3' = "[Trigger: 1,3]"
Include: "/onefile.lasso"
Abort [/pre]

[p]The following table lists the actions which are available for Lasso’s URL rewrite rules. [/p]

Table 3: Actions

[table][tr][th]Rule[/th][th]Description[/th][th] [/th][/tr]

[tr][td][Variable][/td][td]Sets a named variable to a value. [/td][/tr]

[tr][td][Global][/td][td]Sets a named global variable to a value. [/td][/tr]

[tr][td][Redirect_URL][/td][td]Redirects the client's Web browser to a specified URL. [/td][/tr]

[tr][td][Include][/td][td]Includes a specified file which will be processed before any code in the URL specified by the client is processed. Note that if this action is used in concert with an [Abort] then the included file essentially takes the placed of the file specified by the client since that file will never be processed. [/td][/tr]

[tr][td][Library][/td][td]Like an include, but the results of the included file are not returned. [/td][/tr]

[tr][td][Log_Always][/td][td]Logs a message to Lasso's console. [/td][/tr]

[tr][td][Log_Critical][/td][td]Logs a critical error message. [/td][/tr]

[tr][td][Log_Warning][/td][td]Logs a warning message. [/td][/tr]

[tr][td][Log_Detail][/td][td]Logs a detail level message. [/td][/tr]

[tr][td][Log_SQL][/td][td]Logs an action statement. [/td][/tr]

[tr][td][Log_Deprecated][/td][td]Logs a deprecated functionality warning. [/td][/tr]

[tr][td][Fail][/td][td]Fails with a specified error code and error message. The error code can be caught by a later URL rewrite rule or otherwise will trigger Lasso's built-in error processing. [/td][/tr]

[tr][td][Abort][/td][td]Aborts processing of the curent page. No further URL rewrite rules will be processed, but any at-end page handlers will be processed. [/td][/tr]

[/table]

[p]Many of the actions such as [code][Variable][/code], [code][Redirect_URL][/code], and the [code][Log_…][/code] tags require a value. The value is specified in the Site Administration interface. The values can include a number of tokens which are replaced with values from the triggers. These tokens work identically to the Lasso tags which they correspond to. All of the available tokens are listed in the following table. [/p]

Table 4: Action Tokens

[table][tr][th]Rule[/th][th]Description[/th][th] [/th][/tr]

[tr][td][Action_Param: "name"][/td][td]Returns the value of the specified action parameter. [/td][/tr]

[tr][td][Client_GETParam: "name"][/td][td]Returns the value of the specified URL parameter. [/td][/tr]

[tr][td][Client_POSTParam: "name"][/td][td]Returns the value of the specified form parameter. [/td][/tr]

[tr][td][Cookie: "name"][/td][td]Returns the value of the specified cookie. [/td][/tr]

[tr][td][Error_Code][/td][td]Returns the current error code. [/td][/tr]

[tr][td][Error_Msg][/td][td]Returns the current error message. [/td][/tr]

[tr][td][Response_Path][/td][td]Returns the path to the file requested by the client including the directories and the file name. [/td][/tr]

[tr][td][Response_FilePath][/td][td]Returns the path to the file requested by the client including only the directories without the file name. [/td][/tr]

[tr][td][Response_FileName][/td][td]Returns the name of the file requested by the client. [/td][/tr]

[tr][td][Server_Name][/td][td]Returns the host name referenced by the client. [/td][/tr]

[tr][td][Server_Port][/td][td]Returns the port accessed by the client. Either 80 for normal HTTP requests or 443 for HTTPS requests. [/td][/tr]

[tr][td][Trigger: "Number"][/td][td]Returns the value for the specified trigger. This token can be used to get the value of any trigger no matter what operator was used within the trigger. [/td][/tr]

[tr][td][Trigger: "Number", "Part"][/td][td]Returns a specific sub-pattern from a trigger which used a regular expression operator. The regular expression must use parentheses ( … ) to define at least one sub-pattern. The part should be ommitted to return the entire trigger value. [/td][/tr]

[/table]

[note][b]Note: [/b]General LassoScript expressions cannot be used when specifying URL rewrite rules. The tokens in the table above must be written exactly as specified in order to be processed properly. Arbitrary code can be executed using an [code][Include][/code] or [code][Library][/code] action. [/note]

Setting Up Rules

[p]The current rules can be seen in the Setup > URL Rewrite > Rewrite Rules section of Lasso Site Administration. Each rule is listed with its name, status, triggers, and actions. Selecting the name of a rule allows the rule to be edited. New rules can be added by selecting the [code]Add Rule[/code] section (see below). [/p]

Figure 1: URL Rewrite Rules

[p]The controls in the left sidebar allow the following actions. [/p]

• Reload Rules – Reloads the rules in the URL rewrite system. Rules which are added or edited are not made part of the live URL rewrite system until they are reloaded. This allows the administrator to edit a collection of rules as a batch and then make them all live at once.
• Disable Rules – Disables the URL rewrite system. This option can be useful when testing new rules to temporarily disable all of the URL rewrite rules.
• Refresh – Refreshes the display showing any rules which have been added.

Adding a Rule

[p]A new rule can be added by selecting the Setup > URL Rewrite > Add Rule section. The initial screen allows one trigger and one action to be created for the rule. If the rule requires additional triggers or actions then they can be added after the rule has been created. Lasso will not make the new rule live until the URL rewrite system is reloaded. A new rule has the following characteristics: [/p]

• Name – The name of the rule, used strictly for display in the administration interface.
• Status – Allows rules to be activated or deactivated individually.
• Perform Action If – Allows rules to be set to perform their actions if all of their triggers’ conditions are met or if any one trigger’s condition is met. By default all of the triggers’ conditions must be met.
• Trigger/Action – Lists a summary of the triggers and actions for the rule.
• If Triggered – By default all of the rules in the URL rewrite system will be run one by one. If this setting is set to Stop After Actions then the URL rewrite system will stop processing for the current URL after this rule performs its actions. This prevents later rules from further modifying the result of this rule.
• Priority – Rules are executed in order of their priority. Modifying the priority allows rules to be re-ordered.

[p]See below for details about the trigger and action sections. [/p]

Figure 2: Add Rule

Editing a Rule

[p]When a rule is edited the Setup > URL Rewrite > Edit Rule section is shown. This screen has the same basic interface as the Add Rule section described above. The triggers and actions for the rule can be modified by selecting the summary of the trigger or action. The [code]Add Trigger…[/code] and [code]Add Rule…[/code] links allow new triggers or actions to be added. See below for details about editing or adding triggers or actions. [/p]

Figure 3: Edit Rule

Triggers

[p]This section describes the characteristics of triggers. The same basic interface is used when initially adding a rule, editing a trigger that is part of a rule, or adding a new trigger to a rule. A trigger takes the form of a comparison expression. See above for a full list of trigger types. [/p]

[pre][Action_Param: 'myparam'] Contains "myvalue" [/pre]

• Type – The type of trigger. Each type corresponds to a Lasso tag such as [code][Response_FilePath][/code] or [code][Action_Param][/code].
• Name – If the type requires a name value then it can be specified here. For example, [code][Action_Param][/code] requires the name of the action parameter to test.
• Comparator – The comparator to use to check the value against the type. The comparators are equivalent to those which can be used when specifying database queries.
• Value – The value for the comparison. Most comparators require a string value. [code]Is True[/code] or [code]Is False[/code] do not require a value. The [code]Greater Than[/code] and [code]Less Than[/code] comparators are usually used with a numeric value. The [code]Matches Regular Expression[/code] comparator requires a regular expression value
• Priority – Allows the trigger to be re-ordered. Triggers are performed in order and must be referenced by order in the [code][Trigger][/code] token within an action.

Figure 4: Edit Trigger

Actions

[p]This section describes the characteristics of actions. The same basic interface is used when initially adding a rule, editing an action that is part of a rule, or adding a new action to a rule. An action takes the form of a simple Lasso tag. See above for a full list of action types and tokens. [/p]

[pre][Redirect_URL] http://www.example.com[Response_FilePath] [/pre]

• Type – The type of action. Each type corresponds to a Lasso tag such as [code][Redirect_URL][/code] or [code][Log_Critical][/code].
• Name/URL/Path/Message – If the type requires a parameter then it can be specified here. For example, [code][Redirect_URL][/code] requires the URL to redirect to, and [code][Log_Critical][/code] requires the message to log. The parameter value can use any of the token values to substitute in the result of various Lasso tags or the matched value from a trigger.
• Value/Code – If the type requires an additional parameter then it can be specified here. For example, [code][Fail][/code] requires both a message and an error code and [code][Variable][/code] requires a variable name and value. The parameter value can use any of the token values to substitute in the result of various Lasso tags or the matched value from a trigger.
• Priority – Allows the actions to be re-ordered. Actions are performed in order and the order can be important for certain sequences of actions. For example, one action can set a variable using the type [code][Variable][/code] and then a later action can reference that value using the [code][Variable][/code] token.

Figure 5: Edit Action

[note][b]Note [/b]– Only the tokens which are listed can be used within the parameters of an action. The [code][Include][/code] or [code][Library][/code] types can be used to execute arbitrary code if necessary. [/note]