urlAdded by IBM on October 10, 2012 | Version 1 (Original)
|Provides the url to a target, such as a file or application.
Items containing this option must have a type option setting of link, replace, submit, done, or pagedone.
The object identified must be one of the following:
- File – Used with a type option of link or replace. The file identified is downloaded, and either displayed or saved. Examples of such files are images, word processing documents, and XFDL forms.
- Application – Used with a type option of submit or done. The application identified is initiated. A form processing application, such as a cgi or a servlet, is an example of such an application.
- Item – Used with a type option of pagedone. The item identified, on the page identified, receives focus. The item must be on another page.
- Form or Page Globals – Used with a type option setting of pagedone. The focus moves to the first item on the page when the new form or page appears. The form globals reference is global.global. The page globals reference is <page sid>.global for another page
- E-mail Address – Used with a type option of submit, done, link, or replace. With a submit or done type, the form is attached to an e-mail message, and that message is sent to the address in the URL. With a link or replace type, an e-mail message is created and sent, but the form is not attached to the message. Depending on the settings you use, the user may be able to add additional information to the e-mail.
Note: item reference can be an item, form or page global reference.
Table 1. URL parameters
|the URL||string||Identifies the target. Can be one of:
- A URL with the format: scheme://host.domain[:port]/path/file name for files and applications. Scheme is restricted to http or https.
- A URL with a mailto format. See "URLs for email" below for further information.
- #item reference for the next item in the form to receive focus.
Available in action, button, cell, pane
This sample identifies a file to link to or replace:
This sample identifies a form processing application:
This sample identifies a page to display:
This sample creates an e-mail message that is sent automatically because it contains all of the necessary parameters. Note that the URL is enclosed in the CDATA construct because it contains ampersands (&).
This sample creates an e-mail message that appears to the user before sending, allowing the user to change the parameters.
<url><! [CDATA [mailto:firstname.lastname@example.org?&subject=Hello&
URLs for email URLs that provide an e-mail address must follow this general format:
The first parameter follows the question mark (?) symbol, while each additional parameter is added using the ampersand (&) symbol.
For example, a URL using all parameters would look like this:
The following table lists the available parameters and their settings:
Table 2. URLs for e-mail
If you provide the mailto:, cc=, bcc=, subject=, and body= parameters, the e-mail will be sent automatically and the user will not be able to modify the message. This is true even if the parameters are set to nothing. For example, the following URL would mail the message automatically:
bcc=||string||A complete e-mail address, such as email@example.com. To include additional addresses, use the appropriate parameter twice. For example, to add two cc addresses, use the cc= parameter twice as shown: mailto:firstname.lastname@example.orgemail@example.com &firstname.lastname@example.org
Note that the first address, immediately after the mailto: parameter, is the first recipient. Additional recipients are specified using the to= parameter.|
|subject=||string||The subject line of the e-mail. The text must conform to standard URL encoding rules, such as replacing spaces with the plus (+) symbol.|
|body=||string||The body of the e-mail. The text must conform to standard URL encoding rules, such as replacing spaces with the plus (+) symbol.|
|filename=||string||The name you want to give to the file that is attached to the e-mail message. If you do not set this parameter, a default file name will be assigned.|
If you leave out any of those parameters, the user will see the e-mail message before it is sent, and will be able to change the e-mail.
Note: The ampersand is a restricted character in XML. As such, you must either use an entity reference (&) or enclose the mailto URL in a CDATA section when using the ampersand. See below for an example that uses CDATA.
- Default: none
- You can only list a single URL.
- When using a file object, you can use relative or absolute path to define the file location.
Important: For security purposes, link and replace only allow files to be placed in the same directory or subdirectory as the form.
- You can create a URL that includes computed values, as shown:
- You can create a URL that includes user input as part of the URL string. Ensure that you concatenate (+.) the elements of the string. Additionally, you must contain the e-mail parameters (mailto, &subject, and so on) within quotation marks. For example:
<url compute="'mailto:' +. to_field.value +.
'&subject=' +. subject_field.value +. '&body='
- If you have specified an HTML transmitformat in a form, the form sends its data as HTML when it communicates with a server. Information transmitted in HTML is URL-encoded. Therefore, for forms transmitted in HTML, you must replace all non alpha-numeric characters with a character triplet consisting of the % character followed by two hexadecimal digits. These hexadecimal digits are derived from the ASCII code for the original character. The hexadecimal digits are "0123456789ABCDEF". For example:
Table 3. URL-encoded triplet and ASCII code replacements for HTML characters
Applications receiving form data must check the content type of the incoming data to see whether it is url-encoded.
|Character||ASCII Code||URL-encoded triplet|
| <space> ||32||%20|