This exercise will cover creating and using a custom control.  Custom controls can be used to display or collect data in a specialized way (as in; a simple text or dropdown is just not sufficient).  In the last exercise, Mobile Data Entry and Validation, we were providing the user a textbox to enter a date.  Let’s replace that textbox with a calendar.

(You may download the source for this exercise from CodePlex.)

Building the ListItemStyle
The first step to creating a custom control is to create the template that will be used to render it.  The easiest way to do this is to create a static HTML representation first and then templatize it.  A control template is an XSLT that builds the control based on properties.

Note: All custom controls should be contained within an <li> since all ListItems are put inside a <ul>.

Note: Be sure to break out any supporting JavaScript and CSS into their own files to be used in support of your control.

The following is a small portion of the template we have built to be our calendar datepicker:

...<div class="calendar" style="display:none;">

    <xsl:attribute name ="id">

      <xsl:value-of select="Properties/Property[@name='__FormKey']"/>

      <xsl:text>_cal</xsl:text>

    </xsl:attribute>

    <xsl:text>-</xsl:text>

  </div>

  <div style="clear:both;">

    <input type="hidden">

      <xsl:attribute name ="id">

        <xsl:value-of select="Properties/Property[@name='__FormKey']"/>

      </xsl:attribute>

      <xsl:attribute name ="name">

        <xsl:value-of select="Properties/Property[@name='__FormKey']"/>

      </xsl:attribute>

      <xsl:attribute name ="value">

        <xsl:value-of select="Properties/Property[@name='Value']"/>

      </xsl:attribute>

    </input>

  </div>

</li>

Notice the hidden field that we are adding with the ID set to the FormKey value set for this control.  This will allow us to use JavaScript to populate that hidden field based on the selection in the calendar and then reference that date server-side like any other form property.

Also notice the use of the Properties.  These are what you set server-side as the Properties of your EntreeListItem or EntreeFormItem.  This being a form item for data collection, it is an EntreeFormItem.

See ListStyles.xml for another example of creating a custom list style.

Adding the Template to ListStyles.xml
Now you have a control template and some supporting js and css files.  The next step is to create a custom ListStyles.xml for your application and add the template to it.  A ListStyles.xml file that resides in your application's PluginPath will be merged with the default and will add styles or replace styles that you have defined.  In our case, we want to add a single item style and call it "calendar".  Our calendar style is only supported by the A and B tier device platforms, so we will only add the style to those.  To be completely thorough, you could add a simple text box for the C platforms, but this exercise is not covering that.

Your ListStyles.xml file should look like this:

<ListStyleConfig>

  <Platform ID="A">

    <ListItemStyles>

      <ListItemStyle name="calendar">

        [template goes here in CDATA]

      </ListItemStyle>

    </ListItemStyles>

  </Platform>

  <Platform ID="B">

    <ListItemStyles>

      <ListItemStyle name="calendar">

        [template goes here in CDATA]

      </ListItemStyle>

    </ListItemStyles>

  </Platform>

</ListStyleConfig>

Note: The template for your control goes inside the ListItemStyle as a CDATA node.

Adding Your Resources to UserAgentMapping.xml
The UserAgentMapping.xml file that resides within your application's PluginPath will also get merged with the default.  Here is were you add the reference to the supporting resources your calendar requires.

<UserAgentMapping>

  <UserAgent match="">

    <CSS>

      <File name="calCSS" href="cal.css"/>

    </CSS>

    <Script>

      <File name="calendar" src="cal.js"/>

    </Script>

  </UserAgent>

</UserAgentMapping>

Adding All These Files to Your Feature
Basic SharePoint feature development here.  Just make sure all your files (XML, JS, CSS) are being put into the directory you specified as the PluginPath of your application.

Note: Where these files are put is a function of the SharePoint feature definition.

Then once we deploy and take a look using SharePoint Designer:

Using The New Control
You have completed the difficult part, now it's time to enjoy the fruits of your labor.  You can add your new calendar control to the screen like you would any other control.  The textbox we are replacing was added like this:

EntreeTextBox date = lGrp.AddFormItem<EntreeTextBox>("Date");
date.Name = "Date";

Since our calendar control is custom, we can't use any of the built-in controls.  We will have to use a generic control like this:

EntreeFormItem c = lGrp.AddFormItem("Date");
c.ListItemStyle = "calendar";
c["Name"] = "Select Date";
c["Value"] = DateTime.Today.ToShortDateString();

Notice how we are setting the ListItemStyle to the name of our style and we are setting two properties, Name and Value.  This is all you have to do, the date value will be available through the same FormProperty when the user submits.  You now have a calendar datepicker instead of a texbox!

 

You may download the source for this exercise from CodePlex.