Create custom designer views

All widgets have designers where you configure widget properties. By default, widgets have two designer modes – simple and advanced. Simple mode is the simpler way to configure a widget. In the advanced mode, you configure individual properties of the widget.

You can add custom views to the widget designer by adding new template files and then adding the logic, or content, in the template files. Finally, you make the new view the default one.

To create a designer view template file:

In the ~/Mvc/Views/<WidgetName> folder, create a new template file, following the naming convention. For details, see Naming conventions.

For example, if you are creating a new view for the Content Block widget designer:

• Location of file: ~/Mvc/Views/ContentBlock
• Name of file: DesignerView.NewView.cshtml

Next, you add content to the template file. For example, you want to add simple text input in the new view of the designer and to allow the user to change the content of the Content Block through this new input. To do this, paste the following code line in the template file: 
<input ng-model="properties.Content.PropertyValue" type="text" />
As a result, you create a binding to a widget property of the Content Block widget named Content.

Once you run your project and open the widget designer, a new view with a text field appears. When you type in a value and save it, this value is displayed inside the Content Block widget. 

By default, the new designer view you created is not the default one you see when you open the designer. To change that, you need to create a  ~/Mvc/Views/[WidgetName]/DesignerView.[ViewName].json file. This file is used both for specifying the priority of your designer view and the custom component and script dependencies it has. 
For details on script dependencies, see Extend designers with client logic.

To make your designer view the default one, you set its priority to 1 (the highest priority). Your file should look similar to this:

The designer view configuration file specifies the view’s dependencies and configures whether the view is visible in the designer or through the More actions menu of the widget. The file uses JSON syntax. The file lists parameters and values that define the properties of the view.

RECOMMENDATION: We recommend that you have at least one designer view configured, even though none of the parameters are required.

You can leverage the reusable client components to implement your custom widget designer views.

IMPORTANT: Make sure you add the components to the array of components of the JSON file, otherwise the view will not load. 

In case some components, for example, input fields, require sanitization, you need to add the ngSanitize selector to the array of dependencies of the AngularJs controller.

Following is an example of a widget designer configuration file for a view named Simple. The file is named DesignerView.Simple.json after the naming conventions.

In the configuration file above:

• ”priority” is an integer number that defines the order, in which designer view in the widget designer are resolved. In this case, “priority” = 1 means that this view will be the default one. Designer views are ordered by priority in ascending order
• "hidden” – controls whether the designer view is visible via a tab in the widget designer. By default, the parameter value is false, so the view is visible as a tab page. If this designer view is hidden and the value of the parameter is true, you can access this designer view via adding a new widget menu command in the More options menu.
  For more information, see Add custom commands.
• “components” is an array of strings representing the client component names that are used in the designer view and for which script dependencies need to be loaded when opening the widget designer.
  For more information, see Use components to resolve script dependencies.
• “scripts” is an array of stings representing the paths of external scripts that need to be loaded in the designer view. For more information about how these paths are resolved, see Priorities for resolving assets.

You need to make sure the properties of the widget’s MVC controller CustomWidgetController.cs match the ones of the widget designer’s AngularJs controller CustomWidgetController.js. You do this by two-way binding these properties using the $watch functions. $watch functions are triggered when the value of the watched variable is changed. You usually use the $watch functions to intercept the change of a property, for example, when modifying the property value and before setting this value or before executing logic that depends on the new value.

If you are persisting a string in the MVC controller that represents a collection, for example, a collection of IDs, you use the $watch function in combination with the JSON.parse function:

To do the reverse - transform the collection back to a string representation to persist in the MVC controller, use a $watch function in combination with the JSON.stringify function:

You can enable the loading indicator during widget designer initialization to check whether there are any discrepancies in property bindings. You can thus get information about any errors. To do this, you use the $scope.feedback.showLoadingIndicator property.

Additionally, you can enable the display of error messages during widget designer initialization to provide you with information about property binding errors. You do this by using the $scope.feedback.errorMessage = data.Detail; expression. The data.Detail value contains the binding error information but you can also set other values to the $scope.feedback.errorMessage property in case custom initialization logic fails.

The following example demonstrates how to enable both options: