Templates are used to tell XMod how to display data entered with your forms. In most respects, they are like HTML pages since you use HTML tags to position and format your data. Most HTML tags which are found in the <body> of an HTML page are valid in a template, so you are free to design the page in just about any way you like.
What makes templates different than HTML pages is that they also use special XMod Template Tags. These tags are much like HTML tags, except that they tell XMod what data to get and where to put it. All XMod Template Tags begin with "xmod:". For example, the one you'll probably use most is the "<xmod:field>" tag. As with HTML tags, most XMod tags have attributes that determine how they function. For the <xmod:field> tag, one required attribute is the "name" attribute. The name attribute determines which form field's value to retrieve. There are others, like "maxlength"... they are detailed in the Template Tags reference section of this help file.
Templates come in two basic flavors - List View templates which present a browse-able list of records (this could be presented to the user as a list or grid) and Detail View templates which present a single record. The easiest way to think of this is by imagining a news site which presents you with a list of headlines (perhaps with a synopsis of each story). This is the list view. You then click a headline to read the full story. This is the detail view. One of the strengths of XMod is that you aren't limited to a single view of the data. You can create multiple templates - each with its own look and/or functionality - but all of them working from the same set of data, the data entered via an XMod form. So, you could create a template for your normal visitors and one for your site editors and one for your content providers.
In this walkthrough, we'll be creating a total of 3 templates: 1) A list view template, displayed as a list; 2) A list view template, displayed as a Grid; and 3) A detail view template. Each of these templates will be designed to display data from the Ebook Reviews form created in the Form Walkthrough.
A Note About Syntax of XMod Tags.
It is very important that you use the proper format when using XMod tags. Most tags are "empty" tags, meaning that they do not have a closing tag. For example, the <p> tag in HTML is a "tag" pair, written as <p>.... some text ... </p>. However, the <img> tag is an empty tag, as it doesn't have the closing tag. Using proper XHTML syntax, the <img> tag should be written as <img src="/images/myimage.gif" /> Here, the tag is written as a single tag, but the tag is written with the closing "/>" Empty XMod tags should be written this way. The examples in the Template Tag reference should guide you in properly constructing a tag.
Creating the Templates
To refresh your memory, the fields we created in our Form Walkthrough, for entering Ebook Reviews are listed below:
Title (text box)
Author (text box)
Reviewer (text box)
Genre (single-select list box)
Review (textarea, also called a multi-line text box)
To begin, if you haven't already added an XMod module to a tab, do so now. On the Actions menu, select "Manage Templates." This screen is where you add, edit, and delete display templates.
From the "Manage Templates" starting panel, click the Add New Template button to display the Add Template panel. Enter a descriptive name for this template. We'll first be creating the Detail view for the review, so an appropriate name might be: "Ebook Review - Detail". If it's not already selected, choose Detail View as the Template Type. Finally, to help XMod help you save some keystrokes when you create your template, select Ebook Review for the Form Fields list box. Note that when you select a new Template Type and when you select a new Form Fields form, the page will post back to the server so that XMod can make the necessary changes to the page. If, however, you use the keyboard to select new items, the post back will not occur and the changes will not happen. For this reason, it's always advisable to use your mouse to change the selection of these list controls.
Next, click the Editor tab (shown in the gray bar next to the General tab) to see the template editor.
In the toolbar area you'll see two drop-down list controls: Template Tag and XMod Constant. These are very similar to the drop-down lists in the Form Editor. Template Tag contains a list of tags you can use in your template. Selecting an item from this list and clicking the Add button will either pop-up a tag designer or insert text into your template. The XMod Constant list control contains the same type of dynamic data that we found in its counterpart in the Form Editor. Items in this list allow you to insert the portal's ID, the current user's name, the current date, the user's IP address and more.
More details on how to use the template editor can be found in the help topic How Do I Create A Template. For the purposes of this example, though, we'll simply copy and paste text into the editor. In the text box enter the following code:
<div class="Normal">
<h2><xmod:field name="Title"/></h2>
<strong>Author:</strong> <xmod:field name="Author"/><br />
<strong>Genre:</strong> <xmod:field name="Genre"/> <br />
<strong>Reviewed By:</strong> <xmod:field name="Reviewer"/> <br /><br />
<strong>Review:</strong><br />
<xmod:field name="Review"/>
</div>
Now, let's explain a bit about what all that code means. We'll gray out certain parts of the code, to make it easier to focus on the item(s) we're discussing...
<div class="Normal">
<h2><xmod:field name="Title"/></h2>
<strong>Author:</strong> <xmod:field name="Author"/><br />
<strong>Genre:</strong> <xmod:field name="Genre"/> <br />
<strong>Reviewed By:</strong> <xmod:field name="Reviewer"/> <br /><br />
<strong>Review:</strong><br />
<xmod:field name="Review"/>
</div>
In the code above we're creating a <div> tag to wrap our template. A <div> tag is an HTML tag used to contain other items - usually for the purposes of applying certain styles to the contained items or to aid in laying out text on the page. In our case, we've added it to make it easy to apply the CSS "Normal" style to our text in one fell swoop (class="Normal"). The "Normal" CSS class is built into DotNetNuke and is typically used for most text throughout the site.
<div class="Normal">
<h2><xmod:field name="Title"/></h2>
<strong>Author:</strong> <xmod:field name="Author"/><br />
<strong>Genre:</strong> <xmod:field name="Genre"/> <br />
<strong>Reviewed By:</strong> <xmod:field name="Reviewer"/> <br /><br />
<strong>Review:</strong><br />
<xmod:field name="Review"/>
</div>
We want to create a heading for the title of the ebook we're reviewing. So we use the HTML <h2> tag, which indicates the content it contains is a 2nd-level heading. You could change this to an <h1> to indicate the title is a top-level heading, <h3> for a 3rd-level heading, or some other tag, depending on your needs. For our purposes, <h2> tags typically tend to be displayed as fairly large, bold text - but not so large that they dominate the page (as is the case typically for <h1> tags).
Inside the <h2> and </h2> tags, you'll find <xmod:field name="Title"/>. This is an <xmod:field> tag is the most often used template tag. The reason is simple. This is the tag you use to position data from fields in the record. If you look at all the <xmod:field> tags, you'll see that they all contain a "name" property whose value is the name (i.e. the "ref" value of a form control tag) of a control on our form. In this case it's "Title", which is the title of the ebook that has been reviewed.
<div class="Normal">
<h2><xmod:field name="Title"/></h2>
<strong>Author:</strong> <xmod:field name="Author"/><br />
<strong>Genre:</strong> <xmod:field name="Genre"/> <br />
<strong>Reviewed By:</strong> <xmod:field name="Reviewer"/> <br /><br />
<strong>Review:</strong><br />
<xmod:field name="Review"/>
</div>
In the rest of the template you'll see <xmod:field> tags (highlighted in red) corresponding to the fields (or controls) we created in the Form Walkthrough. We've provided a bolded caption for each field using the <strong> and </strong> HTML tags. To indicate where a line break should go, we've added the HTML <br /> tags. The important point to remember is that all we're doing is creating a mini-web page and sticking in data from our form, via the <xmod:field> tags.
Click "Save Template" to save our Detail template then click the Add Template button to create a new template.
Click the General tab and give this template the name "Ebook Review - List". Choose "List View - List" for the Template type (do this with your mouse and allow the page to postback to the server). Once the page has posted back, you'll see 2 new tabs: Template Settings and Item Settings, which we'll cover in more detail in a bit. Finally, select Ebook Review from the Form Fields drop-down list box and allow the page to post back before continuing.
Click the Template Settings tab and fill in the form as you see it below:
On this tab we're telling XMod how the list view should look and function as a whole. We're telling it that when someone clicks a link to see the details of a record, it should temporarily hide the list view and replace it with the detail view. This is done by checking the "Show Details Inline" check box.
Next, we want each record in the list to have some white space between them, so we've specified cellpadding and cellspacing of 5 pixels. Finally, we want a border around our list that is a solid, 1 pixel black line.
Click the Item Settings tab to specify how each item in the list will be displayed. On this tab, you also control how the pager, header, footer, and search bar will look. You can read more about this in the How Do I Create A Template help topic. To keep things simple, we're only going to focus on the Item Style and Alternating Item Style sub-tabs. The Item Style settings apply to the odd-numbered items in the list - i.e. the 1st, 3rd, 5th, etc. The Alternating Item Style settings apply to the even-numbered items - the 2nd, 4th, 6th, etc. If no Item Style settings act as the "base" style for all items unless overridden by settings in the Alternating Item Style settings. So, if you don't specify anything for Alternating Item Style, then the Item Style settings will be applied to all items in your list. Fill out the Item Style and Alternating Item Style sub tabs with the information provided below. Basically, all we're doing is specifying the color #E7E7FF as the background color for each odd-numbered item and the color white (#FFFFFF) for each even numbered item:
Next, click the Editor tab to reveal the template editor. The contents from your detail template may still be in the editor. This is done by XMod to save you some keystrokes if you want to create a series of similar templates - one after another. In our case, though, just delete the contents. Copy and paste the following code into to the editor:
<xmod:field name="Title" class="NormalBold" detaillink="true"/> by <xmod:field name="Author" class="Normal"/><br />
Reviewed by <xmod:field name="Reviewer" class="Normal"/>
This code is similar to what we've seen in the detail view template. There are two changes of note. The first, highlighted in blue is the "class" property of the <xmod:field> tag. This allows us to specify a CSS class to the contents of the field. Here's we're applying the DNN NormalBold class to the title and the DNN Normal class to the other fields. Second, we're using the <xmod:field> tag's "detaillink" property. By setting its value to true, we're telling XMod to turn the ebook's title into a link that automatically loads the full ebook review (i.e the detail view).
Click "Save Template" to save our list view template..
At this point, we have enough templates, but we'll create another grid-style list view template, just to show how it is done. Click the Add New Template button to create our new template. On the General tab, type "Ebook Review -Grid" in the Template Name field, select "List View - Grid" from the Template Type drop-down list and allow the page to post back to the server. If necessary, select our Ebook Review form from the "Form Fields" drop-down list.
Click the Template Settings tab to set the styling for the grid. It looks very similar to the Template Settings tab for List-type list templates. This time, we're additionally going to check the "Show Header" check box so column headings will be shown. Additionally, we'll set the Gridlines setting to "Both".
On the Item Settings tab, click the Item Style sub-tab and verify the background color is #E7E7FF while, on the Alternating Item Style sub-tab, the background color is #FFFFFF (white).
Click the Editor tab and delete anything that is in the editing area. Grids are made up of columns. In XMod, they are represented by <column> tags. To create a column, simply select it from the Template Tag drop-down list and click the Add button:
When you do this, the <column> tag designer will pop-up (please make sure your browser is set to allow pop-up windows). This designer is kind of a mini-editor for a single column in your grid. It allows you to set the column properties (Header and Footer) and insert additional XMod fields, just as you do in the main editor.
The first column will list the ebook's genre. So, in the Header field, type "Genre". Then either choose <xmod:field> from the drop-down list to create the tag for the Genre field or simply copy and past the following text into the editing area of the column designer:
<xmod:field name="Genre" class="Normal"/>
When you're finished click the OK button to hide the designer. In the main editing area you'll see:
<column header="Genre"><xmod:field name="Genre" /></column>
You can follow the same process for the remaining columns or simply copy and paste this code:
<column header="Title">
<xmod:field name="Title" class="NormalBold" detaillink="true"/>
</column>
<column header="Reviewed By">
<xmod:field name="Reviewer" class="Normal" />
</column>
Click "Save Template" and you're done. All that's left is to configure an XMod module to use the templates and the form.
From the XMod module's Actions menu, select "Configure XMod Module". This screen enables you to determine which data is displayed and how it's displayed by choosing a form and a list and detail template.
On the General Tab, select our Ebook Review form, created in the Form walkthrough, in the "Data Entry Form" drop-down list.
Click the "Display" Tab to assign the templates we just made.
Select "Ebook Review - Detail" from the "Detail View Template" drop-down list.
Select "Ebook Review - List" or "Ebook Review - Grid" from the "List View Template" drop-down list - depending on which view you'd like of your data.
Click "Save Changes" to save your settings and return to the main screen.
Next, you'll want to add some test data. To do so, select "Add New Item" from the Actions menu to bring up your data-entry form. Add a few test records and you'll be able to see your templates in action.
For More Information on XMod Template Tags, see the Template Tags section