Conceptual Content - How to Include Bulleted and Ordered Lists

Introduction

In an earlier tutorial we demonstrated the basic components used to create conceptual content. That tutorial also explained the basic building blocks, including the file types used and also how the conceptual content should be structured in order for it to be successfully compiled into a help file.

In this tutorial, we are going to look at how you can refine the layout of conceptual content pages by adding various kinds of lists.

Bulleted Lists

Although you can of course simply type in para items one below the other in order to create a list, the user experience will often be improved if you use bullets or numbers. Here's a simple example of a help page that contains a bulleted list:

To create this kind of list in the markup you use a list element with the class name "bullet". Then, within that list element you add individual listItem elements (Note the camel casing used in the name of the element here). In each individual listItem you can add whatever content you want to display. The example above uses para elements to hold the content but, as you'll see later in this tutorial you're not limited to these.

The markup that creates the help page shown above is as follows. I've highlighted the xml that creates the list:

<?xml version="1.0" encoding="utf-8"?>
<topic id=" 949a345b-d8a6-4009-9b58-efb26ab4914c" revisionNumber="1">
  <developerConceptualDocument
    xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5"
    xmlns:xlink="http://www.w3.org/1999/xlink">
   
    <introduction>
      <para>
        Bulleted Lists are created using "list class="bullet" and individual listItems.
      </para>
    </introduction>

    <list class="bullet">
      <listItem>
        <para> Public </para>
      </listItem>
      <listItem>
        <para> Private </para>
      </listItem>
      <listItem>
        <para> Protected </para>
      </listItem>
      <listItem>
        <para> Friend </para>
      </listItem>
      <listItem>
        <para> Protected Friend</para>
      </listItem>
    </list>

  </developerConceptualDocument>
</topic>

If you need to refresh your memory on how the above .aml file is referenced in the .content file, you can read up on it here.

Ordered Lists

Creating ordered lists, like the one shown below is just as easy.

In this case, the class name you use is "ordered" and the list is highlighted in bold in the markup below:

<?xml version="1.0" encoding="utf-8"?>
<topic id="57a1d911-0915-4865-c4514-581u3gf49s88" revisionNumber="1">
  <developerConceptualDocument
    xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5"
    xmlns:xlink="http://www.w3.org/1999/xlink">

   
    <introduction>
      <para>
        Ordered Lists are created using "list class="ordered" and individual listItems.
      </para>
    </introduction>

    <list class="ordered">
      <listItem>
        <para> Public </para>
      </listItem>
      <listItem>
        <para> Private </para>
      </listItem>
        <listItem>
      <para> Protected </para>
      </listItem>
      <listItem>
        <para> Friend </para>
      </listItem>
      <listItem>
        <para> Protected Friend</para>
      </listItem>
    </list>

    <relatedTopics>
      <link xlink:href="949a345b-d8a6-4009-9b58-efb26ab4914c" />
    </relatedTopics>
  
  </developerConceptualDocument>
</topic>

You'll see that the example above includes a link to the bulleted list page. These lists can be used as just one portion of a help page and you can include different kinds of formatted content on the same page as shown above.

Summary

Lists can be very useful to break up text into logical and easily digestible chunks. Although the above examples have displayed text as their list items, it is possible to use other visual elements, such as images, or differently formatted text. However MAML isn't very flexible in this regard and in many cases if you try and insert over-complex visual elements as list items, the results won't be as neat as you might want - defeating the purpose of using a list in the first place. Where you need to break the display up into clearly discrete chunks, it's often better to use section elements. But for simple lists of text, the listItem element as shown here is ideal.