At the very heart of the Umbraco CMS lives the desire to provide the most intuitive editing experience possible. It can only be done with a good toolkit for developers to create the best UI and functionality for their backoffice users. Being able to extend Umbraco is in the DNA of the CMS.
For this to be possible, we need to make sure the CMS stays current, and the technology it is built on doesn't get in the way. At the beginning of the year, we started the project "Future Proofing the backoffice" where we will give the backoffice frontend code an overhaul to ensure it continues to provide a great editing experience that is intuitive, flexible and highly customizable. We are already well underway with Part 1 - "UI Component Library."
We are now ready to start Part 2 - "Define the backoffice extension API."
Tune in to Umbracoffee today, at 12.30 CEST, where Filip Bech, CMS Program Manager at Umbraco, and I discuss the project with Callum and Marcin.
What is the backoffice extension API?
Before we dive into the project details, we want to look at what the backoffice extension API is and why the project is important.
The extension API is all the parts of the Umbraco UI you can extend through code. The focus of Part 2 will be on what we can and want to extend through the frontend code. This includes custom sections, content apps, property editors, tours, overlays, etc.
The challenge with the current extension API is it’s too limited, which forces developers to rely on unofficial and undocumented hacks, and that in turn means that the backoffice now unofficially supports, or at the very least needs to consider these. This makes it difficult for newcomers to understand, and it makes it hard to know what can be safely used/changed.
Furthermore, the current API is tightly coupled to AngularJS, which means new developers have to learn an additional (outdated) framework to extend/customize Umbraco. It also means that changes to the framework will break the API.
Defining a new extension API.
With a new extension API, we want to address the challenges mentioned above. We need to find out which parts of the CMS should be extendable and provide an API that officially supports these areas. The goal of Part 2 is to define an API based on Web Standards and best practices without any ties to a specific framework.
Some of the questions we want to answer in this project are:
- How do we want to build dashboards and property editors?
- How do we bind a value on a property editor, how will validation work and can it be async?
- Do we want a service-based approach like today or a global store like Redux?
- How do we interact with the data layer?
- Should it be possible to add an extra option to the save and publish menu and how will we do it?
As opposed to Part 1, which was started with an RFC, the end-result of this project will be an RFC with the learnings we have made and a proposed solution to how developers will be able to extend the backoffice in the future. We will have to gather a lot of knowledge about the current extension API and how it is used before we can propose a new one.
The project comes in four parts.
- Explore the current state of the official extension API.
- Get to know the need for extension points from various developers extending the backoffice.
- Prototype and describe the new extension API.
- Publish RFC for Part 2: Define the backoffice API
1. Explore the current state
To best describe what we need, we first have to get an overview of what we already have. We will explore our current documentation and training material to get an overview of our official API. The material includes:
- Extending Umbraco documentation
- Back Office API reference documentation
- Extending the Backoffice training course
2. We need your expertise
We want to make sure the new API covers the existing extension points but also want to explore the areas that are not covered by the current official API. To get to know the needs, we want to interact with developers who have experience in extending the backoffice:
- Agency solutions where extensions are needed but are kept internal
- Package developers that create smaller extensions in Umbraco CMS to improve the editing experience
- Developers of large packages, including commercial packages, which heavily rely on the extension API
- Research other CMSs extension models
- The Extending the Backoffice training course. Collect all the valuable information we get when we teach developers how to use our API. Which parts are hard to understand, common questions, etc.
- HQ product teams: Forms, Deploy, Heartcore, Uno. We are a consumer of the extension API, and we should learn from our internal teams.
The outcome will be to uncover the most important parts of our official API and reveal parts of our unofficial API that deserves more love. We want to identify the areas where developers either have compromised the user experience because of limitations in our API or have made "hacks" to achieve what they want.
3. We need a strong community team!
Throughout the project, we will build prototypes and describe the new extension API. It will be an iterative process where we will try out different approaches. We will create a new community team that will regularly give feedback on the knowledge gained through the project. The team will function as a sounding/advisory board where they can give feedback to ideas and prototypes. Read more about the community team in “How you can get involved."
4. Publish RFC for Part 2: Define the backoffice extension API
The final part of the project is to publish the RFC with the new extension API. The RFC will include examples and a prototype to start the discussion. This will open up for comments and feedback from a wider audience.
How you can get involved
For this project to be a success, we need your stories and hacks to tell us how extending the Umbraco backoffice should be. Collaboration is key to success - we need your thoughts, ideas, and assistance. We want to initiate some activities over the next couple of months, as follows:
- Discussion board for community involvement
- Share your hack/story
- Backoffice Community Team
Discussion Board
We have created a new repository with a discussion board for this project. Feel free to share all your ideas and thoughts about the new extension API there. It will be open to everyone to follow and participate in the discussion. At the moment the repository will only be used for its discussion area.
Share your hack
We would love to see a lot of examples of your creative backoffice extensions. Everything from property editors, custom sections, new buttons, overlays, etc. When you share your extension please include:
- How your extension works
- How you have developed it
- How you think a solution with a better extension API should look
Find the format you think tells your story the best way: video, blog posts, code pens, gists, repositories, or whatever works best for you. If possible, share your hack on the new discussion board, so it can contribute to the overall discussion and might spark ideas in other community members. This is how you use the board:
Go to the discussion board on the new repository and start a new discussion
Select the category that fits your topic and start your story
We have made an example discussion as inspiration. Feel free to tell your story the way you like.
We also fully understand if you are not able to share your extension in public so feel free to send your extension/story/hack to backoffice@umbraco.com
Backoffice Community Team
If you want to get even closer to the project we will create a new community team as mentioned earlier - the Backoffice Community Team. The team will consist of 3-5 community members who will dedicate some of their time to evaluate and give feedback on the extension API prototypes we will make. The team will also help with examples and use cases. The team will review the RFC before it goes out.
More information about when and how to join the community team will be shared in a blog post on Wednesday, April 14th, 2021.
Let's get started!
We’re really excited about this next phase in Future-proofing the Umbraco backoffice and hope you’ll participate with feedback, examples, great ideas and maybe even join the team.
