Optionally provide private feedback to help us improve this article...

Thank you for your feedback!


Adding Plug-Ins to InstantForum pages

By default InstantForum will attempt to inject your plug-in user control to the end of the containing pages control collection. This control injection is handled by the InstantASP.Common.UI.Base.Plugin class.

This works well for plug-ins that don't render any UI however if you wanted to inject your plug-ins into specific locations or pages within InstantForum.NET you'll need to implement some code to handle this within your plug-in. This article provides a number of examples showing how to load plug-ins into specific locations & also how to complete replacing existing forum controls with your own plug-in.

Our InstantASP.Common.UI.Base.Plugin class provides several methods you can use to add plug-ins to specific locations within a InstantForum.NET page. These methods are…

  • AddControlBeforeType
  • AddControlAfterType
  • AddControlBeforeID
  • AddControlAfterID

We would suggest adding your plug-in to the pages control collection within the "OnPluginLoad" event. If your handling the injection of plug-ins within your plug-in code you may wish to set the "AutoAddControl" proprty of your plug-in to false within the constructor as shown below…

public New()
{
// setup plugin details
this.Name = "Custom Registration Form";
this.Author = "InstantASP Ltd";
this.PluginFileName = "~/Plugins/CustomRegistration.ascx";
this.AutoAddControl = false;

}

If you don't explicitly set "AutoAddControl" to false our plug-in framework will always attempt to automatically inject your plug-in at the end of the pages control collection.

Adding the Hello World Plug-In to specific locations

To demonstrate how you would use these methods within your plug-in to add your plug-ins user control to a specific location please see the examples below.

Add plug-ins after the header

You can see our Hello World example positioned just below the header control below…

The code to achieve this is shown below…

 namespace InstantForum.Plugins
{

public class HelloWorld : InstantASP.Common.UI.Base.Plugin, InstantASP.Common.Plugins.IPlugin
{

protected System.Web.UI.WebControls.Label lblHelloWorld;

public HelloWorld()
{
// setup plugin name
this.Name = "Hello World Sample Plugin";
// optional author information
this.Author = "InstantASP Ltd";
// the location of our user control from the web applications root
this.PluginFileName = "~/Plugins/HelloWorld.ascx";
}

// method to setup controls within plugins ascx file
protected override void InitializePlugin(System.Web.UI.Control ctlSkin)
{
// find the label control within our plugins .ascx file
lblHelloWorld = (System.Web.UI.WebControls.Label)ctlSkin.FindControl("lblHelloWorld");
// update the text if we found the control
if ((lblHelloWorld != null)) {
lblHelloWorld.Text = "Hello World!";
}
}

public void OnPluginInit(InstantASP.Common.Plugins.IPluginContext context)
{
base.OnPluginInit(context);
}

public void OnPluginLoad(InstantASP.Common.Plugins.IPluginContext context)
{
// add our label just after the header control
if ((lblHelloWorld != null)) {
base.AddControlAfterType(context.Page, lblHelloWorld, typeof(InstantASP.InstantForum.UI.Controls.Header));
}
base.OnPluginLoad(context);
}

public void OnPluginPreRender(InstantASP.Common.Plugins.IPluginContext context)
{
base.OnPluginPreRender(context);
}

public void OnPluginRender(System.Web.UI.HtmlTextWriter writer, InstantASP.Common.Plugins.IPluginContext context)
{
base.OnPluginRender(writer, context);
}

}

}

 Here we use the AddControlAfterType method within the OnPluginLoad event to add our plug-in to the forum page. We set-up our plug-in label as normal within the InitializePlugin however the label is now a class level variable and we can dynamically add this to the pages control collection within the OnPluginLoad event.

The AddControlAfterType method accepts three arguments. The first is the System.Web.UI.Page you wish to add the control to, the section is the actual control you wish to add and the third is the type of control we should inject after within the existing pages control collection.

Adding the Hello World Plug-in to specific pages

The example below shows how to customize your plug-in to ensure it only appears on a specific page within InstantForum . In this example we'll use our Who’s Online page. First we search for our Who's On control and if found we inject additional controls into the page. If we don't find the Who's On control it's safe to assume we are not on our Who's Online page and we simply set the plug-ins visible property to false to ensure it does not appear on other InstantForum pages...

public void OnPluginLoad(InstantASP.Common.Plugins.IPluginContext context)
{
// try to find whos online control
InstantASP.InstantForum.UI.Controls.ViewWhosOn WhosOncontrol = (InstantASP.InstantForum.UI.Controls.ViewWhosOn)base.FindControlByType(context.Page, typeof(InstantASP.InstantForum.UI.Controls.ViewWhosOn));
// did we find the ViewWhosOn control?
if ((WhosOncontrol != null)) {
// if so add our hello world lable below header
base.AddControlAfterType(context.Page, lblHelloWorld, typeof(InstantASP.InstantForum.UI.Controls.Header));
} else {
// else hide the plug-in Me.Visible = False
}
base.OnPluginLoad(context);

}

