05th November, 2014 by Nick Austin

How to create a dashboard control / link within Envisage.

1. Define your new control / link within the Database

For your control to be created, the first thing you need to do is too add your control to the database and assign it an ID. The table you need to add your control to is called: Dashboard_Plugins_List

Database Layout

As you can see this table consists of 5 columns, these columns represent:

ID

Unique ID assigned to the control

PluginID

The ID of the control we will refer to when building and saving the control, this does need to be unique and should be the next sequential number from the last control built

PluginName

The name of the control to be displayed within Envisage we selecting Dashboard controls

Type

Values: (Control or Link) Depending of what value you put here, we determine which column the control will display under the dashboard controls settings

Active

Values: (True or False) This will determine whether the control is visible for selection within the dashboard settings

 

Once all of the columns have been filled in for the control, you can save and close the database table.

2. Create the controls frontend

Now that we have defined our control, we need to create the code files for this control. The first thing you will need to do is to navigate to the ‘HomeDashboard\Plugins’ folder within Envisage. This folder can be found:

“\webroot\Envisage\Dashboards\HomeDashboard\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:

Site Folder Structure

As you can see from the image shown, within the plugin folder the is a folder named ‘_1’ this folder contains a control and has the same name as the ‘PluginID’ we created within the database in step 1.

To create our new control with the ‘PluginID’ 2, we need to create a new folder named ‘_2’.

The reason for this is that all controls need to be uniquely identified so they have the ability to be used in multiple panels within the dashboard, without interfering with each other.

RECOMMEND: We strongly recommend, for any new control, instead of creating the files and folders new and from scratch, that you take a copy of an already created control and copy / paste it back into the ‘Plugins’ folder.

This will create our plugins folder, but with the copied data. The next step we need to do is rename our new files to match our new control.

This will create our plugins folder; we now need to create our control. Again if you are using a code editor, we need to add a new ‘web form’, which will create our 2 files, frontend (.aspx) and backend (.aspx.cs).

Visual Studios Menu

Folder Names

Now that we have created our files, we need to update them and add some default code to them. The first file we are going to update is our backend file (.ascx.cs).

For our code to work we first need to include some references we will be using within the control:

using Envisage.CMS.Core.Editor;
using System.Data;

We no need to add our variables we will be using to store our control data in:

public string pluginid = "";
public string panelid = "";


No we have our references and variables, we need to append our ‘Page_Load’ method. This code is going to include a check to make sure we are a logged in user with an access code and the control values passed through to any saved control:

string accessCode = Request.QueryString["accessCode"].ToString();
EnvisageSite site = new EnvisageSite(0);
 if (site.ValidateAccessCode(accessCode)){
      if (Request.QueryString["pluginid"] != null)
     {
        pluginid = Request.QueryString["pluginid"].ToString();
     }
      if (Request.QueryString["panelid"] != null)
     {
        panelid = Request.QueryString["panelid"].ToString();
     }
     //Loading code will go here
 }

Now that we have got our page load sorted, we need to get check if there is a valued saved for our control. We are first going to check if our ‘panelid’ is a number and if so we will then query the database to get any saved values against both our panel and control: (this code will replace the comment above)

int _pluginid;
if (int.TryParse(pluginid, out _pluginid))
{   
    EnvisageHomeDashboard dashboard = new EnvisageHomeDashboard(accessCode);
    DataTable dt = dashboard.GetSavedData(panelID, _pluginid);
    if (dt.Rows.Count > 0)
    {
       foreach (DataRow row in dt.Rows)
       {
           if(row["Key"].ToString() == "SearchTerm")
           {
                string myvalue = row["Value"].ToString();
                if (myvalue != "")
                {
                     //do something
                     break;
                }
           }
      }
    }
    else
    {
         //no result do something
    }
}

This is the last lines of code were we need to replace the old reference with our new control.

  1. Creating the controls backend

Now that we have our control all setup and referenced correctly, we need to add in the methods to save and load our data every time the control is used.

Initial set up

The first thing we need to do is create the public variables to store are controls data. These include the ‘pluginid’ and the ‘panelid’, the code is as follows:

public string pluginid = "";
public string panelid = "";

The above variables are used to store the specific pluginid and the panelid we have used the control in. This data is saved to the database along with any values we custom set for the control. 

Loading the controls data

The page load is used to load the current users access code to verify them as a user, as well as getting any plugin and panel data for the control.

protected void Page_Load(object sender, EventArgs e)
        {
            if (Request.QueryString["accessCode"] != null)
            {
                string accessCode = Request.QueryString["accessCode"].ToString();
                EnvisageSite site = new EnvisageSite(0);
                if (site.ValidateAccessCode(accessCode))
                {
                    if (Request.QueryString["pluginid"] != null)
                    {
                        pluginid = Request.QueryString["pluginid"].ToString();                        
                    }

                    if (Request.QueryString["panelid"] != null)
                    {
                        panelid = Request.QueryString["panelid"].ToString();
                    }
                }
            }
        }

We have now created the backend for our control. Next thing to do is to create the controls frontend (.aspx).

The first thing we need to add is the JavaScript load function. The code below will need to be wrapped in script tags ‘<script></script> with a type set of type=”text/javascript”.

$(document).ready(function () {
 Load_RequestDashboardPanel_1 <%= panelid %> ();
 }); 
 function Load_RequestDashboardPanel_1 <%= panelid %> () {
 //Code will go here
 }
 
<a href="#" onclick="SaveMethod_<%= panelid %>(); return false;" class="input-group-
addon info">Click me</a>

Pressing this button will call the SaveMethod as shown below:

function SaveMethod_<%= panelid %>()
    {
        var PanelID = '<%= panelid %>';
        var PluginID = '<%= pluginid %>';

        if (search != "") {

            $.ajax({
                type: "POST",
                url: "../../api/EnvisageAPI.asmx/SaveDashboardData",
                data: JSON.stringify({
                    "pluginid": PluginID,
                    'accessCode': parent._editor.CurrentUser.AccessCode,
                    'PanelID': PanelID,
                    'Key': 'key',
                    'Value': 'value'
                }),
                contentType: "application/json; charset=utf-8",
                dataType: "json",
                async: false,
                success: function (data) {
                    LoadPanel(PanelID, PluginID);
                },
                failure: function (errMsg) {
                }
            });
        }
    }

As you can see from the above code, this is where we set our controls key and value that we get in the load event as shown previously. We also pass in the panel and plugin ids to make sure we are saving the correct control in the correct panel.

About author

Nick Austin

Hatched in the precarious heights of Luton's Milliner district. Nick left hat- making behind to become one the foremost .NET developers of his generation.

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

01202 555124 or hello@envisagecms.co.uk