The New PencilBlue Admin Section

We've decided on a frontend framework

January 12, 2017

A few months back we promised to make a decision on whether the admin section for PencilBlue 1.0 would be written in Angular 2 or React. After listening to your feedback and development needs, and calculating the long term requirements of the platform, we have decided to go with React.

This was a choice that was equally driven by business requirements as technical ones. Because we know that there would be a strong reaction from the community regardless of which frontend framework we chose, I'll do my best to convey the main factors behind this decision.

Minimizing barriers to entry

Obviously, we want people to use PencilBlue - to learn how to develop with it and, ultimately, to develop plugins for the community. In order to accomplish this we saw three key requirements for the admin section upgrade:

  • Development in JavaScript
  • Minimize the amount of third party frameworks needed
  • No added server-side rendering (only core PencilBlue functionality)

Development in JavaScript

When we released PencilBlue almost three years ago, we received a substantial amount of complaints that we didn't write it in CoffeeScript. For obvious reasons, we're glad that we went with JavaScript then and we believe we'll look back in a few years and be happy that we stuck with it now.

Maintaining PencilBlue is no small task. There are a wide range of issues and questions that make their way into our github queue, from how to meet a very specific technological or business need, to how to install Node.js. Adding a whole new category of "how to fix something breaking in TypeScript and/or its compilation process" could be disastrous for the platform's long term health.

It's been almost a whole year since Angular 2 moved out of alpha and, as of now, the promised JavaScript tutorial page has still yet to be created. We can't bank our business on such uncertainty.

React, on the other hand, is wholly bought into ES6 - with documentation - making it the clear choice in the "pure JavaScript" requirement.

Minimize the amount of third party frameworks needed

We work to make PencilBlue as easy to learn as possible, but as a business class CMS it naturally has a higher barrier to entry from platforms geared for less complex use cases. We don't want to pile onto that by introducing unneeded complexity.

It's much easier to transition our existing user base to the major changes of 1.0 (and to onboard new developers) by saying:

In order to build admin plugins you'll need to learn how to build a basic, client-side React controller in ES6.

... instead of saying:

In order to build admin plugins you'll need to learn Angular 2, TypeScript, how to compile it with the base PencilBlue admin section TypeScript using the CLI, and how to make sure you don't conflict with any other third party admin plugins that also need to be compiled.

That being said, you remain completely free to use whatever frontend frameworks you want in your site themes or public facing plugins. React only applies to admin section modification itself.

No added server-side rendering

We regularly receive requests to integrate Pug (formerly Jade) or Handlebars into the platform. Rather than tie down PencilBlue to any one rendering engine - outside of our built in services - we direct users to integrate their library of choice directly into their Node.js controllers.

It's for this same reason that we chose not to use server-side React, opting for the client-side implementation with Babel. Who knows what PencilBlue 3.0 will look like, or what browser functionality will be available in five or ten years?

In the interest of the long-term lifecycle of the platform, we want to keep the server side code as pure as we can. We want to give you, the developer, as much flexibility in your implementation as possible.

Where we go from here

