Custom Fields in Templates

Custom fields are displayed via a special macro called msgCustomField. While we will use that macro in these docs, we're not going to fully document it here. (For the docs on the msgCustomField macro, follow that link to the official macro docs.) Instead, this section will focus on adding the field to various templates.

This page assumes that you've edited a template before, using Conversant's admin interface. If not, read the docs.

The first and most obvious place to add a custom field is in your message teplates. These are the templates which define the look of your discussion group pages: what fields are available, and where they appear on the page. Each conversation uses two message templates: one for reading (viewing) messages, and one for editing messages.

There isn't anything special about using custom fields in your templates, except that you need to use the msgCustomField macro instead of one of the other msg* macros. If you've used macros before, and you've edited a template before, then you are ready to add a custom field to your templates.

How Does Conversant Know Which Template to Use?

How does Converant know which templates to use for your conversation? Asked another way, How can you tell Conversant which templates to use for viewing and editing messages in your conversation? This is accomplished by setting a preference in the admin area, specifically for the "Default DG" plugin. Go to this page in the admin area of your site:

conversationURL/admin/conversations/convName/preferences$plugin=Default%20DG

The Message View Template and Message Edit Template specify which template is used for viewing and editing messages (respecively) in the conversation's discussion area.

Practice: Add the Field to a Message Editing Template

Now we'll walk through the process of adding a custom field to your message editing template, so that you can set the field's value when you create or edit a message.

The practice steps will use a copy of the template named, "Styled Message Editing READONLY." This is the default template used by most new conversations. If your conversation uses a different template, then either work with a copy of your template and adjust the steps to suit, or follow along with the same template we use here (for practice) and then do it again with your own template when you're more comfortable with the process.

Here's a summary of the following steps, for those readers who are experienced enough to not need the detailed, step-by-step instructions. First, we're going to make a copy of the template "Styled Message Editing READONLY", and the copy will be named "Message Editing - Custom Field Practice". Then we'll edit that template, adding a row to the table of message headers which will contain the field label and the custom field. When we're done editing the template, we'll save it and then change the conversation's preferences to use that template, so that we can see the custom field in action when we edit a message.

This is not a general tutorial on creating and editing templates, so some of the details will be glossed over. For more information on creating and editng templates, see the How-To tutorial.

Let's get started!

1. Create the Template
   

   We're going to modify a copy of a "read only" template, because every conversation has access to these templates. Obviously, we can't modify the read only template itself.

   1. Go to the Templates section of your conversation's admin area.
   2. Click on the "Create" tab near the top-center of the page.
   3. Type "Custom Fields Message Editing" for the name of your new template.
   4. Select "Styled Msg Editing READONLY" from the popup (or 'dropdown') menu.
   5. Click the New Template button.

   After creating the template, your browser will show the template editor form.

   
   
2. Edit and Save the Template
   

   All we're going to do to this template is add one row to the table of message headers that appears at the top of the message editing form. This row will contain the title (the name of the row), and a macro to insert the custom field's widget.

   1. The seventh through the fourteenth lines of the template contain the Subject row of the message's header. Click at the beginning of the seventh line and select all of the text through the end of the fourteenth line, then copy it.
   2. Position the flashing text-insertion cursor at the beginning of the fifteenth line, and paste a copy of the lines selected in the previous step. If the template was saved at this point, you'd have duplicate copies of the Subject row and field in your message editing template.
   3. Change the word "Subject" (at line 20) to "Keywords".
   4. Change the #msgSubject macro (at line 23) to the #msgCustomField macro, as follows:
      

      <!--#msgCustomField fieldName="Keywords"-->

   5. Click on the Save Template button at the bottom of the template-editor form.

   That's it, your template is ready to be used, and will allow you to edit the keywords field, along with the other fields in your messages.

   The final, edited version of the template can be seen by clicking this link.

3. Use the Template
   

   Putting the template to use requires setting a single preference, as described above. To change the preference, follow these steps:

   1. Click on the "Preferences" link near the top left of the page, underneath the "Select Conversation" popup menu.
   2. Click on "Default DG", just below "Preferences".
   3. In the center of the page, find the popup menu labelled Message Edit Template and change its value to "Custom Fields Message Editing".

Now go back to your site, and create a new message. Near the top of the page you'll see the Keywords field! Enter any text into that field, and then save the message.

Almost Finished

After saving the message at the end of the last section, the message page loads into your browser but does not display the text that you entered into the keywords field. In fact, there is no place for the keywords text to be displayed, at all. This is because you only added the field to the message editing template, but not to the message viewing template.

Follow the steps above, but work with a copy of the template Styled Msg Viewing READONLY instead of the editing template, and set the Message View Template preference. Now you can set and view the keywords field in your discussion group messages!