Admin Section: Creating a new custom module/section
See original GitHub issueHey Joel,
Sorry if this question appears elsewhere, I searched through issues and couldn’t find something specifically related. My question/issue revolves around implementing a brand new admin section/module. I’ve used the Cofoundry.Web.Admin
project and Modules
folder as references but have a few questions related to the JS side of things.
C#
- We have created a new ModuleRegistration class inheriting from
IStandardAngularModuleResgistration
In our own Core project under /Admin/Modules/SchoolData/Bootstrap
public class SchoolDataImportModuleRegistration : IStandardAngularModuleRegistration
{
private readonly IAdminRouteLibrary _adminRouteLibrary;
public SchoolDataImportModuleRegistration(IAdminRouteLibrary adminRouteLibrary)
{
_adminRouteLibrary = adminRouteLibrary;
}
public AdminModule GetModule()
{
var module = new AdminModule()
{
AdminModuleCode = "COFSCHDI",
Title = "School Data Import",
Description = "Import Schools Data .",
MenuCategory = AdminModuleMenuCategory.Settings,
PrimaryOrdering = AdminModuleMenuPrimaryOrdering.Last,
Url = new SchoolDataImportRouteLibrary(new AdminSettings()).Details(),
RestrictedToPermission = new SettingsAdminModulePermission()
};
return module;
}
public string RoutePrefix => SchoolDataImportRouteLibrary.RoutePrefix;
}
- Created a RouteLibrary for use in the URL property of the AdminModule above (not sure if this is correct convention here, but seemed the only way to create the correct routes) created under Core project Admin/Modules/SchoolData/Constants
public class SchoolDataImportRouteLibrary : ModuleRouteLibrary
{
public const string RoutePrefix = "schooldataimport";
#region constructor
public SchoolDataImportRouteLibrary(AdminSettings adminSettings)
: base(adminSettings, RoutePrefix,RouteConstants.InternalModuleResourcePathPrefix)
{
}
#endregion
#region routes
public string Details()
{
return AngularRoute();
}
#endregion
}
Is there anything else C# wise we would need to do to register this module, it seems to be showing up in the correct place within settings, and allows us to click on it, obviously showing nothing because angular errors, because we don’t have the proper JS framework set up yet.
JS
Here we have started to create some JS files from examples within the Cofoundry.Web.Admin
project, they live within our Core project in Admin/Modules/SchoolData/Content and /Js (mirroring the structure used in Cofoundry Admin project)
The things we’ve noticed are:
- In the Cofoundry project, there’s compiled JS for _templates.js, the controllers, etc - is this something we will need to do as well, is there a more simplified way of doing all this?
- My colleague mentioned that he thinks we may need to copy down the Shared folder in the Admin.Web project as he thinks some of the modules we are using as reference to write our own are dependent on that for loading.
I know there isn’t documentation yet on how to do all this, but was hoping we might be overthinking this and re-working the wheel here when there are already things in place to take care of most of this or a different way to do this then you have done in the Admin.Web project for the Cofoundry admin modules.
Issue Analytics
- State:
- Created 4 years ago
- Comments:6 (2 by maintainers)
TODO: Add documentation and samples for creating custom admin section.
Hi @mcockrellsana,
As you’ve probably worked out already, the admin panel is not well documented but is quite extensible. As a general rule the parts of Cofoundry that are documented should be relatively stable and will be well supported in terms of a migration path for future updates, whereas un-documented parts tend to be liable to change and may not have a documented migration path when we finalize the API.
With that warning out of the way, if you are a little adventurous and don’t mind digging into the code to work things out then that’s cool, I’ll see if I can point you in the right direction!
I see you’ve worked out quite a lot of this but I’ll just add some clarification to your questions for anyone who stumbles on this trying to do the same thing:
IStandardAngularModuleRegistration
You didn’t necessarily need to create a
ModuleRouteLibrary
here, and instead you could hard code the route if you prefer to avoid creating the extra class. One thing to note here though is that you’ve usedRouteConstants.InternalModuleResourcePathPrefix
which is reserved for internal (Cofoundry) modules.Because embedded resources are all consumed using relative paths from your application, we try and avoid conflicts by dividing module code into three categories:
RouteConstants.InternalModuleResourcePathPrefix
and are located in /Admin/Modules/RouteConstants.PluginModuleResourcePathPrefix
and are located in /Plugins/Admin/Modules/RouteConstants.ModuleResourcePathPrefix
and are located in /Cofoundry/Admin/Modules/This means that, for example, if we later introduce a Cofoundry module with the same name as one of your local modules, then we don’t conflict.
IAssemblyResourceRegistration
If you use
RouteConstants.ModuleResourcePathPrefix
and locate your module files in /Cofoundry/Admin/Modules/ in your local project then you shouldn’t need to add aIAssemblyResourceRegistration
. This is only necessary if you’re using them in a separate project/assembly e.g. if you’re creating a plugin.Compiled files
The admin panel was original developed in .NET framework and made use of .NET bundling and minification, which made it really easy to drop in new source files and dynamically bundle them. When we ported to .NET Core this wasn’t available and we switched to using a grunt build task to pre-compile the files.
I’m not really happy with how non-intuitive all this is to set up so we’d definitely be looking to improve this in the future.
For now, the error logging plugin is the best example to work to, although if you’re creating a local project module you’d need to update the paths as you should be working from /Cofoundry/Admin/Modules/.
Missing elements
You’ll need to wrap any ad-code html in your form into a
cms-form-field-container
control:Working example
It would be great if you wanted to put together a working example. We’ve just not had the resource yet to focus on making the extensibility here as straightforward as it should be and it’s likely we’d be looking at that further down road alongside a rebuild of the admin panel in a more up-to-date framework.