You can also use the page name to conditionally display inject plug-ins. For example...

public void OnPluginLoad(InstantASP.Common.Plugins.IPluginContext context)
{
if (context.Page.Request.RawUrl.ToLower.IndexOf("somepage.aspx") >= 0) {
// add your plug-in
} else {
// else hide your plug-in 
}

}

Replacing InstantForum controls with your custom Plug-Ins

You may wish to replace our standard registration form with your own user control to accommodate for uniuqe data you may need to capture during registration. Our CustomRegistrationForm plug-in shows how to do this...



As you can see this replaces the InstantForum standard registration form with your own unique custom registration code. Using plug-ins to-do this ensures you can easily update InstantForum as we offer new updates without having to add your custom changes upon each release.

The code below shows how you would replace our registration form with your custom plug-in at run-time

namespace InstantForum.Plugins
{

public class CustomRegistration : InstantASP.InstantForum.UI.Base.Plugin, InstantASP.Common.Plugins.IPlugin
{

protected InstantASP.Common.UI.WebControls.PanelBar ctlPanelBar;

public CustomRegistration()
{
// setup plugin details
this.Name = "Custom Registration Form";
this.Author = "InstantASP Ltd";
this.PluginFileName = "~/Plugins/CustomRegistration.ascx";
// don't auto inject
this.AutoAddControl = false;
}

// method to setup controls within plugins ascx file
protected override void InitializePlugin(System.Web.UI.Control ctlSkin)
{

// setup plugin controls
ctlPanelBar = (InstantASP.Common.UI.WebControls.PanelBar)ctlSkin.FindControl("ctlPanelBar");
ctlPanelBar.CurrentSkin = base.CurrentContext.InstallURL + base.CurrentContext.CurrentSkin;

}

public void OnPluginInit(InstantASP.Common.Plugins.IPluginContext context)
{
base.OnPluginInit(context);
}

public void OnPluginLoad(InstantASP.Common.Plugins.IPluginContext context)
{

// search for our registration control in the form
InstantASP.InstantForum.UI.Controls.Register Register = (InstantASP.InstantForum.UI.Controls.Register)base.FindControlByType(context.Page, typeof(InstantASP.InstantForum.UI.Controls.Register));

// remove spacers from register control
if ((Register != null)) {
for (Int32 intCount = 0; intCount <= Register.Controls.Count - 1; intCount++) {
if (Register.Controls.Item(intCount) is InstantASP.Common.UI.WebControls.Spacer) {
Register.Controls.Item(intCount).Visible = false;
}
}
}

// search for our registration control in the form
InstantASP.InstantForum.UI.Controls.RegistrationForm RegistrationForm = (InstantASP.InstantForum.UI.Controls.RegistrationForm)base.FindControlByType(context.Page, typeof(InstantASP.InstantForum.UI.Controls.RegistrationForm));

// did we find the registration form?

if ((RegistrationForm != null)) {

// create a panel for our custom form
System.Web.UI.WebControls.Panel pnl = new System.Web.UI.WebControls.Panel();
pnl.Style.Add("float", "left");
pnl.Style.Add("width", "100%");
pnl.Controls.Add(new InstantASP.Common.UI.WebControls.Spacer());
pnl.Controls.Add(ctlPanelBar);
pnl.Controls.Add(new InstantASP.Common.UI.WebControls.Spacer());

// add our panel just after the header
base.AddControlAfterType(context.Page, pnl, typeof(InstantASP.InstantForum.UI.Controls.Header));

// hide the original registration form
RegistrationForm.Visible = false;

}

base.OnPluginLoad(context);

}

public void OnPluginPreRender(InstantASP.Common.Plugins.IPluginContext context)
{
base.OnPluginPreRender(context);
}

public void OnPluginRender(System.Web.UI.HtmlTextWriter writer, InstantASP.Common.Plugins.IPluginContext context)
{
base.OnPluginRender(writer, context);
}

}

}

 In the example above we set-up our plug-in coronals (textboxes, panelbar etc) as normal within the InitializePlugin method. The magic for this example happens within the OnPlugInLoad event. Within this event we search the page for our standard registration form. If we find the InstantForumregistration form we dynamically build up a new System.Web.UI.WebControls.Panel control which we'll render to the page. The Panel allows use to add additional formatting & spacing to the page.

We add our "PanelBar" control which contains our custom registration form to the Panel and finally add the Panel containing our controls to the pages control collection just after the header using the code…

 base.AddControlAfterType(context.Page, pnl, typeof(InstantASP.InstantForum.UI.Controls.Header))

The last step is hide our standard registration form and you can do this as normal using…

RegistrationForm.Visible = false;

Reformatting Page Layout Using Plug-Ins

If you wish to align plug-ins within the InstantForum UI you can re-arrange the InstantForum UI from within your plug-in. For example our Google Maps plug-in adds a new Google Map to the right of the Who's Online list showing active online members…

