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?

A server widget can have configurable parameters - options that are passed to a *.cshtml view as ViewBag properties or list of option view models. Options can be of these types: Text, Date, Integer, Float, Boolean. Default values can be set to options.

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

<p>Title is @ViewBag.WidgetTitle</p>

Or by using view model:

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

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

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