HTML best practices

In this section, we'll provide some tips and best practices for your HTML documents.

Start with a template

This may seem like common knowledge, but creating and using a template for your HTML document can save you time and improve the development process. There's no sense re-inventing the wheel, so once you set up a structure for a basic web page, save it and reuse it. Your HTML template should include the key elements and tags that you typically find in a web page.

Here's an example of a typical HTML template for a BlackBerry WebWorks application:

<!DOCTYPE html>
<html lang="en">
        <meta charset="utf-8">
        <link href="favicon.ico" rel="icon" type="image/x-icon">
        <link rel="stylesheet" href="css/app.css">
        <style type="text/css">
        <p>The quick brown fox jumps over the lazy dog.</p>

In this template, there are a few things to note:

  • The application is set to full screen by using the following values in the viewport meta tag: initial-scale=1.0, minimum-scale=1.0, maximum-scale=1.0
  • Zooming functionality is turned off by setting user-scalable=no
  • For performance improvements, the JavaScript is placed near the bottom of the HTML document. See Put scripts at the bottom for more details.

Specify a document type

The DOCTYPE declaration tells the browser what version of HTML the page is written in, which informs the browser how to render the content. When you validate your web page, the HTML validator uses the DOCTYPE to determine which HTML version to validate against; the validator checks your code against the applicable standards and reports which portions are compliant and non-compliant.

Why should I specify it?

If you don't include a document type declaration, your content will not be rendered consistently across browsers. Each browser might render your content differently. By including a DOCTYPE, browsers are required to process your content according to the standards for that document type.

Which DOCTYPE should I use?

HTML5 is the current standard, which you should be using in your BlackBerry applications. HTML5 includes great new features and functionality that you can leverage in your application.

<!DOCTYPE html>

For BlackBerry devices running BlackBerry 6 and earlier, the browser doesn't support all of the HTML5 features, so you might choose to use the HTML 4.01 Strict or XHTML 1.0 Strict document types instead of the HTML5 document type.

Design your content for offline use

With mobile devices, there's an increasing demand for users to access their applications at any time, even when they are offline. For your web application, you can take advantage of the W3C HTML5 application cache feature to:
  • Make your web application available offline
  • Increase the speed of your application by caching resources locally
  • Reduce load times and data usage by only downloading updated or changed resources

The application cache (also known as AppCache), allows you to specify the files to cache and make available even when the user is offline.

Create a manifest

To use the AppCache feature, your web application must provide a "manifest" to the browser that lists all the resources that it needs so that the application can function when offline. After the first time a web page is loaded, the resources specified in the manifest file are obtained from the application cache, not from the web server. The manifest is simply a text file that typically has a file extension of .appcache.

# 2012-03-08:v1

# Explicitly cached resources

# offline.html displays if the user is offline
/ /offline.html

# All other resources require an online connection

# Additional cached resources

Your manifest file must be served with the mime-type text/cache-manifest. You may need to add a custom file type to your web server or configuration. For example, to serve this mime-type in Apache, add this line to your configuration file (httpd.conf):

AddType text/cache-manifest .appcache

To access the manifest file, you must declare it in your HTML document by adding the manifest attribute to the <html> tag. The manifest attribute points to the manifest file. If your web application has more than one page, make sure that each page includes the manifest attribute, otherwise those pages won't be part of AppCache, and they won't work offline.

<html manifest="html5.appcache">

Updating the appcache

Once your application is cached, it remains cached until one of the following actions occurs:
  • The user clears their cache.
  • The manifest file is modified. Note: Updating the resources on your server will not trigger a cache update. You must change the manifest file itself.
  • The application cache is programmatically updated.

Related resources

To learn more about appcache, visit the following resources:

Use the correct viewport syntax

The viewport is the rectangular area that the user sees on their mobile device. You can override the default viewport by using the viewport <meta> tag in the <head> section of your HTML document.

Keep in mind that the syntax for the viewport meta tag is not the same as the syntax for the @viewport rule in CSS. This means that you must use commas as delimiters between viewport values, and not semicolons. If you use semicolon delimiters, the viewport values can be interpreted incorrectly.

Here's an example showing the correct syntax for the viewport meta tag:


Create a site icon

Every web browser looks for a favicon.ico (short for favorites icon) file and displays the file as the site's icon.  You often see the small icon displayed in the address bar, tabs, user's bookmarks or favorites.

Screen showing the address bar of a web browser. There is an arrow pointing to the site's icon adjacent to the URL.

When the browser looks for your web page, it will also make a request for your favicon.ico file. If the favicon.ico file can't be found, you'll see 404 errors in your web server's log.  To avoid this, you should always specify a favicon.ico file in your web pages.

[Mon Aug 20 15:17:49 2012] [error] [client] File does not exist: C:/www/favicon.ico

In the <head> section of your HTML5 documents, add a link tag pointing to your favicon.ico file.


