This version of the Ed-Fi Dashboards is no longer supported. See the Ed-Fi Technology Version Index for a link to the latest version.

Ā 

Developers' Guide - Plugin Architecture

Overview


This documentation provides sample implementations of the plugin architecture for Ed-Fi Dashboards. The intent is to provide detailed information about the creation of plugins and the complete interaction with data, services, and views while documenting the overall plugin architecture and major conventions so that an accomplished developer in the technology can successfully create plugins.

Audience

The primary audience for this document are developers implementing plugins for dashboards powered by Ed-Fi.

Prerequisites

The Ed-Fi platform architecture uses a collection of design patterns, architectural best-practices, conventions, and databases. In order to understand the code base and be able to write a plugin, it is important to understand these patterns and techniques. It is recommended that a developer intending to implement a plugin has knowledge and understanding of the dashboardā€™s extension mechanisms and has completed the dashboard setup guide. Setup information is available in the Ed-Fi Dashboards Getting Started guide and detail about the dashboard architecture can be found in the Ed-Fi Dashboard Developers' Guide.

Basic Guidelines for Implementing a Plugin

There are a few basic guidelines that are very important and should be followedĀ when developing a plugin:

  1. All plugins should be mutually exclusive and self-contained. Plugins areĀ intended to be new functionality that gets added to the dashboards.
  2. Plugins follow the basic Ed-Fi conventions for extensions. See /wiki/spaces/TT/pages/18645095.
  3. Plugins should use the convention-based project names starting always withĀ EdFi.Dashboards.Plugins.[PluginName].[ProjectType].Ā For example:Ā EdFi.Dashboards.Plugins.[PluginName].Resources,
    EdFi.Dashboards.Plugins.[PluginName].Data.
  4. A new plugin should always be developed under the currentĀ EdFi.Dashboards.Plugins.Web version. This means that if this project is MVC 3Ā with .Net Framework 4.0, you should use MVC 3 with .Net Framework 4.0 or theĀ plugin will not work.
  5. JavaScript and CSS files need to be declared as Embedded Resources.

Technical Overview

The plugin architecture hooks into the existing dashboards by leveraging theĀ CastleWindsor Inversion of Control (IoC) container.Ā When the container is created, on Application_Start, it looks in the ~/Plugins
directory for appropriately named DLLs. If it finds any plugins, it then usesĀ reflection to create instances of classes that implement the IWindsorInstallerĀ interface. The IWindsorInstaller classes are responsible for wiring up theĀ dependency injection for the plugin.

Once the IoC container has been initialized, the dashboard initializes the MVCĀ framework. During this initialization, the dashboard will again look in theĀ ~/Plugins directory for appropriately named DLLs. If it finds any plugins, it thenĀ registers all of the custom routes, controllers, and views. If the plugin hasĀ embedded JavaScript or CSS files, it creates the Cassette bundles for thoseĀ embedded resources.

At this point, the plugin is available to be consumed.Ā 

Plugin walk-through samples:

Troubleshooting

Security Exception

Error message: You do not have access to: [Resource].

Resolution: Make sure the methods on your controller and service have the required parameters in the signature. For example, if writing a plugin at the StudentSchool Level, make sure you have the SchoolId and the StudenUSI. You can also ensure that your service method is attributed with the CanBeAuthorizedBy and required claims:

[CanBeAuthorizedBy(EdFiClaimTypes.ViewAllStudents, EdFiClaimTypes.ViewMyStudents)]

The Dashboard Doesnā€™t Find My View

Error message: System.InvalidOperationException: The view ā€œGetā€ or its master was not found or no view engine supports the searched locations. The following locations were searched: [Locations]

Resolution: Make sure the namespaces are correct. EdFi.Dashboards.Plugins.[PluginName].Web.Areas.[area].Views.[controllerName].Get. Also make sure that you have enabled Razor Generator on the view.

Controller Not Found Error

Error Ā message:Ā ControllType return null while opening the sample plugin page in Admin login.

Resolution: Check the PluginHelper.GetPluginInstallers() which is called by InversionOfControlContainerFactory.GetInstallers() to ensure that the Plugin's installers are getting passed to the call to Castle.Windsor.Install(params IWindsorInstaller[] installers) which will trigger Castle Windsor to callĀ 
EdFi.Dashboards.Plugins.HelloWorld.Web.Utilities.CastleWindsor.Installer.Install which will callĀ 
EdFi.Dashboards.Presentation.Core.Plugins.Utilities.CastleWindsor.WebDefaultConventionInstaller<Marker_EdFi_Dashboards_Plugins_HelloWorld_Web>.Install(IWindsorContainer container, IConfigurationStore store) which will call
Castle.Windsor.WindsorContainer.Install(params IWindsorInstaller[] installers) passing in theĀ 
EdFi.Dashboards.Presentation.Architecture.CastleWindsor.ControllerInstaller<Marker_EdFi_Dashboards_Plugins_HelloWorld_Web> which will trigger Castle Windsor to call
EdFi.Dashboards.Presentation.Architecture.CastleWindsor..ControllerInstaller<Marker_EdFi_Dashboards_Plugins_HelloWorld_Web>.Install which uses reflection to find and register the Plugin Controller Types with Castle Windsor

About the Developers' Guide Documentation


This documentation contains detailed conceptual and how-to information for developers working with the Ed-Fi Dashboards. It describes in detail the various components of the solution, and provides specific guidance on how to extend and deploy the system.

Ā 

Ā