Preview: DNN Dev Tools 02.00.00 integrates into DNN 9’s new Persona Bar

Introduction

DNN 9 will introduce a great new admin experience by replacing the old control bar (placed on top of the screen) with the so called “Persona Bar” (placed on the left side). You can read more about the ideas behind the Persona Bar in the blog posts “DNN 9 and the Future of the DNN Platform” and “DNN 9: Rethinking the Admin Experience“. On a technical level this concept means a massive change to all (admin) user interfaces that want to be integrated in the Persona Bar: Until DNN 8 they were built as “standard” DNN WebForm or SPA/MVC modules; now, they need to be built with pure frontend technologies (HTML, JavaScript and CSS).

These days the DNN team is working on rewriting all core admin modules (like user management or page management). A preview version of DNN 9 including a nearly completed new admin experience is already available as nightly build. Most likely and due to compatibility reasons, the old admin interfaces will be still accessible in DNN 9, but and sooner or later most DNN module developers need to think about migrating their modules into the new world.

Some days ago DNN published the post “DNN 9: Extending the Persona Bar” which shows a basic example of how to develop modules that extend the Persona Bar. This motivates us to take a closer look into the new concepts and to find out what needs to be done to migrate an existing module. We chose our open source module DNN Dev Tools which is available on GitHub. You can find more information about the module on our website or in this video. The module contains one admin interface called “Host Settings” which allows configuring the module’s preferences. In this blog post we will give a short overview about what we changed to move the Host Settings interface from a traditional DNN module into a Persona Bar extension.

2016-11-09-dnndevtools-personabar

Please note: The following part of this blog post is addressed to DNN developers and requires some technical DNN knowledge to be understandable.

Technical details

Before getting into the source code changes, it’s worth mentioning that one of the main learning for us was: Turn off your browser cache when developing Persona Bar extensions. As most of the code you write runs on the client side, it’s getting cumbersome if the client caches old versions and you are wondering why your source code changes don’t have any effect.

Please also note: DNN 9 is not yet released and all information here is based on the DNN 9 nightly build (9.0.0.356). So there might be some (breaking) changes until the final release, but there shouldn’t be any fundamental changes.

As soon as DNN 9 is finally released and after rechecking the DNN 9 compatibility of our source code, we will officially release DNN Dev Tools 02.00.00 with Persona Bar support. You can find the source code of the “Persona Bar” version discussed here on GitHub in the feature branch “feature/DNN9“. In the remaining part of the post we elaborate on the most important source code changes we have done. If you are interested, please check out the source code and follow our how-to to set up your development environment.

DNN manifest

The most important change were done in the DNN manifest file which defines the package structure. We completely removed the module component and replaced it by a PersonaBarMenu component:

<component type="PersonaBarMenu">
  <menu>
    <identifier>DnnDevTools</identifier>
    <moduleName>DnnDevTools</moduleName>
    <resourceKey>nav_DnnDevTools</resourceKey>
    <path>DnnDevTools</path>
    <mobileSupport>true</mobileSupport>
    <parent>Settings</parent>
    <order>2</order>
  </menu>
</component>

As the PersonaBarMenu component takes care of registering DNN Dev Tools into the Persona Bar menu, we removed our Business Controller that took care of creating the host page containing the Host Settings module.

We also changed the dependency to require DNN 9:

<dependency type="CoreVersion">09.00.00</dependency>

Persona Bar files

For our Persona Bar extension we needed to create four files that are deployed into the subfolder admin\Dnn.PersonaBar under the websites root folder:

  • DnnDevTools.html: Contains the user interface
  • scripts/DnnDevTools.js: Contains the JavaScript frontend logic and Persona Bar initialization boiler plate code
  • css/DnnDevTools.css: Contains all styles (we use Sass to create this file)
  • PersonaBar.resx: Contains resources (like the “nav_DnnDevTools” that is referenced in the manifest file, see above)

Basically, we moved the corresponding code from our Host Settings module into these files. As the module was built as MVC module, the user interface was already defined in pure HTML and most of the frontend logic was already written in JavaScript. When migrating WebForm modules there might be more work to do.

It’s important to mention the initialization code that was copied from here (section “JavaScript file”) into DnnDevTools.js. This code takes care of instantiating our extension when the corresponding Persona Bar entry was clicked. It’s also worth to take a closer look to the following line

var config = cf.init(); // cf is passed as argument to the initialization method

as cf.init() returns a config object that contains various useful information about the system (like the Portal ID) and the current session (like user information). We for example use config.antiForgeryToken which defines the token that needs to be passed to “protected” Web API endpoints or config.culture which defines the current culture.

Of course, we needed to adjust the build process to make sure the new frontend files are included in the DNN install zip package.

New Web API controller

As everything happens on the client side and the user interface is defined in one (simple) HTML file, we needed to create a new Web API controller “PersonaBarController” (source code file DnnDevTools/Src/DnnDevTools/Api/Controller/PersonaBarController.cs) that is used to transfer all dynamic information (current DNN Dev Tools settings and resources) from the server to the client. In a nutshell, just after rendering DnnDevTools.html the client gets the data from that API and updates the HTML, i.e. sets the initial form values and localizes the frontend by inserting the resource. In detail, the server returns a JSON that looks like this and the logic to process the response is part of scripts/DnnDevTools.js:

{
  "Enable":true,
  "EnableMailCatch":false,
  "EnableDnnEventTrace":false,
  "LogMessageTraceLevel":"OFF",
  "HostSmtpConfigured":false,
  "Resources":{
     "DnnEventTraceDescription":"This option activates notifications about events that are created in the DNN environment.",
     "DnnEventTraceButtonLabel":"Trace DNN Events",
     "EnableDevTools":"Enable DNN Dev Tools",
     [...]
  }
}

Summary

The new admin experience in DNN 9 introduces radical technological changes and it requires some work to migrate traditional interfaces into Persona Bar extensions. Of course, the amount of work depends on the complexity of the interface and the used technology: While migrating SPA/MVC modules that already rely on client side technologies should be relative easy, WebForm modules most likely need to be rewritten from scratch. In total the migration took us about 6 hours whereas we spent the most time on getting familiar with the Persona Bar concepts and APIs.

Summarized, it’s worth to think about a migration: DNN 9 will come and the new admin experience will be the default. And not only the end users will benefit from the new usability, but also developers as development is significantly faster. The new client side approach makes the annoying and time consuming redeployment of DLL files which always restarts the complete website obsolete.

The changes we made to our module can be found in the source code download or in the feature branch on GitHub. If you just want to try out the preview version of DNN Dev Tools 02.00.00, you can download the install zip file.

 

More information: