Skip Top Navigation
Developers Partners
North America [change region] Products Solutions Purchasing Support

cHTML In Depth

Jennifer Emery, Research In Motion

cHTML (Compact HyperText MarkUp Language) is designed for small portable devices such as the BlackBerry device, phones and other PDAs (Personal Digital Assistants). It is derived from a subset of HTML 2.0, 3.2 and 4.0 specifications. Development using cHTML is becoming more essential in todayís expanding wireless market.

Almost all portable devices will have some form of hardware restrictions. These restrictions can be any or all of the following items: memory, CPU, little or no secondary storage, display size and color, single character font or restricted input methods, to name a few. cHTML takes into account these restrictions when developing sites for portable devices.

The overall design of cHTML is based on four principles:

  1. Based on the current HTML recommendations.
  2. "Lite Specifications." cHTML pages are viewed on a limited memory and lower power CPU devices.
  3. Viewed on small monochrome or color display screens.
  4. Easily operated by end-users. cHTML is designed to provide the end-users with basic operation.

The features listed below are excluded from the cHTML specifications:

  • Images - .jpeg / ImageMaps
  • Tables
  • Multiple character fonts and styles
  • Background color and images
  • Frames
  • Style Sheets

Several benefits of using cHTML are:

  • Allows mobile devices to view web pages.
  • cHTML retains the advantages of HTML and may solve restriction problems that mobile devices may have.
  • HTML authoring tools can reference cHTML specifications.

This article focuses on cHTML development for the BlackBerry device while delving into the cHTML specifications.

