Mari Jørgensen
Mar 20, 2012
  3208
(5 votes)

Developing EPiServer Gadgets

Recently I developed a couple of add-ons to an EPiServer project that were using EasySearch for handling search.
These add-ons included two new Gadgets - one for managing search synonyms and one for viewing the search log.


newgadgets                     The new gadgets

Here are a few useful tips that might come handy when creating EPiServer Gadgets.

Client script, ids and event binding

If you are used to JQuery you normally use static id’s to wire up events and such – typically something similar to this:

$(document).ready(function () {
            $("#myBtn").click(function () {
                alert("Hello world");
            });
        });
    

Lets say you have 3 radiobuttons inside your gadget, and you want to set up a client side event for the change event.

selectinterval

What the editor sees

<div id="interval">
  <%= Html.LabeledRadioButton("timeinterval", 
   string.Format(LanguageManager.Instance.Translate("/gadget/searchlog/option"), 
   "7"), "7", true, null, null)%>
  <%= Html.LabeledRadioButton("timeinterval", 
   string.Format(LanguageManager.Instance.Translate("/gadget/searchlog/option"), 
   "30"), "30", null, null)%>
 <%= Html.LabeledRadioButton("timeinterval", 
   string.Format(LanguageManager.Instance.Translate("/gadget/searchlog/option"), 
   "90"), "90", null, null)%>
</div>

The markup inside the view

<div id="interval">
<input id="id193" type="radio" value="7" name="timeinterval" checked="checked">
 <label for="id193">Last 7 days</label>
 <input id="id194" type="radio" value="30" name="timeinterval">
 <label for="id194">Last 30 days</label>
 <input id="id195" type="radio" value="90" name="timeinterval">
 <label for="id195">Last 90 days</label>
</div>

The rendered html
Since gadgets can have multiple instances present at the same time one cannot use static values for ids. The trick is to use the gadget instance object passed to the init method, and wire up your events inside the "epigadgetloaded” event. You can then use the gadget.element to get hold of the HTML DOM element for the gadget in question. 

(function ($) {
    easysearchsearchlog = {
        init: function (e, gadget) {
            // gadget.element gives us access to the gadget html dom element
 
            // Listen to the gadget loaded event to set up the change event
            $(this).bind("epigadgetloaded", function (e, gadgetInstance) {
 
                $("#interval select", gadget.element).change(function () {
                    var lang = $(this).val();
                    var time = $("#interval input:checked").val();
                    if (time == null)
                        time = "7";
                    gadget.loadView({ action: "Reload", timeInterval: time, language: lang });
                });
 
                $("#interval input", gadget.element).change(function () {
 
                    var time = $(this).val();
                    var lang = $("#interval select option:selected").val();
                    gadget.loadView({ action: "Reload", timeInterval: time, language: lang });
                });
            });
        }
    };
})(epiJQuery);

Use the [ScriptResource] attribute in combination with a ClientScriptInitMethod in the [Gadget] attribute to reference a script to be added to the dashboard and a method in this script to call for each gadget on a tab.

[Gadget(ResourceType = typeof(SearchLogController),
   ClientScriptInitMethod = "easysearchsearchlog.init",
   IconUrl = "Content/searchhistory.png",
    NameResourceKey = "GadgetName", DescriptionResourceKey = "GadgetDescription")]
 [EPiServer.Shell.Web.ScriptResource("Scripts/searchlog.js")]
public class SearchLogController : Controller

 

Note the use of html helper LabeledRadioButton to ensure input controls with corresponding labels.

Checklist: Playing nice on the dashboard

Making a gadget means sharing a common workspace with others. Take a moment to review this list before publishing your gadget to a wider audience:

  • “Namespace” your CSS classes
  • Namespace and encapsulate your JavaScript methods to avoid polluting global namespace
  • Don’t override other gadget’s styles
  • Don’t assume other gadgets will stay the same
  • Never assume there is only one gadget of your kind (affects element ids)
  • Prefer documented CSS classes for a consistent look and feel over time
  • Avoid long-running operations (such as reports or RSS operations) from your default action

Read more

OnlineCenter Developer Documentation
Gadgets – Developer Tutorial

Mar 20, 2012

Comments

Please login to comment.
Latest blogs
Plug-in manager is back in CMS 12

Plug-in manager is back in the UI, what is it and how can i use it?

Luc Gosso (MVP) | Oct 6, 2022 | Syndicated blog

Display Child Pages in Content Delivery API Response

The below example will implement an instance of IContentConverterProvider to customise the serialisation of PageData and output child pages in the...

Minesh Shah (Netcel) | Oct 4, 2022

Bring the Report Center back in Optimizely CMS 12

The Report Center has been a part of Optimizely CMS since its first debut in version 5R2 in 2008, but in CMS 12, it's removed! Don't despair! Make...

Tomas Hensrud Gulla | Oct 4, 2022 | Syndicated blog

Customizing Property Lists in Optimizely CMS

Generic property lists is a cool editorial feature that has gained a lot of popularity - in spite of still being unsupported (officially). But if y...

Allan Thraen | Oct 2, 2022 | Syndicated blog