HTML coding and best practices

This article contains information about coding the following types of information with HTML:

• Inserting unordered lists
• Inserting ordered lists
• Inserting definition lists
• Nesting lists
• Inserting tables
• Adding a screen capture
• Adding a drawn graphic
• Linking to a spot or heading within the same file
• Cross module linking

Inserting unordered lists

Use an unordered list when you have three or more items in a list and they occur in no particular order. To create an unordered list, use the ul tags with the enclosed li tags as shown in the following example:

<ul>
<li>Insert an item in random order</li>
<li>Insert another item in random order</li>
<li>Insert one more item in random order</li>
</ul>

Inserting ordered lists

Use an ordered list when you have three or more items in a list and they occur, or must be performed, in a certain order. Use an ordered list, for example, when you are providing steps for users to follow. Also use an ordered list if there are processing steps that occur in a certain order. To create an ordered list, use the ol tags with the enclosed li tags as shown in the following example:

<ol>
<li>Insert the first item or step in a process</li>
<li>Insert the next item or step in a process</li>
<li>Insert the next item or step in a process</li>
</ol>

Inserting definition lists

Use a definition list when you have three or more items with a description or definition. Examples could be a parameter list in which you describe each parameter in the list. To insert a definition list, use the dl tags with the enclosed dt and dd tags as shown in the following example:

<dl>
<dt>Insert a term to define</dt>
<dd>Insert a definition or description of the term. Begin the first letter of the first word of each definition or description with a capital letter and end each with a period.</dd>
<dt>Insert code term</dt>
<dd>Repeat adding dt/dd pairs as many times as you need them for each entry.</dd>
</dl>

Nesting lists

You can nest ordered, unordered or definition lists within each other. For example, you are presenting steps that have substeps included so you want to nest an ordered list within an ordered list. To accomplish this, use the div class="olSuba" tag to insert an ordered list within an ordered list as shown in the following example:

<ol>
<li>This is the first step in the process.</li>
<li>This is the second step in the process and it has the following substeps:
   <div class="olSuba">
   <ol>
   <li>This is the first sub-step under step two.</li>
   <li>This is the second sub-step under step two.</li>
   <li>This is the third sub-step under step two.</li>
   </ol>
   </div>
</li>
<li>This is the third step in the process.</li>
</ol>

The div class="olSuba" coding, when run with the css sheet, will make the numbering on the sub steps change to lettering so that you get steps 1 and 2 with steps a, b, and c clearly denoted as substeps under step 2.

If you are coding an unordered list and one of the items in it has sub-items, you would likewise code it as shown in the following example:

<ul>
<li>One item in the list, in no particular order</li>
<li>Another item in the list, in no particular order, but this one has the following sub items:
   <ul>
   <li>One sub item</li>
   <li>Another sub item</li>
   <li>One other sub item</li>
   </ul>
</li>
<li>One other item in the main list</li>
</ul>

No division tags are needed for this coding.

You could also mix and match nesting of ordered lists within unordered lists or unordered lists within ordered lists. The following example shows an ordered list nested within an unordered list:

<ul>
<li>One item in the list, in no particular order</li>
<li>Another item in the list, in no particular order, but this one has the following sub items and the order of these items matters:
   <ol>
   <li>The first sub item</li>
   <li>The second sub item</li>
   <li>The third sub item</li>
   </ol>
</li>
<li>One other item in the main list</li>
</ul>

The following example shows an unordered list nested within an ordered list:

<ol>
<li>This is the first step in the process.</li>
<li>This is the second step in the process and it has three items under it, in no particular order.  For example, step two could say, "be sure you have included the following files in your package:"
   <ul>
   <li>This is a file name in random order.</li>
   <li>This is another file name in random order.</li>
   <li>This is yet another file name in random order.</li>
   </ul>
</li>
<li>This is the third step in the process.</li>
</ol>

If you are coding a definition list and you want to nest another definition list within it, use the following example:

<dl>
<dt>Insert a term to define</dt>
<dd>Insert a definition or description of the term. Begin the first letter of the first word of each definition or description with a capital letter and end each with a period.  This term, for example, is also made up of the following parts that you also want to define:
   <dl>
   <dt>Insert a term to define</dt>
   <dd>Insert a definition or description of the term. Begin the first letter of the first word of each definition or description with a capital letter and end each with a period.</dd>
   <dt>Insert another term</dt>
   <dd>Repeat adding dt/dd pairs as many times as you need them for each entry.</dd>
   </dl>