Topics within this section include:

  • The Basic Structure
  • <head>Header Section</head>
  • <body>Body Section</body>
  • The Basic Structure

    A cHTML page should begin with the definition of the document type. The DOCTYPE tells the browser which page specification to use and specifies any rules that may apply to the page.

    There is only one DOCTYPE for cHTML which is defined as:

    <!DOCTYPE HTML PUBLIC "-//W3C//DTD Compact
    	HTML 1.0 Draft//EN">

    Immediately following DOCTYPE, the opening:


    ... and closing HTML tag:


    ... should follow. Per the cHTML specification, the version attribute can also be included within the opening <html> tag. This attribute declares the type of page that will be displayed. For cHTML, the version would be:

    <html version="C-HTML 1.0">

    Note: The following code samples must include the cHTML header, and must be wrapped between the HTML tags

    Like basic HTML or xHTML web pages, cHTML pages are divided into two main sections:

    • Header
    • Body

    <head>Header Section</head>

    Contains information about the document such as title, style, and meta information. The tags <base>, <title> and <meta> are supported. These tags must be placed between the opening <head> and closing </head> tags.

    <base />

    Defines a base URL for all links (including images) on the particular page.

    For example:

      <title>cHTML Page</title>
      <base href= />
      <img src="Send.gif" />

    The Send.gif image is located in the subfolder called Images.

    <title>Page Title</title>

    Defines a title for the page that is displayed in the title bar on the browser window.

    <meta />

    Provides meta information about the page. Newer versions of the BlackBerry Browser contain limited support for meta tags, however only one of the three valid http-equiv types (refresh, expires and cache-control) are supported by the cHTML specification:


    This is used to refresh the page at specified intervals, and can be used to redirect one page to another. For example:

    <meta http-equiv="refresh" content="2;
    url = http://localhost:8080/BlackBerry/index.html" />

    <body>Body Section</body>

    Contains page contents, such as text and images. The body tag contains numerous attributes that can customize how the page is displayed. Note that the cHTML specification does not include support for these attributes.

    The cHTML skeleton structure so far:

    <!DOCTYPE HTML PUBLIC "-//W3C//DTD Compact
      HTML 1.0 Draft//EN">
        <title>CHTML Page</title>
        <meta /><!-- Meta tags would appear here -->
        CHTML Page

    BlackBerry Browser Output:

    Note: Any text enclosed with the <!-- - -> tag is defined as a comment. Comments are used to describe the source code and are ignored by the browser.

    Text Formatting - Supported Style Tags

    The BlackBerry Browser has the ability to recognize a variety of style tags, such as <b>bold text</b>, and <u>Underline Text</u>. The cHTML specification limits which style tags are supported.

    <blockquote>Blockquote text</blockquote>

    The BlackBerry Browser version 4.0 or later is designed to indent the enclosed text by one full-width space. Earlier versions of the BlackBerry Browser will not render the indentation.

    Code Sample:

    This is the start of the blockquote, which defines the start of a long quotation.

    BlackBerry Browser Output:

    <pre> Preformatted text, fixed-font </pre>

    The <pre> tag may show the enclosed text with the following characteristics:

    • leave white space intact
    • render text with a fixed-pitch font/li>
    • disable automatic word wrap/li>
    • must not disable bidirectional processing./li>

    <center>pre Element</center><br />
    This is preformatted text
      Line # 2
    Line # 3
           Line # 4

    BlackBerry Browser Output:

    Defining a header

    Header tags are used to emphasize text on a page. There are six sets of tags, <h1></h1> through to <h6></h6>. <h1> is the largest header and <h6> is the smallest. An align attribute can be added to align the enclosed text, either left, center or to the right.

    Code Sample:

    <h1>Header # 1</h1>
    <h2 align="right">Header # 2</h2>
    <h3>Header # 3</h3>
    <h4>Header # 4</h4>
    <h5>Header # 5</h5>
    <h6>Header # 6</h6>

    BlackBerry Browser Output:

    Text Layout

    The cHTML language supports tags that align, list and display page contents in a customized way. The following tags illustrate all supported layout tags.

    <br />
    Inserts a single line break

    In previous versions of the BlackBerry Browser (3.7 and earlier), multiple <br /> tags in a row will be ignored. The BlackBerry Browser version 4.0 or later is designed to execute and render multiple <br /> tags correctly.

    An align attribute can be added to a tag to determine where the next line will start. Note that the BlackBerry Browser will ignore the align attribute if included in the tag.

    <center>Center enclosed text</center>


    <center>Center Element</center>

    BlackBerry Browser Output:

    <div>A division or section within the document</div>

    The div tag is a way to add structure to the contents of the page. It includes an align attribute that is used to horizontally align the contents. The possible values for align are left, center or right. Vertical alignment is ignored by the BlackBerry Browser application.

    Code Sample:

    <div align="left">This is div, left aligned</div>
    <br />
    <div align="center">This is div, center aligned</div>
    <div align="right">This is div, right aligned</div>
    <br />

    BlackBerry Browser Output:

    <hr />
    Insert a horizontal rule

    Draws a horizontal line. The <hr /> tag incorporates several formatting attributes as shown in the following table:

    Attribute Description
    align =left/center/right
    Aligns the rule on the page.
    The default value is center.
    size Determines the height of the rule.
    The default value is 1.
    width Determines the width of the rule.
    The default value is 100%.
    noshade When specified, the rule is rendered as a solid color rather than a traditional 2-color "groove".

    Code Sample:

    <center>hr Element</center><br />
    Line # 1
    Line # 2
    <hr size="10" width="50" align="center">
    Line # 3
    <hr size="10" noshade>
    BlackBerry Browser Output:

    BlackBerry Browser Output:

    <p>New paragraph of text</p>

    The paragraph tag must be properly closed, as some browser applications will ignore empty tags. Paragraphs can be aligned to the left, center or right:

    <p align="left">
    <p align="center">
    <p align="right">

    The BlackBerry Browser supports horizontal alignment of text, and ignores vertical alignment. The following code sample shows each alignment value.

    <p align="center">P Element</p>
    <p align="left">Left Align</p>
    <p align="center">Center Align</p>
    <p align="right">Right Align</p>

    BlackBerry Browser Output:

    Note: Older versions of the BlackBerry device may not render the <p> align properly.

    Layout - Lists

    There are numerous methods within the cHTML specifications for providing a list structure. Each type of list will differ slightly from a visual perspective when the page is rendered but are all used to organize page contents.

    The first style is a simple ordered or unordered list. The items in an ordered list appear in a numbered sequence. In an un-ordered list, the items are prefixed with a bullet. In other web languages, such as HTML or xHTML, the type of bullet can be defined. However, the cHTML specification does not permit this.

    The following code samples illustrate these styles:

    Ordered List:

      <li>Item # 1
      <li>Item # 2
      <li>Item # 3

    Unordered List:

      <li>Option # 1
      <li>Option # 2
      <li>Option # 3

    BlackBerry Browser Output:

    The <li> tag defines a list item. Lists can be nested inside each other, creating a multi-tier list. The following code sample illustrates nested lists:

      <li>Item # 1
        <li>SubItem # 1
        <li>SubItem # 2
        <li>SubItem # 3
      <li>Item # 2
      <li>Item # 3
        <li>SubItem # 4
        <li>SubItem # 5

    The second list style is a definition list which consists of two parts:

    1. Term
    2. Description

    Code Sample:

        A device that computes, especially a
        programmable electronic machine that
        performs high-speed mathematical or
        logical operations or that assembles,
        stores, correlates, or otherwise
        processes information.

    BlackBerry Browser Output:

    <dl></dl> The start and end of a definition list.
    <dt></dt> The start and end of the term within a definition list.
    <dd></dd> The start and end of the description of a term in a definition list.

    A third list type is a directory list. A directory list is created using the <dir></dir> tag, where each item in the list is prefixed with the <li> element.

    For example:

      <li>Item # 1
      <li>Item # 2
      <li>Item # 3

    BlackBerry Browser Output:

    The last type of list is designed for single column menu lists. A menu list is defined by using the <menu></menu> tags along with using the <li> tag to list each individual menu item.

    For example:

      <li>Menu Option # 1
      <li>Menu Option # 2
      <li>Menu Option # 3
      <li>Menu Option # 4
      <li>Menu Option # 5

    BlackBerry Browser Output:

    Special Characters

    cHTML supports a variety of special characters. These characters can range from symbols to spaces or dashes. For example, below is a very small subset of these characters:

    Code Sample:

    Copyright - &copy; or &#169; <br />
    Quotation Mark - " or &quot; or &#34; <br />
    Ampersand - & or &amp; or &#38; <br />
    Registered Trademark - &reg; or &#174; <br />
    Less-Than - < or &lt; or &#60; <br />
    Greater-Than - > or  &gt; or &#62; <br />

    BlackBerry Browser Output:

    For a complete list of all special characters, please see this Developerís Knowledge Base article.


    Navigation is an important element in any web page and is created through links. Links are defined by the use the anchor (<a> and </a>) tag, where the enclosed text appears underlined to represent a hyperlink. The attributes "name" and "href" are the only attributes supported in cHTML.

    The BlackBerry Browser supports the following link schemes:

    • cti:
    • dc:
    • http:
    • mailto:
    • tel:
    • wtai:

    The syntax for a mailto link is as follows:

    <a href="">
    Email for Application Development Support</a>


    The BlackBerry Browser can recognize wbmp (monochrome wireless bitmap), gif, tif, jpeg, and png image formats. When using a BlackBerry Mobile Data Service, this service will convert gif images to png format as png images have a higher compression ratio and support alpha channels. Jpeg images are used on color screen BlackBerry devices only.

    The following tables lists all attributes associated with the <img> tag:

    Attribute Description
    src The source (link/URL) of the image.
    align Aligns images horizontally or vertically on the page. Acceptable values are left, right, top, middle and bottom. The BlackBerry Browser aligns images to the left by default and ignores center alignment. In addition the BlackBerry Browser ignores vertical alignment.
    alt Short image description. The enclosed text will display if the image is unavailable or if the user has disabled display of images on the BlackBerry Browser.
    Width Specifies the image width.
    Ignored by the BlackBerry Browser.
    Height Specifies the image height.
    Ignored by the BlackBerry Browser.
    Hspace Specifies white space to the left and right sides of the image.
    Ignored by the BlackBerry Browser.
    Vspace Specifies white space to the top and bottom of the image.
    Ignored by the BlackBerry Browser.
    Border Defines a border.
    Ignored by the BlackBerry Browser.

    The cHTML specification does not include support for image maps (i.e. usemap/area tags).


    Adding a form to any web page enhances functionality and user interaction. Data from the form fields is collected when the "Submit" button is selected. The name and associated values are gathered and submitted to the specified location.

    cHTML provides support for basic forms, which is also supported by the BlackBerry Browser.

    The syntax supported by the BlackBerry Browser is:

    <form action="" method="">


    • A request form attribute to set the submission URL.


    • The HTTP method used to submit data to the URL specified in the action attribute. The method is set to either POST or GET, and is set to GET by default. GET submits the form contents within the URL, where POST submits contents in the body of the request.

    The cHTML specification also includes the "enctype" attribute for the opening <form> tag, which defines the mime type used to encode the contents of the form. Note that the BlackBerry Browser will ignore this attribute.

    The <input> tag is used to define a field on a form:

    <input type="" name="" value="">

    There are several different types of input fields, however the default (if not specified) is "text". The following describes each type of input in detail:

    type: checkbox

    Defines a checkbox control.


    <input type="checkbox" name="CheckBox" value="1" checked />Check Box # 1<br />
    <input type="checkbox" name="CheckBox" value="2" />Check Box # 2<br />
    <input type="checkbox" name="CheckBox" value="3" />Check Box # 3<br />
    <input type="checkbox" name="CheckBox" value="4" checked />Check Box # 4<br />

    BlackBerry Browser Output:

    Any option that includes the checked attribute will automatically be displayed as selected when the page loads.

    Attribute: name

    • The check box group name. Required attribute.

    Attribute: value

    • Specifies the value of the check box. This value is sent to the server when the form is submitted. Required attribute.

    type: hidden

    Defines a hidden element on a form. This item will be included when the form is processed but is not displayed in the browser window.


    <input type="hidden" name="HiddenField" value="HiddenValue" />

    type: password

    Creates a password input field. The characters entered are masked with an asterisk (*).


    <input type="password" name="UserPassword" size="10" maxlength="5" />

    The "size" attribute is used to set the size of the field that is displayed.

    The "maxlength" attribute is used to limit the number of characters that can be entered.

    type: radio

    Defines a radio control where only one option can be selected at a time.


    <input type="radio" name="RadioControl" value="1" />Radio # 1<br />
    <input type="radio" name="RadioControl" value="2" />Radio # 2<br />
    <input type="radio" name="RadioControl" value="3" checked />Radio # 3<br />

    BlackBerry Browser Output:

    type: reset

    Displays a Reset button. When selected, all form fields are restored to their original values.


    <input name="ResetButton" type="reset" />

    type: submit

    Defines a Submit button. When selected, the contents of the form are submitted to the provided URL with the action attribute of the form element.


    <input name="SubmitContents" type="submit" />

    type: text

    Defines a text input field


    Enter Information:<br />
    <input type="text" name="TextField" size="10" maxlength="20" />

    BlackBerry Browser Output:

    Note: The input type "img" and "file" are not supported by the cHTML specification nor the BlackBerry Brower application.

    Another input method that can be added to the form is a selection list (or drop-down list). This is created through a <select> tag, which can be set to single-selection or multiple-selection. The select is set to single-selection by default, where the first item is automatically selected (unless specified differently). To create a multiple-selection drop down list, you must specify the attribute "multiple" in the opening select tag. A select list contains one or more <option> tags to define items in the drop-down list. Each <option> tag appears between the opening and closing select tags.

    Example: Single Select List

    <select name="SingleSelectList">
      <option  selected>Option # 1</option>
      <option>Option # 2</option>
      <option>Option # 3</option>
      <option>Option # 4</option>

    When an <option> tag contains the "selected" attribute, it displays the item as selected when the page loads. In addition, this item will also be displayed first in the list.

    BlackBerry Browser Output:

    BlackBerry Browser Output:

    Example: Multiple Select List

    <select name="MultipleSelectList"
      multiple size="1">
      <option value="Option1" >Option # 1</option>
      <option value="Option2">Option # 2</option>
      <option value="Option3" selected>
        Option # 3</option>
      <option value="Option4">Option # 4</option>

    BlackBerry Browser Output:

    BlackBerry Browser Output:

    An additional attribute called "size" can be added into the opening <select> tag. This attribute determines the number of visible items in the drop down list. If this attribute is not specified, all items are shown in the drop down list when selected by default. For example, if the size attribute is specified and set to "2", two items will be displayed when the drop down list is selected.

    The last type of field that can be added on a form is "textarea." A textarea field is a multi-line text area, defined by the <textarea> tag. You can specify the number rows and columns visible in the text area within this tag.

    The following example defines a textarea that spans 10 rows and 15 columns:

    <label>Text Area:</label><br />
    <textarea name="TextArea1" rows="10" cols="15"></textarea>

    BlackBerry Browser Output:

    For additional web development information for the BlackBerry Browser, please visit the Developerís section of or visit the World Wide Web Consortium.

    Please email your comments, suggestions and editorial submissions to

    Top |  Table of Contents |  Journal in PDF Format |  Legal Disclaimer
 Home | Products | Solutions | Purchasing | Support | Developers | Worldwide | News | About Us | Contact Us | Site Map
 Legal | Copyright © 2008 Research In Motion Limited, unless otherwise noted.