Widgets for Developers

In Better CMS there are two types of widgets:

• Content widgets (simple html content that can be used on multiple pages);
• Server widgets;

Content widgets are created via the Better CMS control panel. They are simple to create and function in a very similar way to content editing.

Server widgets are used for the website functionality that needs server side processing.

How to create server widget?

In the website project add partial view (*.cshtml) with the functionality that is needed - there is nothing special about such view, just mark that model is type of BetterCms.Module.Root.ViewModels.Cms.RenderWidgetViewModel and in the view it will be filled with CMS data.

@model BetterCms.Module.Root.ViewModels.Cms.RenderWidgetViewModel
@if (Model != null)
{
    <h2>Widget Name: @Model.Widget.Name</h2>
    <h3>Current Page: @Model.Page.PageUrl</h3>
    <p>Some widget content...</p>
}
else
{
    <p>Widget Preview...</p>
}

Tip: if you would like to add all your widget functionality in to the controller action, than in partial view just call RenderAction. Please, pay attention, that Area needs to be defined. For example if your action name is SomeAction and controller name is SomeController then you should add the following statement to your widget:

@{ Html.RenderAction("SomeAction", "Some", new {Area = ""}); }

If CMS information is needed in render action you are calling - pass the model to it:

@{ Html.RenderAction("SomeAction", "Some", new {Area = "", model = Model}); }

and add the parameter to the controller action:

[ChildActionOnly]
public ActionResult SomeAction(BetterCms.Module.Root.ViewModels.Cms.RenderWidgetViewModel model)
{
    // Do what ever is needed.
}

Tip: If you need custom fields in the widget model - derive from BetterCms.Module.Root.ViewModels.Cms.RenderWidgetViewModel and you'll get all the above functionality with custom type model.

How to add widget options?

The widgets can have configurable parameters - options (read more here).

If there is an option added to the widget (e.g. with option key "WidgetTitle") - in a *.cshtml view the value can be accessible by using view model:

@model BetterCms.Module.Root.ViewModels.Cms.RenderWidgetViewModel

foreach (var option in Model.Options)
{
    @option.Key: @option.Value
}

The options can be retrieved also by using view model's extension and specifying option's type (string / int / bool / etc):

@using BetterCms.Module.Root.Mvc.Helpers

@model BetterCms.Module.Root.ViewModels.Cms.RenderWidgetViewModel

@Model.GetOptionValue<string>("StringOption1")
@Model.GetOptionValue<int>("IntegerOption2")

HTML widget can retrieve widget options by using smart tags, as shown in the example below:

<p>Title is {{CmsWidgetOption:WidgetTitle}}</p>

How to register server widget?

Currently, there is no magic about template registration - just use front end functionality:

1. go to Widgets section in Site settings
2. click Register+
3. in Basic Properties input title and widget path
4. and in Widget Options tab register all the options with default values