Summary
This article applies to the following:
- BlackBerry® Device Software version 3.8 and later
- BlackBerry® Browser
- Web content development
- HTML forms
Details
You can use offline queues for HTML form submission to create HTML forms that are queued by the BlackBerry Browser when they are submitted. This feature is designed to allow BlackBerry smartphone users to submit form data even when they are outside a wireless coverage area. The form data is stored in a queue, and is submitted automatically to the form target when the BlackBerry smartphone returns to a wireless coverage area.
Offline queues were introduced as a feature of the BlackBerry Browser in BlackBerry Device Software 3.8.
After form data is submitted to an offline queue, a new menu item named Offline Queues appears in the BlackBerry Browser. BlackBerry smartphone users can select this menu item to view responses for form requests that are submitted successfully and any requests that are still pending.
To define an offline queue for an HTML form, you must declare several HTTP headers that are specific to BlackBerry smartphones. The BlackBerry Browser processes these headers and uses them to specify the descriptors and default behavior of the offline form submission.
| Parameter | Required? | Description |
| x-rim-queue-id |
Yes |
Specifies the Offline Form Queue to which any GET or POST requests from form submissions on this page should go. The value may be any text string. |
| x-rim-next-target |
No |
Specifies the next page to load after sending any GET or POST requests resulting from this page to the Offline Form Queue. The value may be any valid URL. |
| x-rim-request-title |
No |
Specifies the label used to identify this request in the Queue view page. The value may be any text string. By default, the request is identified using the title of the page. |
| x-rim-request-id |
No |
Specifies whether the browser will generate a unique ID and add it as an HTTP header for every offline request resulting from this page. The value may be a Boolean True or False. By default, this value is True. |
| x-rim-request-date |
No |
Specifies whether the browser will generate a time stamp and add it as an HTTP header for every offline request resulting from this page. The value may be a Boolean True or False. By default, this value is True. |
The implementation for creating an HTML form that is configured to use an offline submission queue involves using one of the following two methods:
- Adding hidden input fields to the form, specifying the name and values of BlackBerry specific HTTP headers, or.
- Creating an HTTP property file (.htaccess), containing the offline queuing parameters for one or many forms.
The following file samples can be downloaded here.
A Instructions: Adding hidden input fields to an HTML form
- Create the following HTML form in a file named
offline_form.html. This form specifies two HTTP headers as hidden input fields which are used to define the Offline queue to be used upon form submission. Data submitted will be first stored in an offline submission queue named 'MyOfflineQueue'. When the device is in coverage, the form data will automatically be posted to a page named form_results.asp and the response will be stored in the 'MyOfflineQueue' queue with a descriptor of 'My Form Submission'.
<html>
<head>
<title>Offline for queue demo 1</title>
</head>
<body>
<form id="frmQueuDemo" method="post” action="form_results.asp">
<input type="hidden" name="x-rim-queue-id" value="MyOfflineQueue" />
<input type="hidden" name="x-rim-request-title" value="My Form Submission" />
<input type="text" id="txtValue" value="This value will be submitted." />
<input type="submit" id="bntSubmit" value="Submit form" />
</form>
</body>
</html>
- Create a file named form_results.asp in the same folder as offline_form.html.
<html>
<head>
<title>Offline for queue demo: Results page 1</title>
</head>
<body>
<%
Response.write(“Form value submitted:” & request.form(“txt.Value”)
%>
</body>
</html>
- Deploy these files to a location that can be accessed on your BlackBerry Browser application.
B. Instructions: Creating an .htaccess file
- Create the following HTML form in a file named
form_htaccess.html:
<html>
<head>
<title>Offline form queue demo 2</title>
</head>
<body>
<form id="frmQueuDemo" method="post" action="form_results.asp">
<input type="text" id="txtValue" value="This value will be submitted." />
<input type="submit" id="bntSubmit" value="Submit form" />
</form>
</body>
</html>
- Create a file named
form_results.asp in the same location as form_htaccess.html.
<html>
<head>
<title>Offline form queue demo: Results page 2</title>
</head>
<body>
<%
Response.write(“Form value submitted:” & response.form(“txtValue”)
%>
</body>
</html>
- Create the following file named
.htaccess in the same directory as form_htaccess.html.
<Files form_htaccess.html>
Header set x-rim-queue-id MyOfflineQueue
Header set x-rim-request-title "My htaccess form submission"
</Files>
- Deploy these files to a location that can be accessed on your BlackBerry Browser application.
Simulate an offline form submission:
- Using the BlackBerry Browser, open the HTML page containing your form.
- Before submitting this form, disable the wireless connection on your BlackBerry Smartphone
- Select "Switch Application" from the browser's menu.
- Open the "Manage Connection" icon on the home screen.
- Unselect the "Mobile Network" checkbox and save your changes.
- Return to the BlackBerry Browser and submit the form. You will receive a message indicating the page could not be submitted because the radio is turned off. Click OK to continue.
- Open the Browser Menu to see a new menu item added named "Offline Queues"
- Open the "Offline Queues" menu item and verify you see a queue named according to the
x-rim-queue-id specified by your form.
- Select the queue to open it and verify you see a pending HTTP request named according to the
x-rim-request-title specified by your form. The clock icon next to this HTTP Request item indicates it is pending submission.
- Enable wireless connection on your BlackBerry Smartphone
- Select "Switch Application" from the browser's menu
- Open the "Manage Connection" icon on the home screen
- Select the "Mobile Network" checkbox and save your changes.
- Return to the browser and see that the icon next to your HTTP request has changed to a globe, indicating the form data has been automatically submitted by the browser, and a response has been received.
- Open the HTTP request item to view the response data received from form_response.asp.
