Developing Gadgets

Introduction

The dashboard is one of the features of EPiServer which is also a
plug-in area. Usages include presenting high-level information or provide quick
access to common tasks. This document is a tutorial for the creation of gadgets
for the dashboard.

OnlineCenter Overview

The main purpose of EPiServer OnlineCenter is to
allow easier navigation and integration of different products – EPiServer
or third-party. EPiServer OnlineCenter is made up of two main
components:

Global Navigation.
The global navigation helps users navigate different integrated products such as
EPiServer CMS, EPiServer Community, and EPiServer Mail but also third party
products or integrated modules which would like to expose their interfaces to
the logged on user. The global navigation can be customized, and it is
possible to insert the menu into both (custom) web forms and MVC views.
The menu is designed to be oriented on products and modules, so that each top
menu item represents a product while the sub-level menu contains the actual
views/functions/parts of the product.

Dashboard.
The main purposes of the dashboard are to aggregate site information and expose
important functions to the user. For example showing a list of recently changed
pages so that the editor quickly can get back to work where they left off.
The dashboard is made up of tabs, zones and gadgets. Gadgets can easily be
created (ASP.NET MVC) and plugged into the dashboard so that the user can use
them (add to dashboard). A gadget is a self-contained item and is responsible
for its own rendering and behavior. A gadget can either contain functionality
that can be used within the gadget interface or simple link away to other
products integrated in the framework (for example, a direct link to CMS /
Pages where you can use the classic editing mode features).

Setting Up the Environment

Start by installing an EPiServer CMS website using the standard installer.
Using the default options you will end up with a website in
c:\EPiServer\Sites\[MySiteName]. In the example below this site was installed in
c:\EPiServer\Sites\ExampleEPiServerSite4. While it is not required for normal
operation this tutorial assumes you have installed ASP.NET MVC.

Develop gadgets in separate project

The module is created as a separate project below the “public” folder
of the EPiServer site. As an alternative to creating a separate project you can
add you gadget to the existing PublicTemplatest project, please see the
Develop gadgets in public templates project
section for more information.

Add a unit test project if you
want. This tutorial will not cover unit testing.

When enabling Show all files, the quick chat
module is placed below the development site.

Modifications to default

Some modifications are recommended to the default MVC application.

1. Remove default controllers and views

Remove the default controllers, views and scripts (HomeController.cs,
/Views/Home, etc.) according to the image below. You can always use another
project to play with ASP.NET MVC. Note that if you have added a unit test
project you also have to remove all the related test functions from the
QuickChat.Test project.

2. Clean up web.config

The web configuration is inherited from the public templates site but if you
leave some settings in the module’s web.config you will kepp intellisense
enabled. Copy the root web.config file (not the one in the Views folder) from the QuickChat
example zip to your project.

3. Change output path

Open the QuickChat project’s properties and change the default build output path
of the quick chat project to "..\..\bin\".

4. Add references

Add references to
EPiServer.Shell and EPiServer.Data (you will need these later
on). You can find a copy of these in the public template’s bin folder.

5. Register module in web.config

Open the public templates’ web.config file and find the episerver.shell
configuration section. Add the quick chat module to the
/configuration/episerver.shell/modules/ path. This is an excerpt of the added
configuration:

CopyXML

<episerver.shell><publicModulesrootPath="~/modules/"autoDiscovery="Minimal"><!-- QuickChat is assumed to be located in ~/modules/QuickChat --><addname="QuickChat"><assemblies><addassembly="QuickChat"/></assemblies></add></publicModules>

Develop gadgets in public templates project

While creating gadgets in a separate project as described in the
Create gadgets in separate project section
often is a good approach, it is also possible create gadgets in the
PublicTemplates.csproj project by doing some modifications to configuration and
the csproj file.

1. Configuration

The Public Templates needs to be registered in the
configuration/episerver.shell/publicModules configuration section. The
resourcePath attribute tells the system to look for views (which are described
later in this document) in the folder /Views/[ControllerName]/[ActionName].ascx
instead of the default location below the modules folder. Also update the add
assembly section to any new name chosen for the public templates application.

