Widgets for Developers (v1.x)

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

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

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

In the website project, add a partial view (*.cshtml) with the functionality that is needed. There is nothing special about this view, just mark that the model is BetterCms.Module.Root.ViewModels.Cms.RenderWidgetViewModel type, 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>
}

Note: if you would like to add all your widget functionality in to the controller action, than just call "RenderAction" in partial view. Please note that "Area" needs to be defined. For example, if your action name is "SomeAction" and your 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 the 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.
}

Note: 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 have configurable parameters - options (read more here).

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

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

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

The options can also be retrieved by using the view model's extension and specifying the 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 involved in 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 the "Widget Options" tab, register all the options with default values