How Do I... Create A Template

What is a template and why do you need one?

There are two main parts to most every XMod solution: data-entry forms and display templates. The forms enable you and your users to store data in XMod and the display templates allow you to format and display that data to your end-users. If you're just creating a one-way solution like a Contact Us or Feedback form, you may not need a template. For all the other cases, though, you'll need to tell XMod how to format your data and display it to the person viewing the page. If you haven't already done so, step through the How Do I Create A Form topic

The Data Entry Form

Since data-entry forms and templates go hand-in-hand, for this topic, we'll use the simple form created in the How Do I Create A Form topic. That form looked like this:

A Basic Form for entering First and Last Names as well as Favorite Color

This form contains three controls. Each has a unique name or ID. This is defined in the control's ref (for reference) attribute. It uniquely identifies the control so that it can be referenced later (as we will do in this example). For the form above, the control names are: FirstName, LastName, FavoriteColor. Each of these controls is best thought of as a form field. For this reason, we'll find ourselves using a special XMod tag called a field tag to position and format data from the form.

Two Types of Templates

Before continuing, it would be instructive to learn a bit more about templates and how they work.

List View Template

There are two basic types of display templates: The first is a list view. This is simply a list of records, often used for browsing. Though it's not required, typically list views will display a small amount of data from each record so the viewer can quickly locate an item of interest. A good analogy would be a list of news headlines. They will display the article title and a short synopsis. List views can be displayed as simple lists or as grids. A list view template will describe how one record should appear and XMod will apply that formatting to all the records it displays.

List View - News Stories

Detail View Template

The second type of template is a detail view. As its name implies, this view typically will display much more information to the end-user. Detail templates only display a single record at a time. Carrying on with our news analogy, the detail view would be the full story. So, the user would scan the headlines (list view), locate an article of interest, click a link and be shown the full story (the detail view).

Detail View - News

Creating Two Simple Templates

Since we want to focus on the process of creating templates, our examples will be quite simple and will use the simple form created in the How Do I Create A Form topic. Once you understand the basics, we suggest putting it all together with the more advanced walkthrough: Creating A User Profile. Let's build a list view template and detail view template for our simple form.