The code to achieve this can be seen below...

 namespace InstantForum.Plugins
{

public class WhosOnMap : InstantASP.InstantForum.UI.Base.Plugin, InstantASP.Common.Plugins.IPlugin
{

protected InstantASP.Common.UI.WebControls.PanelBar ctlPanelBar;
protected System.Web.UI.HtmlControls.HtmlGenericControl map_canvas;

InstantASP.InstantForum.UI.Controls.ViewWhosOn WhosOnControl;

public WhosOnMap()
{
// setup plugin details
this.Name = "Google Map Whos Online Plugin";
this.Author = "InstantASP Ltd";
this.PluginFileName = "~/Plugins/WhosOnMap.ascx";
}

// method to setup controls within plugins ascx file
protected override void InitializePlugin(System.Web.UI.Control ctlSkin)
{
// setup panelbar control
ctlPanelBar = (InstantASP.Common.UI.WebControls.PanelBar)ctlSkin.FindControl("ctlPanelBar");
ctlPanelBar.CurrentSkin = base.CurrentContext.InstallURL + base.CurrentContext.CurrentSkin;
}

public void OnPluginInit(InstantASP.Common.Plugins.IPluginContext context)
{
base.OnPluginInit(context);
}

public void OnPluginLoad(InstantASP.Common.Plugins.IPluginContext context)
{

// register plug-in css
RegisterClientCss(base.CurrentContext.InstallURL + "PlugIns/WhosOnMap/WhosOnMap.css", context.Page.Header);
// find whos on control on forum page
WhosOnControl = (InstantASP.InstantForum.UI.Controls.ViewWhosOn)base.FindControlByType(context.Page, typeof(InstantASP.InstantForum.UI.Controls.ViewWhosOn));

// did we find the whos on control?
if ((WhosOnControl != null)) {

// reset whos on control
WhosOnControl.PageSize = 10;

// create a panel for our custom layout
System.Web.UI.WebControls.Panel pnl = new System.Web.UI.WebControls.Panel();
pnl.CssClass = "whosonmap";

System.Web.UI.WebControls.Panel pnlLeft = new System.Web.UI.WebControls.Panel();
pnlLeft.CssClass = "whosonmapleft";
pnlLeft.Controls.Add(WhosOnControl);

System.Web.UI.WebControls.Panel pnlRight = new System.Web.UI.WebControls.Panel();
pnlRight.CssClass = "whosonmapright";
pnlRight.Controls.Add(ctlPanelBar);

pnl.Controls.Add(new InstantASP.Common.UI.WebControls.Spacer());
pnl.Controls.Add(pnlLeft);
pnl.Controls.Add(pnlRight);
pnl.Controls.Add(new InstantASP.Common.UI.WebControls.Spacer());

// add our panel just after the header
base.AddControlAfterType(context.Page, pnl, typeof(InstantASP.InstantForum.UI.Controls.Header));

} else {

ctlPanelBar.Visible = false;
this.Visible = false;

}

base.OnPluginLoad(context);

}

public void OnPluginPreRender(InstantASP.Common.Plugins.IPluginContext context)
{

// bind data to google map, do this in prerender so we have correct clientids
if (!context.Page.IsPostBack & (WhosOnControl != null)) {
Binddata(context.Page);
}
base.OnPluginPreRender(context);

}

public void OnPluginRender(System.Web.UI.HtmlTextWriter writer, InstantASP.Common.Plugins.IPluginContext context)
{
base.OnPluginRender(writer, context);
}

private void Binddata(System.Web.UI.Page objPage)
{
// bind data code here
}

private void RegisterClientCss(string strAbsolutePath, System.Web.UI.HtmlControls.HtmlHead ctlHeader)
{

System.Web.UI.HtmlControls.HtmlLink HtmlLink = new System.Web.UI.HtmlControls.HtmlLink();
HtmlLink.Attributes.Add("href", strAbsolutePath);
HtmlLink.Attributes.Add("rel", "stylesheet");
HtmlLink.Attributes.Add("type", "text/css");
if ((ctlHeader != null)) {
ctlHeader.Controls.Add(HtmlLink);
}

}

}

}

 Here we set-up the plug-in as usual within the InitializePlugin method. Our top level control here is the PanelBar control containing the map so we add this to a class level variable. This allows us to later add this to the pages control collection within the page level events exposed by the InstantASP.Common.Plugins.Iplugin interface. 

The magic here happens within the OnPluginLoad event which fires during the Page_Load event. Here we look for the InstantASP.InstantForum.UI.Controls.ViewWhosOn this is the grid used to display the list of online members.

If we find this control we build up a new set of Panels adding our ViewWhosOn control to the panel on the left and our Google Map plug-in to the panel on the right. Finally we add the plug-in generated panel to the page just below the header control.

If we don't find an instance of the ViewWhosOn control on the page we simply hide the plug-in and ensure it does not generate the custom layout.