One of the big benefits of XMod is that it plays nicely with your other modules. If you can write a simple SQL query, you can easily integrate XMod with the rest of the data in your database.
For example, let's say you run an ebook website. In the past, you've created or purchased an "ebook directory" module that lists available ebooks. For each ebook, it stores information such as the ebook's title, genre, author, publisher, etc. Now, you're using XMod to create an "ebook reviews" section on your site. Each review will list the ebook's title, author, genre, publisher and, of course, the review.
Of course, you'd like to leverage all the work you've done on the ebook directory and use its genre and publisher information. So, when a review is entering a review, she'll be able to choose from a list of genres and publishers, retrieved from your ebook directory. Second, you want to visually tie the reviews into the directory by providing a genre link that links to a list of ebooks in that genre and a publisher link that links to a list of ebooks published by that publisher.
Here's what you do:
In your form, insert the following control:
<select1 ref="Genre" appearance="minimal" query="SELECT GenreName, GenreId FROM EbookGenres ORDER BY GenreName ASC">
<label>Choose a Genre: </label>
</select1>
This is a standard <select1> tag with 2 differences. We've added a "query" attribute, the value of which, is a simple SELECT query. The second difference is that we haven't added any items to the list. The list box will be filled with the results of our query so we don't need to add any items. However, if you need to do so, you can add items here and they will be inserted at the top of the list.
In your display template, you would insert this HTML code:
<a href="/default.aspx?tabid=31&mid=100&genreid=<xmod:field name="Genre" usevalue="true"/>"><xmod:field name="Genre"/></a>
This is simply an HTML hyperlink that points to the tab and module that contains your module that lists books by genre. It adds the "genreid" query parameter that contains the value of the selected Genre. To get the Genre ID we use an <xmod:field> tag, pointing to the Genre form field and with the "usevalue" attribute set to true. The link's text is provided by another <xmod:field> tag. This one, doesn't specify the "usevalue" attribute and, thus, it returns the Display Text from the Genre form field. The result might look like this
Science Fiction/Fantasy
RULES:
Your query should only return 2 columns. It can return more but they will be ignored and the extra columns will use unnecessary resources.
The first column will be the Item's display text.
The second column will be the Item's hidden value
If only 1 column is returned, that value will be used for both the Value and Display Text.
Basic security checking is included. However, querying the database should be used with caution as inadvertent or intentional mistakes in the query may results in data loss.