Extending the Administration System with UI Plugins

Owned by Ben Herila
Last updated: Sept 04, 2012Version comment
4 min read

The UI plug-in system in N2 CMS allows developers to add modular functionality to the N2 backend administrative system simply through decorating types that they create with attributes. These types can then be identified and instantiated by the framework as needed. Some examples of plug-ins are shown below.

Toolbar Plugins

To register an interface into the management UI you add an attribute to your page, e.g.:

[ToolbarPlugin("EDIT", "edit", 
  "{ManagementUrl}/Content/Edit.aspx?{Selection.SelectedQueryKey}={selected}", 
  ToolbarArea.Preview, Targets.Preview, 
  "{ManagementUrl}/Resources/icons/page_edit.png", 
  50, 
  ToolTip = "edit",
  GlobalResourceClassName = "Toolbar", 
  RequiredPermission = Permission.Write)]

IPlugin

UI Plug-ins are classes that are decorated by an attribute that implements the N2.Plugin.IPlugin interface. This interface provides a Name and a SortOrder for the plug-in. It identifies the Type that is being Decorated by the attribute and it provides a method for checking if a User IsAuthorized to use this plug-in. The classes for the UI plug-in system are held in N2 assembly under the N2.Plugin namespace.

Finding UI Plug-ins

There is a service identified by the IPluginFinder interface that returns a list of all the UI plug-ins in the system that have been found. The default implementation of this service is the N2.Plugin.PluginFinder class. UI Plug-ins can be excluded from being found by adding elements to the interfacePlugins element in web.config:

N2 framework services can find and use UI plug-ins by calling into the IPluginFinder. For example in the Control Panel there is this method.

protected virtual void AddPluginsControlPanelState(state)
{
	var pluginPanel = new Panel();
	pluginPanel.CssClass = "plugins";
	Controls.AddPluginPanel();
	ContentItem start = Engine.Resolve<IUrlParser>().StartPage;
	ContentItem root = Engine.Persister.Repository.LoadEngine.Resolve<IHost>(.CurrentSite.RootItemID);
	foreach (IControlPanelPlugin plugin in Engine.Resolve<IPluginFinder>(.GetPlugins<IControlPanelPlugin>))
	{
		var span = new HtmlGenericControl("span";
		span.Attributes"class" = "control";
		pluginPanel.Controls.Addspan;
		plugin.AddTo(span, new PluginContext(CurrentItem, null, start, root, state,	Engine.ManagementPaths));
	}
}

This code has not been checked, would someone please review it and update this article? Thanks!



Here, the IPluginFinder is used to get all the control panel UI plug-ins, decorated by attributes deriving from IControlPanelPlugin. Each are then added to the pluginPanel control.

Backend Administration Plug-ins

The primary role of the UI Plug-in system is to add to the N2 CMS backend administration functionality. These UI plug-ins are identified by being decorated with attributes that derive from the AdministrativePluginAttribute. UI Plug-ins are automatically added to the Control Panel, Navigation Pane and Toolbars.
The attributes specify where the button or link will appear, both in terms of the toolbar area, for instance, and the sort order. Also they specify in what state the current page should be for this item to appear. For instance, Control Panel plugins can choose to be displayed during the states specified in the N2.Web.UI.WebControls.ControlPanelState enum:

  • Unknown
  • Hidden - The control panel is hidden, e.g. the user is not an editor
  • Visible - The control panel is visible displaying a page normally.
  • Editing - The control panel is displayed while editing the page in place.
  • DragDrop - The control panel is displayed during drag and drop of parts.
  • Previewing - The control panel is displayed while previewing an item version.

Control Panel

Pages that are decorated with attributes that implement the IControlPanelPlugin interface are added to the control panel. There are three of these attributes built in to N2 CMS: ControlPanelLinkAttribute, Control PanelDrapPluginAttribute and ControlPanelSeparatorAttribute. ControlPanelLinkAttribute adds a link to the control panel. ControlPanelSeparatorAttribute adds a separator to the control panel. ControlPanelDragPluginAttribute adds a link to the control panel that is shown only if there is a zone on the page being viewed.

Toolbar

The ToolbarPluginAttribute is used to decorate toolbar buttons that should appear in the toolbars of the administration area. The attribute defines things like the URL to which the button should link, a URL to an icon for the button, the frame and toolbar area in which the button should appear.

Navigation Pane

Pages that are decorated with attributes that derive from NavigationPluginAttribute are added to the right click context menu on the navigation page. There are two built-in attributes in N2 CMS: The NavigationLinkPluginAttribute adds a link to the decorated page in the context menu and NavigationSeparatorPluginAttribute adds a separator in the context menu.

Edit Toolbar

Pages that are decorated with the EditToolbarPluginAttribute appear in a toolbar on the Edit page of the administration

Other Plug-ins

In this section a selection of other plug-ins are described.

Scheduling

N2 has a scheduling service that executes work items on a scheduled basis. This functionality can be found in the N2.Plugin.Scheduling namespace of the N2 assembly.
Types that derive from ScheduledAction and decorated with the ScheduleExecutionAttribute are plug-ins that the Scheduler can find and execute. The scheduler uses a service called Heart that provides a regular beat event. When the beat event is triggered the Scheduler checks to see if any ScheduledAction plug-ins are due to be executed by interrogating their Interval, LastExecuted and Repeat properties.

N2.Templates Wiki Add-on

The Wiki add-on to the N2.Templates project, which can be found in the N2.Addons.Wiki namespace of the Wiki assembly, uses UI plug-ins to provide user controls that may be used in the text of a wiki article.
These user controls must derive from WikiTemplate and be decorated with attributes that implement the IWikiTemplateRenderer interface. There are two built in attributes: WikiTemplateAttribute or the DefaultWikiTemplateAttribute, which just assumes that the template files are found in the folder '~/Wiki/UI/WikiTemplates'.
The wiki add-on uses built-in renderers, found in the N2.Addons.Wiki.Renderers namespace, to convert the wiki text into HTML. In this case there is a TemplateRenderer that lookups up the template renderer plug-in user control based. It is instantiated with this code:
Renderers"Template" = new
TemplateRenderer(pluginFinder.GetPlugins<ITemplateRenderer>());

As an example, if a wiki article contained "LatestArticles". That text will be converted into an instance of the LatestArticles.ascx user control.