2. References

3. Create Folders

The ASP.NET MVC framework suggests that you organize the code in the following folders,
add these to your project:

Controllers

Models

Views

4. Visual Studio Integration

ASP.NET MVC includes some wizards to help out in the task of creating
controllers and views. These are not enabled in the PublicTemplates.csproj
installed with EPiServer CMS but they can be with some manual tweaking of the
file. Right-click the project > Unload > Edit. Add
{603c0e0b-db56-11dc-be95-000d561079b0}; to the list of existing project
type guids. Save, right-click and select Reload Project.

The model represents another pillar of the MVC architecture. This describes the
data we interact with using the controller and show in our views.

Controller

Going back to the QuickChatController and use EPiServer.Data to retrieve
messages from the database (take a look at the EPiServer Framework Reference SDK
for in-depth information about the Dynamic Data Store):

CopyC#

[Gadget]
publicclass QuickChatController : Controller
{
// since the controller is created for each request// we can assign a store as a variablestatic QuickChatController()
{
DynamicDataStoreFactory.Instance.CreateStore(typeof(Message));
}
DynamicDataStore store =
DynamicDataStoreFactory.Instance.GetStore(typeof(Message));
public ActionResult Index()
{
// select all messages for the last 5 minutes
var fiveMinutesAgo = DateTime.Now.AddMinutes(-5);
var messages = from m in store.Items<Message>()
where m.Sent > fiveMinutesAgo
select m;
// pass the messages to the viewreturn View(messages.ToList());
}}

The code will select all recent messages and pass them to the “Index” view for
display.

Views

Create an MVC partial view in the quick chat project.

The wizard can be conjured by right-clicking in the controller action and
choosing “Add view” (requires ASP.NET MVC to be installed).

When the view is located in Views/QuickChat/Index.ascx in the quick chat project
it will be automatically selected to show the messages.

The new improvement of the view renders a form with a text input field and a
submit button. Since we used a “gadget form” the form will be serialized and
posted using jQuery.ajax. The results of the “Save” action will replace any
existing content in the gadget.

Taking care of posted messages in the controller

The controller accepts the posted message and stores it in the store. The view
that is returned will take the place of the existing view in the gadget area.
The mapping of the posted message string to input parameters is a feature of
ASP.NET MVC. Refer to the blogosphere for documentation on form posting
scenarios.

Gadget Development, step 3: Client side development

While server development is great it is what you do on the client that makes your
projects shine.
You may have noticed that the chat gadget at this point still is not very
interactive. While you get updates when refreshing the page, or posting messages
it is just sits there in between.

Defining resources

First of all is getting out on the dashboard with all the other gadgets. The
recommended way of doing this is using an attribute on the controller as shown below:

This will declare a JavaScript file located in the Content directory of the
quick chat module which will be loaded with the dashboard. The script is loaded
every time the dashboard is displayed, regardless if there are any quick chat
gadgets or not, so takes care to put stable code in the JavaScript file.

While the script is executed each time the dashboard loads the way to associate
with a gadget instance are client script init methods:

The init method is invoked by the dashboard and starts updating the gadget every
five seconds. While this represents an easy way to update the gadget regularly
it is not particularly suited for a chat since it will steal focus from the text
box.

Gadget development, step 4 - Styles and CSS

The best way to get your own style sheets out on the dashboard is defining them
for your gadget as in this snippet:

By using the attribute on the gadget controller and creating a
CSS file in the
Styles folder of your gadget project you can define styles specific to your
gadget. There are also shared styles you can use to get a consistent look and
feel. This is described in a later section of this document.

Tutorial Download

Further Information

Styling

The CSS styles used on the Dashboard resets many of the default styling of
elements added by the browser and in some cases adds an own default
style. This styling may however not be enough (it is rather non-styled) so to
the rescue comes some additional convenient classes. Documentation about styling
and the can be found in the
Developing for OnlineCenter document.

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: