This blog post provides brief technical information about Add-On Store in EPiServer 7 Preview and describes the process of developing simple add-on step by step.
Meet the Add-On Store
Add-on Store is the new approach to create, distribute, share and manage modules for EPiServer based sites.
For site owners and administrators Add-On Store is the one place where they can find, install and manage required add-ons to bring new features and tools for site visitors and editors.
For EPiServer partners and developers Add-On Store means the standard way to create and distribute modules, plug-ins and extensions for EPiServer sites.
And we use this technology ourselves. It may be worth mentioning that new Edit UI and UI Platform in EPiServer 7 Preview are add-ons. Add-On system itself is implemented as add-ons. It proves that add-ons can be really powerful.
Go ahead, download EPiServer 7 Preview and see it in action.
Add-ons from developer point of view
Please look at the documentation for add-on developers in EPiServer Framework SDK Knowledge Base to get more information, technical details and things that should be kept in mind when you are developing add-on.
What can be an add-on
Technically add-on is a Shell module that is distributed as NuGet package and can be installed, updated and removed using Add-On Store interface on EPiServer 7 site. Each add-on resides in the one directory.
Add-on provides new functionality and extensions for EPiServer sites: various plug-ins, scheduled jobs, gadgets, Editing UI components, data stores, typed pages, blocks, templates and so on.
Configuration file changes are not supported in this version. I’m not sure if it is good idea to make it possible in the future.
Initialization and extension point
It is possible to implement specific initialization for add-on components and execute custom code when add-on is installed, updated or removed.
Public, protected and system add-ons
Public add-ons provide functionality for the public site.
Protected add-ons usually bring features for site administrators and editors and contain resources that should not be available publicly.
System add-ons are important system modules that cannot be removed, but can be updated. Usually it is EPiServer add-ons that are distributed with the platform and deployed on each new web site. For example: new Editing Interface in EPiServer 7 Preview.
Add-on prerequisites and dependencies
Dependencies are the list of other add-ons that should be installed on the site. The system makes sure that you will not break any installed add-ons by updating or removing related packages. Dependencies are installed and upgraded automatically if possible.
Add-on system allows installing only those add-ons that are compatible with your environment.
Prerequisites are dependencies to the products that are not installed as add-ons. For example, you probably would define EPiServer Community as prerequisite for the add-on that provides some new great widgets to manage Community entities.
Sample add-on: Sharing Widget
This sample add-on makes it easy for site visitors to share the content using ShareThis widget which allows to recommend things in tons of social networks and communities.
To try something new sharing widget is implemented as shared block that can be simply dropped on the site pages in new EPiServer 7 Edit UI.
Getting ShareThis widget code
Go to ShareThis site and generate default widget with small buttons for generic web site and pick 4 favorite social networks: Twitter, Facebook, Google+ and LinkedIn. All other communities will be available through ShareThis option.
You will be prompted to register in order to get Publisher ID. Using this account you can access a set of analytic tools to understand sharing behavior. It’s possible to skip the registration and just get a code, in this case you still get some Publisher ID but you don’t have access to analytics. Make sure that ShareThis terms of service and privacy policy are fine with you.
Save generated code on the last step for further use:
<span class='st_twitter' displayText='Tweet'></span>
<span class='st_facebook' displayText='Facebook'></span>
<span class='st_googleplus' displayText='Google +'></span>
<span class='st_linkedin' displayText='LinkedIn'></span>
<span class='st_sharethis' displayText='ShareThis'></span>
<script type="text/javascript">var switchTo5x=true;</script>
<script type="text/javascript" src="http://w.sharethis.com/button/buttons.js"></script>
<script type="text/javascript">stLight.options({publisher: "Your-Publisher-ID"}); </script>
Creating add-on project
Create new ASP.NET Empty Web Application project using Visual Studio. You can remove web.config file in the project root and the most of default references.
References to the following assemblies need to be added:
- EPiServer
- EPiServer.BaseLibrary
- EPiServer.Data
- EPiServer.Shell
- System.ComponentModel.DataAnnotations
- System.Web.Mvc
Hopefully, platform binaries will be available in the EPiServer NuGet feed after EPiServer 7 release and it will be possible to reference corresponding NuGet package. Right now you can just create Dependencies directory in the solution folder and copy referenced EPiServer assemblies.
Adding block type
Create BlockTypes folder inside your project and add new class SharingWidgetBlock:
ContentType(DisplayName = "Sharing Widget Block",
Description = "Adds ShareThis widget on pages where block is placed.")]
public class SharingWidgetBlock : BlockData
{
[Display(Name = "Publisher ID",
Description = "Register on ShareThis.com to get your Publisher ID.")]
[Required]
public virtual string PublisherID { get; set; }
}
EPiServer.DataAnnotations.ContentTypeAttribute is applied to mark the content type and define the name and description that are displayed when this block type is listed in Admin mode.
EPiServer.Core.BlockData class provides the base implementation for all block types.
PublisherID property is the only one setting for sharing widget block and it is marked as required. DisplayAttribute is used to define property name and description that will appear in EPiServer Edit and Admin mode.
Implementing block rendering
EPiServer 7 Preview brings full MVC support and the great thing here is that you can have Web Forms and MVC working side by side.
Obviously your add-on is going to be so awesome that most of EPiServer site owners will dream about installing it on their EPiServer 7 sites, right? Of course it should support both Web Forms and MVC!
Web Forms control
Add Blocks sub folder in the project and create new user control SharingWidget.ascx.
Change control code-behind file and inherit BlockControlBase<SharingWidgetBlock> which is the base class for user controls that renders block data:
public partial class SharingWidget : BlockControlBase<SharingWidgetBlock>
{
}
Add ShareThis widget code to control markup.
Note that add-on assembly is referenced in the Control directive. This is required since add-on binaries are not placed to site bin folder and will be loaded from probing path.
<%@ Control Language="C#" AutoEventWireup="false" CodeBehind="SharingWidget.ascx.cs"
Inherits="EPiServer.Samples.SharingWidget.Blocks.SharingWidget, EPiServer.Samples.SharingWidget" %>
<script type="text/javascript"> var switchTo5x = true;</script>
<script type="text/javascript" src="http://w.sharethis.com/button/buttons.js"></script>
<script type="text/javascript"> stLight.options({ publisher: "<%= CurrentBlock.PublisherID %>" }); </script>
<span class='st_twitter' displayText='Tweet'></span>
<span class='st_facebook' displayText='Facebook'></span>
<span class='st_googleplus' displayText='Google +'></span>
<span class='st_linkedin' displayText='LinkedIn'></span>
<span class='st_sharethis' displayText='ShareThis'></span>
CurrentBlock property is used to access block instance that is being rendered by this user control and set publisher ID widget parameter.
MVC block rendering
Model
You already have it: SharingWidgetBlock is the model.
View
Add standard Views folder in the project. Create SharingWidget sub folder and add SharingWidget.cshtml partial view. It follows naming conventions for MVC views, however it is not really important in this particular case.
SharingWidget.cshtml view code looks like this:
@model EPiServer.Samples.SharingWidget.BlockTypes.SharingWidgetBlock
<script type="text/javascript"> var switchTo5x = true;</script>
<script type="text/javascript" src="http://w.sharethis.com/button/buttons.js"></script>
<script type="text/javascript"> stLight.options({ publisher: "@Model.PublisherID" }); </script>
<span class='st_twitter' displayText='Tweet'></span>
<span class='st_facebook' displayText='Facebook'></span>
<span class='st_googleplus' displayText='Google +'></span>
<span class='st_linkedin' displayText='LinkedIn'></span>
<span class='st_sharethis' displayText='ShareThis'></span>
As you can see, it uses Razor syntax to output publisher ID and contains the same HTML as user control.
To make it work add web.config file to the Views folder. It configures Razor engine and makes add-on assembly and namespace available in the views as follows:
<?xml version="1.0"?>
<configuration>
<configSections>
<sectionGroup name="system.web.webPages.razor" type="System.Web.WebPages.Razor.Configuration.RazorWebSectionGroup, System.Web.WebPages.Razor, Version=2.0.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35">
<section name="host" type="System.Web.WebPages.Razor.Configuration.HostSection, System.Web.WebPages.Razor, Version=2.0.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35" requirePermission="false" />
<section name="pages" type="System.Web.WebPages.Razor.Configuration.RazorPagesSection, System.Web.WebPages.Razor, Version=2.0.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35" requirePermission="false" />
</sectionGroup>
</configSections>
<system.web.webPages.razor>
<host factoryType="System.Web.Mvc.MvcWebRazorHostFactory, System.Web.Mvc, Version=4.0.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35" />
<pages pageBaseType="System.Web.Mvc.WebViewPage">
<namespaces>
<add namespace="EPiServer.Samples.SharingWidget" />
</namespaces>
</pages>
</system.web.webPages.razor>
<system.web>
<compilation>
<assemblies>
<add assembly="EPiServer.Samples.SharingWidget" />
</assemblies>
</compilation>
</system.web>
</configuration>
Controller
Create controller responsible for block data rendering:
public class SharingWidgetController : BlockController<SharingWidgetBlock>
{
public override ActionResult Index(SharingWidgetBlock blockData)
{
return PartialView(Paths.ToResource(this.GetType(),
"Views/SharingWidget/SharingWidget.cshtml"), blockData);
}
}
There is a tiny trick to provide required view file.
BlockController<T> is the base class for block rendering controllers. Index method of base controller returns action result for partial view with the name equal to block type name. Then the system tries to find partial view in a folder structure according to the block namespace.
Search paths for EPiServer.Samples.SharingWidget.BlockTypes.SharingWidgetBlock type would be as follows:
~/Views/SharingWidget/SharingWidgetBlock.aspx ~/Views/SharingWidget/SharingWidgetBlock.ascx ~/Views/Shared/SharingWidgetBlock.aspx ~/Views/Shared/SharingWidgetBlock.ascx ~/Views/SharingWidget/SharingWidgetBlock.cshtml ~/Views/SharingWidget/SharingWidgetBlock.vbhtml ~/Views/Shared/SharingWidgetBlock.cshtml ~/Views/Shared/SharingWidgetBlock.vbhtml /Util/Views/Shared/SharingWidgetBlock.ascx /Util/Views/Shared/DisplayTemplates/SharingWidgetBlock.ascx /Util/Views/Shared/EditorTemplates/SharingWidgetBlock.ascx /EPiServer/CMS/Views/Shared/SharingWidgetBlock.ascx /EPiServer/CMS/Views/Shared/DisplayTemplates/SharingWidgetBlock.ascx /EPiServer/CMS/Views/Shared/EditorTemplates/SharingWidgetBlock.ascx
Most probably add-on view file will not be found in these folders, so the system needs some help to locate it.
The path to the directory where add-on is installed depends on packaging configuration and add-on developer should never hardcode absolute and concrete paths. Full paths to add-on resources like scripts, styles and views should be resolved from the path relative to the add-on directory. EPiServer.Shell.Paths class provides the bunch of methods to resolve path to resources located in the corresponding add-on folder. Add-on can be identified by name, by assembly or by type from add-on assembly.
Controller for sharing widget block overrides default Index method to resolve the view path using partial path in add-on directory.
Intermediate results
You have implemented block type, Web Forms and MVC rendering templates and this code can be deployed as Shell module on the site.
I agree, it’s nasty to have that script tags in both markups; you get several script includes if there are several controls/views rendered on the page. But don’t worry about it too much. Probably you won’t have several sharing widgets on page unless your site looks like this.
And of course it would be nice to make the style of the widget and the list of available buttons configurable. Again, keep it simple for the version one.
Creating add-on package
To turn the module into an add-on you need to create a NuGet package that contains add-on assemblies and resources.
Download NuGet command line or Package explorer from NuGet CodePlex.
There are several approaches to creating a NuGet package. Creating a package from a project looks like the easiest way for this simple add-on.
Creating package manifest file
Run following command in the directory where the .csproj file is:
nuget spec
It creates NuGet .nuspec manifest file for add-on package. Manifest file can be included to the project for convenience.
Package metadata
Edit .nuspec file, add basic metadata like add-on title, description, tags, icon URL etc.
Note that it contains replacement token $id$, $version$ and $author$ that are going to be replaced by assembly name, version and author when NuGet builds the package:
<?xml version="1.0"?>
<package >
<metadata>
<id>$id$</id>
<title>Sharing Wigdet</title>
<version>$version$</version>
<authors>$author$</authors>
<owners>$author$</owners>
<projectUrl>https://github.com/dmytroduk/SharingWidgetAddOn</projectUrl>
<iconUrl>http://w.sharethis.com/images/sharethis_32.png</iconUrl>
<requireLicenseAcceptance>false</requireLicenseAcceptance>
<description>Enables site visitors to share the content in social networks and communities using ShareThis.com widget.</description>
<tags>EPiServerPublicModulePackage Social Sharing ShareThis</tags>
<dependencies>
<dependency id="EPiServer" version="[7.0,8.0)" />
</dependencies>
</metadata>
</package>
Public or protected add-on
It’s required to add one of the special tags to indicate that this is add-on package for EPiServer based site:
EPiServerPublicModulePackage– this tag should be added for public add-onsEPiServerModulePackage– should be added in the tag list of protected add-ons
EPiServerPublicModulePackage tag is more suitable for this add-on since sharing widget should be available for all site visitors.
Dependencies and prerequisites
Sharing Widget add-on does not depend on any other add-on, so you could skip dependencies list.
However, it can be used to set add-on prerequisites. Define that this add-on requires any version of EPiServer CMS 7. Add dependency with id equal to EPiServer core assembly name and version range from 7 (including) to 8 (excluding). Add-on system will check if corresponding assembly is loaded in site app domain.
Building the package
Build the project.
Run following command to create the package from the add-on project:
nuget pack EPiServer.Samples.SharingWidget.csproj
It creates add-on package EPiServer.Samples.SharingWidget.1.0.0.0.nupkg that is ready to be installed.
Installing Sharing Widget add-on
Login to EPiServer 7 Preview site as administrator and navigate to Add-Ons section.
Sharing Widget add-on is not published in the central EPiServer Store (yet!), you have to upload package file to install it on site. Click on “Manual Upload” button, select package file and press Install. You will be prompted to restart the site to finish the installation.
After successful installation Sharing Widget add-on should be displayed in installed section. You can remove it any time (why would you?) by clicking on Uninstall button in detailed view.
Using add-on widget
Creating shared block
Navigate to new shiny Edit UI. Make sure that you have Shared Blocks widget in the right panel. Create new Sharing Widget block, specify your publisher ID and publish.
Placing widget on pages
Drag Shared Widget block and drop it on the appropriate content area. Publish the page.
Check out that sharing widget works both on Web Forms and MVC site:
Source code
Source code is available on GitHub, you are more than welcome to download or fork. Add-on package can be downloaded here.
Try it!
Hopefully the above example would encourage you to start developing your add-ons right now and make new great things.
Your feedback is highly appreciated and would help to make add-on system and EPiServer 7 better.
Updated
Add-on was rebuilt for EPiServer 7 RTM, you can find more information here.