Creating custom widgets for your portal is sometimes necessary if you want the built-in smooth feeling of pure custom code as well as the performance and customization capabilities that come with it.
Developing custom MVC widgets for Sitefinity is not the same as developing standard MVC widgets for any other ASP.NET site. There are special APIs and considerations one must take in order to develop an MVC widget that fits within the Sitefinity and The Portal Connector framework and architecture.
The purpose of this blog post is to provide you the ability to get yourself up and running with developing a custom MVC widget that connects to Dynamics CRM and sends and retrieves data through form submissions.
We’re going to be developing a custom form control widget for The Portal Connector, a colour picker control. This widget will have a designer to specify what attribute you want to save the color value to and a front end using the Kendo UI framework to select a color.
Download
Download the widget files from here.
Add the files to your SitefinityWebApp project in the root folder. Ensure that the JavaScript files and cshtml files build action is set to "Embedded Resource". Add the appropriate references to the Portal Connector dll files in your bin folder, namely "pavliks.PortalConnector", "pavliks.PortalConnector.Mvc" and "pavliks.PortalConnector.Mvc.Forms"
The Controller
The controller part of an MVC Sitefinity form widget generally just decides what view to use. For our example, the controller is very simple. There are some key pieces of information to consider if you want to integrate your form widget with The Portal Connector
public class ColorPickerController : TpcFormWidgetController<ColorPickerModel>
The TpcFormWidgetController base class lets our engine know that this widget should be submitted to Dynamics CRM, and ensures that the controller has a model that is appropriate for submitting data to Dynamics CRM.
[ControllerToolboxItem(Name = "Color Picker", Title = "Color Picker", SectionName = "The Portal Connector", Toolbox = "FormControls")]
This attribute describes where to put the widget in the toolbox, in our example we put it in the FormControls toolbox under The Portal Connector section
The Model and View Model
The model represents the data required to render the widget and submit it to Dynamics CRM. The key pieces of data required to submit fields to CRM are present in the base class TpcFormFieldModel, namely:
- AttributeName – the name of the attribute this field is bound to
- AttributeType – the CRM data type of the selected attribute
Our designer will fill in these necessary fields automatically when you select the attribute.
public class ColorPickerModel : TpcFormFieldModel, IHideableWidget, IEditableField, IHasTitle
The rest of the fields we expose in our example model come from the interfaces we implement. These fields are added to implement Hide/Show, Read only and Title functionality to our widget frontend.
The view model is a representation of the model tailored for the current request. In our example we use the view model to pass only the information we need to the view, in other widgets the view model can contain data specific to the current request from the current user.
Again, with the view model, our base class is necessary to implement so that all the minimum requirements for rendering a form control are sent to the view.
public class ColorPickerViewModel : TpcFormWidgetViewModel
Properties in the view model can be marked with the [DataContract] attribute if you wish to access them in the JavaScript API, all other properties will not be serialized into the JavaScript model.
The View
The view is the Razor/HTML that is used to render the control. A Portal Connector view requires a few pieces of information in order for the Portal Connector JavaScript APIs to pick up the widget. Firstly, you need a container div that defines the role (type) of widget and also defines the widget id. We define these using data attributes.
<div id="@Html.GetUniqueId(Model.Name)_container" data-tpc-role="color-picker-container" data-tpc-id="@Model.MetaField.FieldName">
Secondly, if this widget needs to be submitted to our submission engine, you need an input. The input requires a name field that matches the Metafield FieldName and a role data attribute so the scripts can find the input.
<input class="form-control" id='@Html.GetUniqueId(Model.Name)_input' data-tpc-role="color-picker-input" name="@Model.MetaField.FieldName" value="@Model.Value" type="text" />
The designer view is a straightforward Sitefinity designer view, The Portal Connector adds no specific functionality. You can read more on designer views and how to create your own here.
The Scripts
The frontend script enables the widget to have a frontend JavaScript API as well as initializes all necessary kendo functionality with the configurations you selected in the designer. In this color picker example, we added the most basic form of our API including:
- hide/show
- enable/disable
- get/set value
- value changed events
The rest of the public JavaScript functions are getters and setters for the inputs/kendo functionality.
A key piece to ensure your widget is initialized and registered with The Portal Connector API would be the init function at the bottom of the file. This function loops through all of the color pickers on the page and registers them to our API.
tpc.$create(id, container, new ColorPicker(container, input, id));
The call to this $create function registers the widget to our API and creates a new ColorPicker JavaScript class with the information needed to render itself.
The designer JavaScript only has one piece of Portal Connector specific functionality, and that is how to get the attributes for the entity of the current form. The getAttributeOptions function runs at the start of the designer initialization and retrieves all attributes from the current entity of type “String” defined in the supportedAttributes member variable. These attributes are retrieved through a secure web service and subsequently populated into the attribute drop down using angular with ng-repeat.
Further Reading
A list of related articles are linked below for additional information on Sitefinity MVC widget creation:
If you have any comments, questions or concerns, please feel free to reach out to The Portal Connector team at support@crmportalconnector.com