As more and more people are adding XMod Pro to their development toolbox, the question often arises: "How do I convert my XMod form and template to XMod Pro?" I'll take a stab at answering that in this post.
XMod and XMod Pro share a similar syntax and heritage, but the two products are written with different purposes in mind. XMod is designed for quick creation of data-oriented solutions – without needing any programming knowledge. XMod Pro, on the other hand, was written from scratch to enable the direct interaction of XMod Pro forms and templates with your own database.
As a result, the two products are not compatible. You can run XMod and XMod Pro on the same site and even on the same page. However, XMod Pro cannot use XMod forms/templates and vice versa.
Don't let that worry you though. There are still a lot of similarities – enough that you should be able to get up and running on XMod Pro fairly quickly. With that said, in order to use XMod Pro, you should have some familiarity with how to write basic SQL commands such as SELECT and INSERT statements. You should also have a basic understanding of HTML. As with anything, the more you know, the more powerful and flexible your solutions can be.
In this post, I'm going to assume you have XMod Pro installed and have an understanding of how to use it. If not, begin by going through the walkthroughs in the help file.
This tutorial will show you how to convert a standard XMod form and its resulting GridView display template. The goal is to show you the process of conversion so that you can better see the similarities and differences between the two products. So, I won't be dealing with anything complex. Additional tutorials can be created to cover more advanced topics in depth.
Converting the Form
Since most data-oriented solutions begin with the data you want to collect, let's start with the form. This one if for tracking a company's inventory of laptop computers.
<form>
<input ref="LaptopModel">
<label>Laptop Model:</label>
</input>
<input ref="ServiceTag">
<label>Service Tag:</label>
</input>
<input ref="SerialNumber">
<label>Serial Number:</label>
</input>
<input ref="LaptopName">
<label>Laptop Name:</label>
</input>
<input ref="Owner">
<label>Owner:</label>
</input>
<input ref="Location">
<label>Location:</label>
</input>
</form>
As you can see, it is a basic auto-layout XMod form with a series of text boxes (<input> tags) used for gathering information for a specific laptop. When this form is rendered by XMod, it will display as a two-column table with the labels appearing in the first (left) column and the text boxes appearing in the second (right) column.
Use HTML to Layout Your Form
In XMod Pro, there isn't an "auto-layout" form type. All forms are built with your own HTML. This provides you with limitless flexibility when it comes to formatting and layout out your controls. That means, though, that you'll need to convert your "auto-layout" form to a Custom HTML form type. There is a mechanism to do this conversion within XMod (beginning with version 5.5). You can use that tool, but in this case, I'll simply convert it for you.
As mentioned earlier, the auto-layout form emits a table with two colums – one for the control caption (<label>) and the other for the control. There is one row for each control. So, our first step is to create the table in HTML and place our controls in it:
<form>
<table>
<tr>
<td><label>Laptop Model:</label></td>
<td><input ref="LaptopModel" /></td>
</tr>
<tr>
<td><label>Service Tag:</label></td>
<td><input ref="ServiceTag" /></td>
</tr>
<tr>
<td><label>Serial Number:</label></td>
<td><input ref="SerialNumber" /></td>
</tr>
<tr>
<td><label>Laptop Name:</label></td>
<td><input ref="LaptopName" /></td>
</tr>
<tr>
<td><label>Owner:</label></td>
<td><input ref="Owner" /></td>
</tr>
<tr>
<td><label>Location:</label></td>
<td><input ref="Location" /></td>
</tr>
</table>
</form>
If you look closely at the example, you'll notice a couple of changes. First, we used an HTML <table> tag to layout the controls. In the first cell (<td>) of each row (<tr>), we placed the <<label> tag for the control. In the second cell, we placed the control. Notice that since the <input> tag no longer has a child <label> tag, we have made it an "empty" tag: <input></input> becomes <input />
Convert Your Controls to XMod Pro Controls
With XMod Pro, we made an effort to give controls names that more closely identified what they were. Gone are <select> and <select1> tags. They are replaced by <ListBox>, <CheckBoxList>, ><DropDownList>, etc. In the case of text controls: <input> has been replaced by <TextBox>.
Additionally, <label> controls are no longer child tags of controls. Instead, they float freely, enabling you to place them where ever you'd like as you've already seen. They also allow you to format them and use them to make your form more accessible to users who need to use screen readers.
Finally, the ref attribute, which in XMod is used to designate a unique identifier for the control, has been changed to id, which is more in keeping with HTML and ASP.NET code.
One other important note about capitalization: In XMod Pro, tags no longer have to be lower-case. In most cases, you can use lower-case, upper-case, camel-case, or whatever case strikes your fancy.
So, we're going to 1) Change <input> to <TextBox>; 2) Change ref to id; Let's make those changes:
<form>
<table>
<tr>
<td><label>Laptop Model:</label></td>
<td><TextBox id="LaptopModel" /></td>
</tr>
<tr>
<td><label>Service Tag:</label></td>
<td><TextBox id="ServiceTag" /></td>
</tr>
<tr>
<td><label>Serial Number:</label></td>
<td><TextBox id="SerialNumber" /></td>
</tr>
<tr>
<td><label>Laptop Name:</label></td>
<td><TextBox id="LaptopName" /></td>
</tr>
<tr>
<td><label>Owner:</label></td>
<td><TextBox id="Owner" /></td>
</tr>
<tr>
<td><label>Location:</label></td>
<td><TextBox id="Location" /></td>
</tr>
</table>
</form>
Making the form more accessible
Here's a quick and easy thing you can do to make life easier on your users who are disabled or are using screen readers: use the for attribute to link your <label> tags with their related controls.
<form>
<table>
<tr>
<td><label for="LaptopModel">Laptop Model:</label></td>
<td><TextBox id="LaptopModel" /></td>
</tr>
<tr>
<td><label for="ServiceTag">Service Tag:</label></td>
<td>< TextBox id="ServiceTag" /></td>
</tr>
<tr>
<td><label for="SerialNumber">Serial Number:</label></td>
<td>< TextBox id="SerialNumber" /></td>
</tr>
<tr>
<td><label for="LaptopName">Laptop Name:</label></td>
<td>< TextBox id="LaptopName" /></td>
</tr>
<tr>
<td><label for="Owner">Owner:</label></td>
<td>< TextBox id="Owner" /></td>
</tr>
<tr>
<td><label for="Location">Location:</label></td>
<td>< TextBox id="Location" /></td>
</tr>
</table>
</form>
Now, let's convert the <form> tag to the XMod Pro <AddForm>. Unlike XMod, each XMod Pro form can contain two form definitions – one to display when the user is adding a record (<AddForm>) and the other to display when the user is editing a record (<EditForm>). Typically, the <EditForm> is a copy and paste affair from the <AddForm> since only a few items need to be changed. For now, we're going to focus on the <AddForm> to keep things simple. Of course, the user has be have a way to submit the form too, so we'll also add an <AddButton> tag for that.
<AddForm>
<table>
<tr>
<td><label for="LaptopModel">Laptop Model:</label></td>
<td><TextBox id="LaptopModel" /></td>
</tr>
<tr>
<td><label for="ServiceTag">Service Tag:</label></td>
<td><TextBox id="ServiceTag" /></td>
</tr>
<tr>
<td><label for="SerialNumber">Serial Number:</label></td>
<td><TextBox id="SerialNumber" /></td>
</tr>
<tr>
<td><label for="LaptopName">Laptop Name:</label></td>
<td><TextBox id="LaptopName" /></td>
</tr>
<tr>
<td><label for="Owner">Owner:</label></td>
<td><TextBox id="Owner" /></td>
</tr>
<tr>
<td><label for="Location">Location:</label></td>
<td><TextBox id="Location" /></td>
</tr>
<tr>
<td colspan="2"><AddButton text="Add to Inventory" /></td>
</tr>
</table>
</AddForm>
Believe it or not, our form conversion is almost complete. The last stage of the conversion is all about the data.
Binding Our Form to the Database
XMod handles all the data operations for you behind-the-scenes. Since XMod Pro's reason for being is to enable you to link your forms (and templates) to your database, we'll need to do a little extra work to make that happen.
Introducing the <SubmitCommand>
When a user submits the form by clicking the <AddButton>, the <SubmitCommand> is executed. This contains a SQL command that, usually in the case of an AddForm, inserts the record into the database. This command can be a standard INSERT statement or it can call a stored procedure. It can also execute a command in a SQL Server database outside of the DNN database, but we'll stick with something simple for this example.
<SubmitCommand CommandText="INSERT INTO LaptopInventory(LaptopModel,ServiceTag,SerialNumber,LaptopName,Owner,Location) VALUES(@LaptopModel,@ServiceTag,@SerialNumber,@LaptopName,@Owner,@Location)" />
The CommandText attribute is where you place your SQL command. In this case, it is a simple INSERT command. It creates a record in LaptopInventory. Notice the @LaptopModel, @ServiceTag, etc. parameters. These parameters will be replaced with values from your controls when the user submits the form. But, how do we link them with the controls? Answer: we bind them using the DataField attribute of our controls. Notice in the example below that the DataField attribute must match the corresponding @ParameterName for the control to be bound correctly.
<AddForm>
<SubmitCommand CommandText="INSERT INTO LaptopInventory(LaptopModel,ServiceTag,SerialNumber,LaptopName,Owner,Location) VALUES(@LaptopModel,@ServiceTag,@SerialNumber,@LaptopName,@Owner,@Location)" />
<table>
<tr>
<td><label for="LaptopModel">Laptop Model:</label></td>
<td><TextBox id="LaptopModel" datafield="LaptopModel" /></td>
</tr>
<tr>
<td><label for="ServiceTag">Service Tag:</label></td>
<td><TextBox id="ServiceTag" datafield="ServiceTag" /></td>
</tr>
<tr>
<td><label for="SerialNumber">Serial Number:</label></td>
<td><TextBox id="SerialNumber" datafield="SerialNumber" /></td>
</tr>
<tr>
<td><label for="LaptopName">Laptop Name:</label></td>
<td><TextBox id="LaptopName" datafield="LaptopName" /></td>
</tr>
<tr>
<td><label for="Owner">Owner:</label></td>
<td><TextBox id="Owner" datafield="Owner" /></td>
</tr>
<tr>
<td><label for="Location">Location:</label></td>
<td><TextBox id="Location" datafield="Location" /></td>
</tr>
<tr>
<td colspan="2"><AddButton text="Add to Inventory" /></td>
</tr>
</table>
</AddForm>
After reviewing the code, you may be wondering if the DataField value has some relation to the ID attribute value in each control, since they are identical in our example. The answer is no. The ID is used for identification purposes only. The DataField value is the important one for binding to your data. It needs to match the @Parameter in your CommandText.
Well, that's all there is to converting an XMod form to an XMod Pro form. Of course, there are a lot more details and features that could be added. Notably, we could specify a DataType for each of our controls and we could add validation too. But, the purpose of this tutorial was to give you an overview of the process, showing you how simple it can be to make the switch.
I'll be covering the GridView display template conversion and the EditForm in up-coming articles.