The Adapt team is very pleased to announce the landmark release v1.0.0-alpha.1 of the authoring tool!
v1.0.0 marks the biggest change to the codebase since its initial release in 2015; the culmination of several years at the drawing board redesigning the app architecture from the ground up, laying the foundations for features which simply weren’t possible previously. For this reason, we thought it fitting to give the release an appropriately major version number.
Objectives
After a process of substantial feedback-gathering, we identified the following main areas for improvement:
- To lower the barrier to entry/reduce the overhead of working with core code for new and existing developers.
- To facilitate a plug-in based architecture similar to the framework, and therefore reduce the need for major core changes in the future.
- To improve the stability of core code, and allow more effective automated testing.
- To expose a consistent and reliable public API for both internal use by the application and to third-party code.
Headline features
From our set of objectives, we created a high-level list of changes:
Modular architecture
The application has been split up into a number of small modules each with well-defined and specific purposes. This allows developers to focus their effort more easily, and reduces the need to have a working knowledge of the whole application.
All of these modules are now managed using npm, which makes it easy to set up installs with custom modules, as well as add/remove/update modules at a later date.
Consistent and conformant API
The API for the authoring tool needed to be updated to be more consistent across the application itself, as well as be more conformant to common web standards and best-practices. This covers everything from naming the conventions we use for the API and data returning from the API, to the use of HTTP status codes and a consistent format for error handling. Abstract classes have been added to help with this, allowing developers to extend from these to inherit common functionality without any extra work.
Better permissions
Defining permissions has been simplified, seeing us switch to a scope-based system which is both easier for the developer and the end user: easier for the developer to restrict behaviour based on meaningful ‘scopes’ rather than by specific URLs and easier to define roles for the end user for the same reason. It also makes roles more flexible, allowing developers to change API endpoints without having a knock-on impact on the roles.
Modernised codebase
In addition to the more stand-out changes, we got to modernise the entire codebase from the ground up, adopting the latest language additions from ECMAScript 6+ (bearing in mind the original codebase was written for ES5).
This includes:
- A switch to using classes to encapsulate functionality
- Heavy use of promises and async/await (replacing the older callback approach)
- Move away from ‘var’ variable declarations in favour of let/const to avoid scope pollution etc.
- Use of arrow functions to avoid scope-based errors
- Adoption of native loops and other helper functions
What this results in is much cleaner, more readable code with less reliance on third-party helper libraries such as Underscore.js and Async/Q. The new code should also be much less error-prone code thanks to ES6 features such as the scope improvements (e.g. arrow functions).
Full API documentation
One big area which needed improvement was the developer documentation, which consisted of an ad-hoc collection of documents with no real structure. For this release, we have included full API documentation (made possible via code comments/docblocs). We’ve also written a collection of user guides to accompany the API docs to give more context and worked examples where necessary.
Conformance to JSON schema specification
In line with our endeavours to be more standards-compliant across the board, we have updated all schemas used by the authoring tool to conform to the JSON schema specification (draft 2020-12 at time of writing).
This brings with it many advantages:
- More familiar to developers
- Fully documented by the maintainers of the spec
- Regularly updated, with a view to it becoming a web standard
- Flexible validation features
- Good support from many third-party libraries (e.g. validators, form renderers)
Improved app configuration
The aim here was to provide more power to developers to add their own custom configuration to the app, while also making the configuration process simpler for end users (particularly during install). This has been achieved by introducing JSON schemas for configuration data, which not only allows us to check if the config data is valid, but also provide default values where appropriate and integrate with GUIs more easily. The ability to have separate configuration settings for different environments has also been added to allow for more complicated setups.
Continuous integration pipeline
We wanted to make more use of a continuous integration (CI) pipeline to automate repetitive tasks and take some pressure from the development team when it comes to releases. Tasks which we intend to add to the CI process are:
- Code linting
- Unit testing
- Documentation generation
Module list
The restructured app consists of the following separate modules:
- adapt-authoring-adaptFramework: deals specifically with using the framework to create the Adapt course output, as well as imports and exports.
- adapt-authoring-api: an abstract module which can be extended by developers in their own modules. Used in many of the core modules.
- adapt-authoring-assets: deals with asset management.
- Adapt-authoring-auth: deals with authentication and authorisation of requests to the app API.
- adapt-authoring-authored: adds metadata to database records to denote when a record was created/updated
- adapt-authoring-config: deals with the configuration settings for the app
- adapt-authoring-core: contains the main entry-point for the app as well as abstract classes for extending by other modules.
- adapt-authoring-courseassets: deals with counting references to assets in courses
- adapt-authoring-coursetheme: deals with customising the theme applied to a course
- adapt-authoring-defaultplugins: adds ability to define framework plugins to be enabled by default when a course is created
- adapt-authoring-installer: an HTML-based installer GUI
- adapt-authoring-jsonschema: handles JSON schema validation
- adapt-authoring-lang: handlers the localisation of language strings
- adapt-authoring-localauth: handles authentication via username/password
- adapt-authoring-logger: logs messages to the output console
- adapt-authoring-mailer: handles sending emails
- adapt-authoring-middleware: adds generic middleware to the Express.js stack
- adapt-authoring-mongodb: adds support for MongoDB
- adapt-authoring-mongodblogger: extends the logger module to add log modules to the MongoDB instance
- adapt-authoring-roles: deals with user roles
- adapt-authoring-server: adds an HTTP server
- adapt-authoring-sessions: provides user sessions to remove the need to login each time the web app is visited
- adapt-authoring-spoortracking: adds support for progress tracking in courses via spoor
- adapt-authoring-tags: adds ability to tag content with searchable keywords
- adapt-authoring-ui: the main app UI
- adapt-authoring-usergroups: adds ability to group users for easier content sharing
- adapt-authoring-users: deals with users
What next?
The new version of the tool is currently in the first alpha iteration. We need as many people as possible to install this and give it a thorough going over to identify all the bugs that will inevitably be in there and report them as GitHub issues. There are a number that we've already spotted and added to the issues list - please check through these before reporting new ones.
We will fix the issues as quickly as we can. Once we're happy that the code is in a stable state we will declare a public beta which you can, if you're feeling brave, start using with real users.
Once we have a stable release we can return to feature development - of which there's a long backlog that has built up. Hopefully with the new codebase we will see a marked increase in velocity.
