05th November, 2014 by George Elliott

How to create a plugin.



To create a plugin to work within envisage we need to create 2 things.

     • Plugin Editor config

     • Plugin control

Plugin editor config

The plugin editor config is used for editing any of the settings that may be used to configure the plugin. An example of settings may be for a News plugin that can show news for a specific time period. The settings this plugin would have would be a start and end date.

The plugin editor above would be where the user can set and change these dates so that they can configure the plugin to work exactly as they want.


Plugin control

The plugin control is the plug in itself, the control that is going to site within the website and what the user is going to see when they visit the site. The control will take any setting saved in the editor and then can be used to manipulate the data as needed.

Creating the plugin

To create the plugin we need first start by creating the plugin folder structure. The plugin should be created under ‘/Plugins’ folder, which can be found in the webroot. This folder can be found:

“\webroot\Plugins”

If you are using a code editor like Visual Studio, then you can navigate to it from inside your webroot folder, the structure will look a little like this:

Folder Structure

Now you are within the plugin folder we need to create our plugin folder. The folder should be named in accordance with the plugin, we are going to create a plugin called ‘LatestNewsPanel’.

Inside our plugin folder we need to create our ‘editor’ folder. The new plugin structure should look like this:

Latest News Panel

Now that we have created our folder structure we need to create our editor and plugin files.

Creating the editor config file

To create the editor config you will need to create a ‘.aspx’ file within the editor folder. This will need to be named exactly the same as the plugin folder we created with the word ‘Config’ added to the end. In this instance the file will be called:

“LatestNewsPanelConfig.aspx”

Latest News Panel Config

Once we have created our editor file it will contain the code as below:

<%@ Page Language="C#" AutoEventWireup="true" CodeFile="LatestNewsPluginConfig.aspx.cs" Inherits="Plugins_LatestNewsPanel_editor_LatestNewsPluginConfig" %>





    


    
    

The next step is to copy some default code that is used in all envisage plugins. The code in the file below is the default code and this should replace any code that is automatically added to your .aspx config page you created.

ATTACH FILE WITH DEFAULT CODE IN!



Explaining the default code

Looking at your default code for the plugin, you will be able to see a few different things. Below is a brief description of the code you have copied into your editor config.

Line 5 – This is the title of your config

Lines 11 – 38 – This is the styling used for envisage and its plugins

Lines 40 – 47 – This is the code called when the plugin is first loaded, this is where we will call and set any custom settings we create for any plugins.

Lines 49 – 60 – This is the code used to save the plugin to the database, if we have any custom settings this is where it would be saved.

Lines 71 – 87 – This is the main html for the config, as default a message is displayed.

Lines 89 – 124 – The script used to run the editor config

Creating the plugin

Now that we have created our plugin editor, we need to create the plugin itself; this includes the front and back end of the plugin. The first thing we need to do is create the plugin files. The plugin files need to be created under the folder we created earlier, in this instance the ‘LatestNewsPanel’.

The plugin file type should be a user control (.ascx). The name of the plugin (for good naming convention) should have the same name as its containing folder, again in this instance ‘LatestNewsPanel.ascx’. Creating this you should have both the’ .ascx’ file and the ‘.ascx.cs’ file.

Plugin Location

Within the frontend file (.ascx) this is where you will put any html you wish to display to the user. As this is a .Net control you can use .Net controls within your front end and reference them from the backend file (.ascx.cs).

Configuring the backend

Now that we have all our files created, the last thing to do is to create the code behind. I have included below the code you will need to add to you code file to make it plugin ready and usable within Envisage.

Envisage references

using Envisage.CMS.Core.Plugins;
using Envisage.CMS.Core.Editor;
using Envisage.CMS.Core.Data;
using Envisage.CMS.Core;
using Envisage.Web.UI;

You will need to include the above reference so that the plugin can use the Envisage libraries.

Envisage control info

Above the plugins class, you will need to include the envisage control info, this is to let envisage know that this is a plugin and can be used within Envisage:

 
[ParseChildren(true), ToolboxData("<{0}:latestnewspanel runat="server">")]
[EnvisageControlInfo("LatestNewsPanel", "", "Latest News Widget", "news", "Envisage", true)]

The above code will need to be edited slightly to reference our new control.

The ‘ToolboxData’ will need to be changed to the name of your plugin, using the same naming convention as used for the folder and the plugin itself.

The ‘EnvisageControlInfo’ will also need to be edited for your own plugins data and settings. The parameters for this setting are as follows:

plugin4
public partial class Plugins_LatestNewsPanel_LatestNewsPanel : System.Web.UI.UserControl
This needs to be change to be an ‘EnvisageUserControl’
public partial class Plugins_LatestNewsPanel_LatestNewsPanel : EnvisageUserControl

About author

George Elliott

When he's not chained to a bit of code, George can be found with a guitar in his hand or running around a football pitch. He's also a big geography buff and confesses to once reading an atlas and encyclopaedia - cover to cover!

Comment
We are always here to help you. Don’t hesitate to contact us anytime!

01202 555124 or hello@envisagecms.co.uk