Use external files

Using external files for your JavaScript and CSS has many benefits, but one of the major benefits is making your web pages load faster.  Why do they load faster? Here are a couple reasons:

  • External files are cached by the browser. This reduces the number of HTTP requests; however, inline JavaScript and CSS is downloaded each time the HTML document is requested.
  • Reduces the size of the HTML document. Since the JavaScript and CSS files are external, there is less inline code in the original HTML document to parse and render.

For BlackBerry WebWorks applications, the resources are typically bundled with the application. The following information applies mainly to web (browser-based) applications.

The benefits for external files aren't experienced in every situation. Before you start externalizing your application's resources, consider only making the resource external if:

  • The resource is used in more than one HTML document
  • The resource changes infrequently

Here are some tips when using external files in your web application:

  • Source your files off a well-known host, which can reduce the number of DNS lookups.
  • Spread the resources out to another domain. The browser has a limited number of connections that it will open to a particular domain; if you spread the files out to another domain, it increases the browser’s freedom to parallelize requests.
  • Use CDN (Content Delivery Network) hosted files for common JavaScript libraries (for example, jQuery). This can improve your web application's performance by decreasing latency and improving what's cached. For example, if a user has visited another site that uses CDN hosted files, those files will already be cached on the device. When the user visits your site for the first time, the library will already be available. Here's a code example that uses the Google's CDN-hosted jQuery:
    <script src="">
  • Analyze the performance of your web application by using the Web Inspector. For more information about the Web Inspector, see Debugging using Web Inspector.

Put your stylesheets at the top

Another way to improve the loading speed of your page is to place your stylesheets at the top of your HTML document. When you have stylesheets in the <head> section of your document, the page renders progressively so it appears to load faster and provides visual feedback to the user as they wait. If your stylesheets are near the bottom of the document, the browser blocks progressive rendering to avoid having to redraw elements of the page if their styles change, so the user ends up with a blank white page. Having stylesheets at the top also increases parallelization because, unlike scripts, stylesheets do not require synchronous processing.

You can add your stylesheets to your HTML document by using the <link> tag.
<!DOCTYPE html>
        <link rel="stylesheet" href="styles1.css">

Do not import stylesheets

When adding external stylesheets to your HTML document, do not use the @import rule. You should use the <link> tag instead.

If you use the @import rule to import style sheets, in some browsers, it behaves as though your stylesheet is at the bottom of the HTML document. This is not the behavior you want because because it prevents the web page from loading progressively.

image Not recommended: Using @import

@import url("styles2.css");

image Recommended: Using a LINK tag


In addition, the @import rule can be nested inside CSS files, preventing the browser from loading your stylesheets in parallel. For example, if styles1.css contained the following:

@import url(styles2.css)

The browser must first retrieve styles1.css and then retrieve styles2.css.

Put scripts at the bottom

Although the W3C spec allows you to put your SCRIPT element in either the head or the body of your HTML document, there are several reasons why adding scripts to the body is preferred. Where you place your scripts can affect the progressive rendering of your HTML page. Because the browser stops and processes JavaScript code as it encounters it, progressive rendering is blocked for all content below the script. If your script is lower in the HTML document, more content is rendered progressively.

Putting your script at the bottom also improves parallel downloading components in parallel. While a script is downloading, parallel downloading is disabled. If the script is at the top, the browser must wait for the script to download before downloading any other components.

Unless you're using the deprecated document.write to generate the body, your scripts can typically be moved to the bottom of the HTML document.

Another advantage to putting the script in the BODY (before the closing body tag) is that you don't need to check to see if the DOM is loaded, because everything in the DOM has already loaded.

image Recommended: Placing the script near the bottom of the BODY

<html lang="en">

image Not recommended: Placing the script in the HEAD

<html lang="en">
    <body onload="init();">

Some third-party frameworks require that you include the scripts at the very top of the HTML document. Refer to the third-party's documentation for more information.

Defer script loading

An alternative to moving your JavaScript files to the bottom of your HTML document is to use deferred scripts.  The DEFER attribute tells the browser to execute the script after the page has loaded. 

<script src="js/app.js" defer></script>

Unfortunately, the DEFER attribute behaves differently between browsers.  To avoid cross-browser issues, you can use the "lazy loading" approach.  That is, avoid loading scripts until they are needed.

Here's an example of an unobtrusive lazy load pattern:

function lazyload() {
    var elem = document.createElement("script");
    elem.type = "text/javascript";
    elem.async = true;
    elem.src = "app.js"; // contains more than 25 uncalled functions

if (window.addEventListener) {
    window.addEventListener("load", lazyload, false);
} else if (window.attachEvent) {
    window.attachEvent("onload", lazyload);
} else {
    window.onload = lazyload;
For more information on lazy loading, see the following resources:

Last modified: 2014-10-09


comments powered by Disqus