Select "Manage Templates" from the Actions menu of any XMod module.
Give the page a chance to load completely. On that page, click the Add New Template link
Now you'll see the Add New Template panel. This panel initially contains two tabs because the panel defaults to creating a detail view. Since we're creating a detail view template, that works just fine for us. Give your template the name Simple Form - Detail, ensure Detail View is selected for the Template Type, and select Simple Form for the Form Fields list box. Performing this last step allows the template editor to know what form you're working with so you don't need to memorize your form's field names.
Next, click the Editor tab to view the template editor. Here you can include text, HTML, and special XMod tags to create your template. We'll keep things simple for our purposes - a simple layout, including all the fields from our form. Copy and paste this code into the editor area:
First Name: 
Last Name: 
Favorite Color:
This creates some headings which are bolded (the and tags surround the text you want to make bold). Second, to signify you want to include a line break, use the tag.
At this stage we have our headings, but we haven't told XMod where to put the data. We'll start with the FirstName field. Place your cursor on the first line, between the and tags. This is where we'll put the FirstName data.
From the <Xmod> drop-down list box, select <xmod:field>. This is the tag you'll most frequently use when building templates. It's the one to use to tell XMod where to place the data from a form.
This will pop-up the <xmod:field> tag's designer. If the window does not appear, ensure that your browser allows pop-up windows. There are numerous properties that can be set for the tag. Right now, though, we're only concerned with the Name property. A drop-down list appears with all the fields from your form. Select FirstName from the list and click the OK button.
Your code should now look like this (the new code is highlighted in red:
First Name: <xmod:field name="FirstName" /> 
Last Name: 
Favorite Color:
Repeat the process for your other two fields: the Last Name field and the FavoriteColor field. When you're done, you're code should look like this:
First Name: <xmod:field name="FirstName" /> 
Last Name: <xmod:field name="LastName" /> 
Favorite Color: <xmod:field name="FavoriteColor" />
As it stands, the data will be displayed using the browser's default styling. The next thing we'll do is wrap the contents in a <div> tag. This is an HTML tag that you can think of as a panel. <div> tags are very helpful when you want to apply a style to part of your template. We're going to add the <div> tag and give it a CSS class of "Normal" - DNN"s default class for text. After our changes (in red), the code looks like this:
<div class="Normal">
First Name: <xmod:field name="FirstName" /> 
Last Name: <xmod:field name="LastName" /> 
Favorite Color: <xmod:field name="FavoriteColor" />
</div>
The final tweak we want to make is a bit more advanced than what we've done so far. It's a good example of how flexible XMod can be. We can actually use values from the form in conjunction with HTML to produce some pretty powerful results, with very little effort.

In our example, when we're displaying the user's favorite color, we don't want to just display it in black. Instead, we'll use the favorite color as the color of the text. So, instead of Red, Green, or Blue, the user will see Red, Green, or Blue. Since this is such a small piece of text, we won't use the <div> tag as we did before. Instead we'll use the HTML tag, which is intended for smaller uses like this.

Remember that each of our list items had a color name (Red, Green, Blue) and also a hidden value in which we stored the HTML RGB value of the color. That value will come in handy here. We're going to use the value to tell the tag what color to use for the text. Here's what our template looks like now, with the relevant code highlighted:
<div class="Normal">
First Name: <xmod:field name="FirstName" /> 
Last Name: <xmod:field name="LastName" /> 
Favorite Color:
">
<xmod:field name="FavoriteColor" />

</div>
So, what are we doing here? Ordinarily, the tag would look like this:
... for Red or
... for Green or
... for Blue

All we're doing, then, is putting another <xmod:field> tag where the color value would be specified. The only thing different is that we need to tell XMod to use the field's hidden value which contains the color value, rather than the display text, which contains the color's name. We do this by setting the <xmod:field>'s usevalue property to true When the template is displayed, the color's value will be placed in the span's tag.
Click the Save Template link to save your template and return to the main Manage Template page.

Creating the List View Template

From the main Manage Templates page, click Add New Template again. Make sure the General tab is selected and enter the following information:
After you select "List View - List" as the Template Type, the page will post back to the web server and 2 new tabs will appear: Template Settings and Items Settings. Click the Template Settings tab.
In the Options section, check the Show Details Inline check box. By doing this, when the user clicks a link to view the details of a record, those details will be shown in-place, rather than on a new page. While you're still on the Template Settings tab, in the Styling section, type Normal into the CSS Class box. This will give everything in the list a default style. Next, let's provide some "white space" between rows (via the cell padding property) and give the list a border (Border: style, width, and color). You can see all the settings in the screen shot below:
Next, we're going to set up our list with a "green-bar" effect (for those of you whose time in the computer trenches go back a few years). This is an effect where every odd-numbered item will have one background color and every even numbered item will have a different background color, making it easier for the user to distinguish them. Achieving this effect is very simple. Click the Item Settings tab. Then click the Item Style sub-tab. These settings affect all odd-numbered items.
All we need to do here is select the background color. You do this by clicking the paint can to activate the color picker. Select the background color you want (in this case we're going with a pale orange) and the HTML RGB color code will be inserted into the box. You can optionally type in the color code, but we find the color picker to be fast and easy.
Next, click the Alternating Item Style sub-tab and select a different color. We're going to select white (#FFFFFF).
Finally, click the Editor tab. If you're following along with each step, the code from your detail template is probably still in the editor. This is handy. Since all we have to do is remove and re-arrange a little. We're going to remove the Favorite color from the list view and put the First and Last names on the same lines.. When you're finished, your code will look something like this:
Full Name:
<xmod:field name="FirstName" /> <xmod:field name="LastName" />
The last think we'll do is add a link for the user to click to view the record's details. There are a couple of ways we could do this. There is a property of the <xmod:field> tag that will turn it into a detail link automatically. If we want to go that route, our code might look like this
Full Name:
<xmod:field name="FirstName" /> <xmod:field name="LastName" detaillink="true"/>
In the above code, the person's last name will appear as a hyperlink, linking to the details.

Alternatively, we can use the <xmod:detailbutton> tag. At run time this tag will show up as a hyperlink by default, but you can also set it to show as an HTML button or even a clickable image. You can set all these properties using the tag's designer by selecting <xmod:detailbutton> from <Xmod> drop down list. For our purposes, though, it's just as easy to type it in. Here's what your finished code will look like - with the new code highlighted in red:
Full Name: <xmod:field name="FirstName" /> <xmod:field name="LastName" /> 
<xmod:detailbutton text="Show Details" class="CommandButton" display="linkbutton" />
Click Save Template to save your changes. Next we'll put everything together by configuring a module to use our form and two templates.

Putting It All Together

We've done all the heavy lifting. All that remains to be done is set up a module to use our form and templates.

If you haven't already done so, place an XMod module instance on a page and click Configure XMod Module in the Actions menu.
On the General Tab select "Simple Form" as the Data Entry Form, "Simple Form - Detail" as the Detail View Template, and "Simple Form - List" as the List View Template:
Click the Save Changes link and you're done.
On the resulting page, you'll get a No Items Were Found message because no records have yet been added. Add a few records by clicking the Add New Item link at the bottom of the module or via the Actions menu.

Finally, here are a couple of screen shots showing our module in action:

The List View with 3 records, neatly displaying our "green bar" effect. When the user clicks the Show Details link, they'll see the 2nd view (our detail template). On this view we see that John Adams' favorite color is Red and we see it display in the color Red. XMod also, by default, supplies a Return link. When the user clicks it, they're taken back to the list view.

Final Thoughts

XMod is a very powerful module that can be made to create all sorts of solutions. This was a simple example of what can be done. The more you work with it, the more you discover what it can do. Now that you have a basic understanding of how to create forms and templates (as well as a few advanced techniques), we encourage you to read through more of the help file and discover all that XMod can offer. Another valuable source if information can be found by visiting the XMod community on our Forums. They can be found at http://dnndev.com