We want to do this right. PencilBlue 1.0 will be our first set of breaking changes to the platform in almost three years (something we're very proud of), and we intend to make sure that it's worth the effort to upgrade.

We will, of course, be documenting everything, including a full upgrade path and generated code-level documentation for the new admin section. We also intend to release a book on PencilBlue development after the release.

The admin section refresh is only one piece of the total 1.0 package. We'll be releasing an updated roadmap in the near future, as well as making some exciting announcements regarding our development community.

You can see the beginnings of our React implementation on the angular-react branch of the platform, and watch the progress from there as well. As always, we are open to pull requests to help speed up the process and are best reached through our github issues or our Gitter channel.

New Routing Capabilities of 0.8.0

January 5, 2017
Some of the first lines of code that was written for PencilBlue was the request handler.  A bit of code that was meant to facilitate request processing in order to provide the correct response.  Over the past couple of years this code became complex and bloated.  With the release of 0.8.0 we introduce a streamlined version of the request handler.  The goal was to abstract the routing engine.  This would provide a few benefits.  First, it would allow for the request pipeline to be testable.  Most importantly, the change provides the flexibility that developers desired to be able to inject code (middleware) into the request pipeline.  We’re happy to announce that this feature is now available as part of our 0.8.0 release (release notes here).  

PencilBlue provides a set of default middleware that performs everything from request timings to controller execution.  The code leverages the same framework that is available to plugins.  Developers can now inject special logic to decide how to handle the request.  The framework itself provides three basic functions to manipulate the request pipeline: add middleware, remove middleware, replace middleware.  At startup, PencilBlue will register its default middleware.  During the onStartupWithContext event, plugins will be able to register their own middleware or manipulate the existing middleware.  

Here are a few rudimentary examples of how developers might leverage the platform’s new features:

Replacing/Overriding Middleware:
In this first example we’ll look at replacing the standard functionality for serving public files.  We’ll demonstrate how overriding the middleware will allow us to minify outgoing javascript files.


Removing Middleware:
Optimizing for performance is a must.  You may not always need all of the default middleware.  Here we look at how to remove undesired middleware from the pipeline by ask the framework to remove the middleware that logs the request result to the console, when in debug mode.


Adding Middleware:
In this example we’ll be adding a header to enable CORS for all domains.  This will allow sites to access the APIs of PB from other domains.



Looking ahead:
Next up we’ll be moving toward our 1.0 release, targeted for 2017.  It will sport a promise based framework utilizing ES6 classes.  The change will cause breaking changes from previous releases.  Additionally, deprecated functionality will be removed.  To make this upgrade easier on our users we’re tediously keeping notes on all changes to publish an upgrade guide as part of the new release.  The branch for this release has already been created and with the help of some of our users we’re making good progress.

As always, feel free to reach out to us on Twitter, Gitter, or on GitHub.

React or Angular 2?

Listening to community feedback on the admin section refresh

October 10, 2016

A few months ago we announced that the admin section of PencilBlue version 1.0 would be upgraded to Angular 2. We saw this as a natural progression for the platform, since the current frontend runs on Angular 1.x.

We were immediately inundated by users asking, "why not React?"

Frankly, we never gave React much thought. When we first built PencilBlue over two years ago, Angular was the overwhelmingly accepted, enterprise frontend framework. Then the drama around greenfielding Angular 2 came about, and many went to the seemingly more stable pastures of Facebook's React framework. It now has an equal share among enterprise web teams and, according to the 2016 State of JavaScript survey, it has a greater favorability among developers. Pure ES6 also has a much higher overall favorability among JavaScript developers than TypeScript.

So, as maintainers who try to always listen to our user base - often to a fault - we explored React as an option. After all, we're going to have to completely rewrite the admin section either way, since we're performing a total facelift. Weighing the pros and cons of the two frameworks, we came to the following conclusions:

  1. We based our original decision on Angular 2's promised support for ES6, but it's still inexcusably nonexistent (especially when you consider that their basic tutorial even has Dart examples but no JavaScript). Though we like TypeScript on its own merits, Angular 2's current state will force our users to develop PencilBlue admin plugins in two different languages - and for us to support that complexity.
  2. As of now, React is wholly bought into ES6, which aligns its use with our goal of converting the Node.js side of PencilBlue to ES6 for the 1.0 release.
  3. Enterprise development teams seem to be equally split between Angular 2 and React, so choosing either one will garner an overall equal reaction.
  4. The only developers effected by this change are those who build custom admin section plugins. You still can build your own themes and other plugins with whatever frontend framework you desire.

Though it may be obvious where we're leaning, we haven't made an official selection yet. We'll make that announcement with the release of 0.8.0 in December. If you feel strongly one way or the other, we encourage you to reach out to us on Twitter or Gitter.

0.7.0 and the Path to PencilBlue 1.0

September 26, 2016

0.7.0 brings about the start of some exciting changes.  The release focuses on preparing the platform for next year’s 1.0 release.  The simplification of the Localization and the Plugin services ensures that each piece of the two services is maintainable and testable.

Aside from cleanup and bug fixes we are excited to announce 3 new features.  The first is the ability to override the default sanitization rules for WYSIWYG content.  This will allow plugins to relax the strict rules when developers have specific needs.


See the function definitions here.

The second big feature is the ability to group plugin settings.  Developers found that as their plugins grew in complexity so did the number of plugin settings.  Having a large number of settings made it difficult to find what needed to be changed.  Additionally, the UI automation was more difficult than it needed to be.  The addition of the settings groups makes this easy by adding identifiers for the headings and separating out settings into logical groups.  With this change plugin settings can now specify a “displayName” property.  Optionally, the value can be a localization key in order to support multiple locales.

Lastly, we are pleased to announce Bower support for plugins.   The details.json file now supports a “bowerDependencies” property where each dependency can be specified.


Sample details.json file.

This gives plugin developers greater freedom for managing dependencies.  During installation and on startup PencilBlue will inspect the file system to ensure that the dependencies exist.  If not then PencilBlue will perform a Bower install to persist the missing dependencies.

Looking forward to what is coming up next we have one more release in 2016.  0.8.0, set for a December delivery, will update the navigation capabilities of the platform.  It will place a focus on creating multiple menus, placements, and SEO.  Secondly, the request handler will be getting refactored for performance and flexibility.

The following release, set to be delivered early 2017, will bring the platform out of beta as 1.0.  PencilBlue 1.0 will bring about a few changes to the platform.  First, the core of the platform will leverage promises over callbacks.  We’ve weighed the pros and cons and came to the conclusion that it provides a cleaner look and feel to the code as well as falls in line with what the majority of our enterprise users will use for testing and automation.  Additionally, the move to promises will come with our move ES6.  Our prototypes today are designed very much like ES6 classes.  This transition will simply make the design more familiar and fall in line with the latest JS standards.  Next, all deprecated functions will be removed.  This will bring about the first set of breaking changes in the platform.  Not to fret, we will be providing an upgrade guide for code and existing data.  Finally, the admin section and default theme will be getting a fresh new look.  The default plugins will leverage the APIs that have been and are in the process of being developed.

With any major release there are a few things that are still in flux.  Here are a few decisions that will be made and decided on as we release 0.8.0.  

·      React or Angular 2 for default plugins -

·      Plugins as NPM modules

·      Removal of core prototypes to a separate NPM package

As always the feedback from the community is greatly appreciated.  You can reach us via Twitter @GetPencilBlue or on Gitter.

PencilBlue and Angular 2

We decided to make the switch

June 27, 2016

The most common question we receive nowadays is, "when will you upgrade PencilBlue to use Angular 2?" As a platform whose admin section is decidedly tied to Angular 1.x, it hasn't been an easy question to answer. Our official public and private stance has been to wait for Angular 2 to leave beta before making a decision, based on the developer community's reaction, whether to make the switch, stick with 1.x, or wholly move to another framework like React or Ember.

As of May 2, Angular 2 is in the release candidate phase. The speed at which the Angular team reached this point, and the warm reception its received, frankly, caught us off guard. And when we applied it to our current roadmap, we found it couldn't have come at a better time.

Therefore, we have made the decision to migrate the default, PencilBlue plugin to Angular 2, in accordance with our current effort to power everything exclusively through REST APIs. Our goal for this update will be March 2017. Here's how we see the next nine months playing out.

July: API and service refactors, plus other performance enchancements that we've been working on for the last few months.
October: Localization enhancements and custom sanitization rules.
January: Refactoring of the request handler to work more like Express/restify/hapi.
March: New default plugin built on Angular2.

Along with this change to Angular 2 will come a full redesign of the admin section to make use of the new APIs, and to present a better interface that meets all of the user needs we've collected over the last two years.

The key UX change is that everything will center around contextual information. If you're looking at a user, you'll see the articles or comments they've written. If you're looking at media, you'll see the articles and pages they're included in.

If you want to see a preview of this interface, you can look at the admin-update branch (which is currently running on Angular 1.5.6). We will, of course, work with our users and partners who have created admin plugins to ease the migration process before the Q1 2017 release.

These shifts will mark our first a major, breaking change to the platform since our initial release in July of 2014 (something we're very proud of, by the way). Because of this, the Angular 2 release in January 2017 will be PencilBlue version 1.0.0. We're excited to have a concrete schedule for leaving beta, and we hope you are too.

As always, if you have any questions or concerns with this change plan, you can share them with us on our gitter channel.