</dd>
<dt>Insert another term</dt>
<dd>Repeat adding dt/dd pairs as many times as you need them for each entry.</dd>
</dl>

You could have a case where you are coding a definition list and you want to include ordered or unordered information within a definition. You could accomplish this as shown in the following example:

<dl>
<dt>Insert a term to define</dt>
<dd>Insert a definition or description of the term. Begin the first letter of the first word of each definition or description with a capital letter and end each with a period. This term is a component that has processing steps. You could then say, "This component processes input in the following order:"
   <ol>
   <li>The first processing step</li>
   <li>The second processing step</li>
   <li>The third processing step</li>
   </ol>
</dd>
<dt>Insert another term</dt>
<dd>Insert another definition or description of the term, but this one has sub components that you do not want to define.  You just want to list them and there is no particular order to the list.  You could then say, "This component processes the following subcomponents:"
   <ul>
   <li>This is a component name in random order.</li>
   <li>This is another component name in random order.</li>
   <li>This is yet another component name in random order.</li>
   </ul>
</dd>
</dl>

Inserting tables

Use a table to display information in multiple parts. To insert a simple table, use the table tag, with the following tags:

thead

Denotes the header row.

tbody

Denotes the body of the table.

tr

Creates a table row.

th

Creates column or row headings.

td

Creates individual columns.

The following example shows the table tags in use:

<table>
  <caption>If you don't need a caption, delete this tag.</caption>
  <thead>
    <tr>
      <th>Header column 1</th>
      <th>Header column 2</th>
      <th>Header column 3</th>
      <th>Header column 4</th>
    </tr>
  </thead>
  <tbody>
      <tr>
        <td>row 1, column 1</td>
        <td>row 1, column 2</td>
        <td>row 1, column 3</td>
        <td>row 1, column 4</td>
      </tr>
      <tr>
        <td>row 2, column 1</td>
        <td>row 2, column 2</td>
        <td>row 2, column 3</td>
        <td>row 2, column 4</td>
      </tr>
  </tbody>
</table>

Note: Insert tables no larger than 640 x 480.

Adding a screen capture

To add a screen captured graphic to your page, use the img tag, as shown in the following example:

<img src="/Documentation/CoreDevelopersGuideWebTools/zero-webtools-index-page.jpg" alt="This screen capture shows the application you just created."/>

Note that the alt tag was used in the img tag. The text in this tag should be fairly short - less than 150 characters. It is used for accessibility to provide the text in place of the graphic on screen readers for the visually impaired. Include this field for accessibility.

Note: Insert graphics no larger than 640 x 480.

Adding a drawn graphic

To add a drawn image to your page, use the img tag, as shown in the following example:

<img src="/Documentation/AssembleDevelopersGuideFlowTutorial/advancedconst.jpg" alt="This graphic shows the process flow from an order being approved to a customer being notified to come pick up his order."/>

Note that the alt tag was used in the img tag. The text in this tag should be fairly short - less than 150 characters. To give you an idea of what that looks like, in this example the text provided contains 122 characters between the quotes. It is used for accessibility to provide the text in place of the graphic on screen readers for the visually impaired.

Note: Insert graphics no larger than 640 x 480.

Linking to a spot or heading within the same file

To create a hyper link to a spot within the same file, use the a tag, as shown in the following example:

<a href="#samples">Samples</a>

Cross module linking

The short answer to this question is, "don't do it." Linking to files outside of your module is prone for breakage. Instead, give the user some key words to search for. The following examples show how to reference information in articles outside of your module:

• For more details, see the global context information.
• For more details about writing Groovy handlers, see the Groovy handler information.
• See the information about installing and configuring PHP for details.

Don't quote the full title of the article if you can avoid it because if the name in the file you're referencing changes, your reference to it won't enable users to find it. Obviously, like in the previous examples, there are times when you can't help but use the article title. The title of the article can be referenced as long as you don't make it LOOK like the title of the article. In some cases, like global context, using the title name in the reference is unavoidable, but note that it doesn't look like title of the article and the string global context is easily searched and found in the documentation.

If you want a quick summary of the rationale for this, read on:

User testing has proven that user satisfaction is affected very little with the presence or absence of inline links. However, user dissatisfaction with broken links is much higher. The trade off is obvious when the potential for breakage is so much higher when we link between modules.