URL Helper

The URL Helper file contains handlers that assist in working with URLs.

Loading this Helper

This helper is loaded using the following code:

rigLoadHelper "url"

The following handlers are available:

rigASiteURL()

Returns your site URL, as specified in your config file. The index.lc file (or whatever you have set as your site index_page in your config file) will be added to the URL, as will any URI segments you pass to the function.

You are encouraged to use this function any time you need to generate a local URL so that your pages become more portable in the event your URL changes.

Segments can be optionally passed to the function as a string or an array. Here is a string example:

put rigASiteURL("news/local/123") into tURL

The above example would return something like: http://example.com/index.lc/news/local/123

Here is an example of segments passed as an array:

put "news,local,123" into tSegments
split tSegments using comma

put rigASiteURL(tSegments) into tURL

rigBaseURL()

Returns your site base URL, as specified in your config file. Example:

put rigBaseURL() into tBaseURL

rigCurrentURL()

Returns the full URL (including segments) of the page being currently viewed.

rigCurrentURIstring()

Returns the URI segments of any page that contains this function. For example, if your URL was this:

http://some-site.com/blog/comments/123

The function would return:

/blog/comments/123

rigIndexPage()

Returns your site "index" page, as specified in your config file. Example:

put rigIndexPage() into tIndex

rigAnchor()

Creates a standard HTML anchor link based on your local site URL:

<a href="http://example.com">Click Here</a>

The tag has three optional parameters:

rigAnchor(uri segments, text, attributes)

Parameters

Here are some examples:

put rigAnchor("news/local/123", "My News") into tLink

Would produce: <a href="http://example.com/index.lc/news/local/123">My News</a>

put "The best news!" into tArray["title"]
put rigAnchor("news/local/123", "My News", tArray) into tLink

Would produce: <a href="http://example.com/index.lc/news/local/123" title="The best news!">My News</a>

rigAnchorPopUp()

Nearly identical to the rigAnchor() function except that it opens the URL in a new window. You can specify JavaScript window attributes in the third parameter to control how the window is opened. If the third parameter is not set it will simply open a new window with your own browser settings. Here is an example with attributes:

put "800" into tAtts["width"]
put "600" into tAtts["height"]
put "yes" into tAtts["scrollbars"]
put "yes" into tAtts["resizable"]
put "0" into tAtts["screenx"]
put "0" into tAtts["screeny"]


put rigAnchorPopUp("news/local/123", "Click Me!", tAtts) into tLink

Note: The above attributes are the function defaults so you only need to set the ones that are different from what you need. If you want the function to use all of its defaults leave the third parameter blank:

put rigAnchorPopUp("news/local/123", "Click Me!") into tLink

Note: Windows opened using JavaScript or target="_blank" have access, even though limited, to the parent window. Although the way, how anchors are generated by rigAnchorPopUp(), addresses security issues of _blank targets, the solution provided does not work for Safari. So, think carefully before using rigAnchorPopUp() for anything that requires high security, especially if you are dealing with user-generated content.

rigMailToLink()

Creates a standard HTML email link. Usage example:

put rigMailToLink("me@my-site.com", "Click Here to Contact Me") into tMailLink

As with the rigAnchor() tab above, you can set attributes using the third parameter.

rigSafeMailToLink()

Identical to the above function except it writes an obfuscated version of the mailTo tag using ordinal numbers written with JavaScript to help prevent the email address from being harvested by spam bots. This function has an optional fourth parameter that is a Content Security Policy nonce (number used once) that you can provide using the rigNonce() function, which is added to the script tag. In case the Content Security Policy library is loaded a nonce is added automatically during runtime.

rigAutoLink()

Automatically turns URLs and email addresses contained in a string into links. Example:

put rigAutoLink(tString) into tString

The second parameter determines whether URLs and emails are converted or just one or the other. Default behavior is both if the parameter is not specified. Email links are encoded as rigSafeMailToLink() as shown above.

Converts only URLs:

put rigAutoLink(tString, "url") into tLink

Converts only Email addresses:

put rigAutoLink(tString, "email") into tLink

The third parameter determines whether links are shown in a new window. The value can be TRUE or FALSE (boolean):

put rigAutoLink(tString, "both", TRUE) into tLink

rigUrlTitle()

Takes a string as input and creates a human-friendly URL string. This is useful if, for example, you have a blog in which you'd like to use the title of your entries in the URL. Example:

put "What's wrong with CSS?" into tTitle

put rigUrlTitle(tTitle) into tURLtitle

-- Produces:  Whats-wrong-with-CSS

The second parameter determines the word delimiter. By default dashes are used. Options are: dash, underscore, - or _:

put "What's wrong with CSS?" into tTitle

put rigUrlTitle(tTitle, "underscore") into tURLtitle

-- Produces:  Whats_wrong_with_CSS

The third parameter determines whether or not lowercase characters are forced. By default they are not. Options are boolean TRUE/FALSE:

put "What's wrong with CSS?" into tTitle

put rigUrlTitle(tTitle, "_", TRUE) into tURLtitle

-- Produces:  whats_wrong_with_css

rigUrlPrep()

This function will add http:// or https:// respectively in the event it is missing from a URL. Pass the URL string to the function like this:

put "example.com" into tURL
put rigUrlPrep(tURL) into tURL

-- result: http://www.example.com

The second optional parameter is used to add "https://" like in the following example:

put "example.com" into tURL
put rigUrlPrep(tURL, true) into tURL

-- result: https://www.example.com

rigURLstripSpace()

Use this function to remove or replace whitespace in URLs. Example:

put " http:// www.mydomain.com/my site/foo/bar/the item " into tURL
put rigURLstripSpace(tURL, "%20") into tCleanURL

-- result: http://www.mydomain.com/my%20site/foo/bar/the%20item

The second parameter is optional and is used as a replacement for whitespace. If it is not provided all whitespace is stripped. Whitespace in domain names is always stripped.

rigRedirect

Does a "header redirect" to the local URI specified. Just like other handlers in this helper, this one is designed to redirect to a local URL within your site. You will not specify the full site URL, but rather simply the URI segments to the controller you want to direct to. The handler will build the URL based on your config file values. If you wish you can redirect to external URLs too if you use full URLs like "http://external-example.com/" for the first parameter.

The optional second parameter allows you to choose between the "location" method (default) or the "refresh" method. Location is faster, but on Windows servers it can sometimes be a problem. The optional third parameter allows you to send a specific HTTP Response Code - this could be used for example to create 301 redirects for search engine purposes. The default Response Code is 302. The third parameter is only available with 'location' redirects, and not 'refresh'. Examples:

if loggedIn is FALSE then
  rigRedirect "/login/form/", "refresh"
end if

-- with 301 redirect
rigRedirect "/login/form/", "location", 301

Note: In order for this handler to work it must be used before anything is outputted to the browser since it utilizes server headers.

Note: For very fine grained control over headers, you should use the Output Library's rigSetHeader handler.