This post will go through the setup of custom backoffice pages in Umbraco 7, as well as adding Autofac and Serilog.
This is a long post, and I was able to get the time needed to write it using Professional Development time provided the company I work for, Readify. To find out more about the career opportunities and benefits they offer, see join.readify.net
Umbraco Project Setup
The process of creating an new Umbraco instance is explained in the official documentation
For this post, I am using version 7.5.14.
All the code from this example can be found on my GitHub
Logging and Dependency Injection Container Setup
Using Autofac for the IoC setup
Autofac
Autofac.WebApi2 - WeApi dependency injection
Autofac.Mvc5 - MVC dependency injection
Autofac.Web - WebForms dependency injection
Using Serilog for the logging
Serilog
Serilog.Sinks.Seq - For writing logs to seq
Serilog.WebClassic - For logging web content
Serilog.WebClassic.WebApi - For logging webapi
Serilog.Enrichers.Process - Supplies information on the running process
By default Umbraco overrides the standard ASP global.asax, replacing the usual Global class with their own implementation of HttpApplication, UmbracoApplication. This class is responsible for initialising a large amount of Umbraco’s services, so the site will not work correctly if it executed on startup. This class prevents use Application_OnStart and the other HttpApplication event callbacks to hook into ASP events. Fortunately Umbraco application provides alternative callbacks that can be overridden to achieve this.
Example implementation of Global.asax, registering Autofac for dependency injection and Serilog for logging
AU Language support
Note for Australian languages: Umbraco doesn’t support Australian English at the time of writing, only UK English and American English. Setting UK English gives the correct date formats, but uses the pound symbol for currency, while American English gives the dollar for currency, but uses the wrong date format. To create an EN_AU locale for umbraco, copy the existing US English or UK English and rename the file to “en_au.xml” replace the language element with <language alias="en_au" intName="English (AU)" localName="English (AU)" lcid="" culture="en-AU">. This will allow you to set users to have Australian English as their language in umbraco.
The moment locale did sometimes not set correctly to en-au, so I had to add “moment.locale(‘en-au’);” to line 10682 and 11026 in “umbraco.controllers.js” after the moment script was loaded to ensure it was working correctly.
Build and deployment
Refreshing cached files
Umbraco uses the client dependency framework for caching resources when running in release mode. A cache refresh is triggered when the value of the version attribute of the ClientDependency element in the ClientDependency.config file. As Umbraco does not automatically update this value, it needs to be manually updated as part of the build and deployment process, or else clients will have issues with cached resources.
A simple method of resolving this is to set the content of the attribute to a unique numeric value for the file .ie “0000000000”, and the a find and replace build step to perform the substitution.
As the file is XML, powershell’s xml support could also be used to perform the substitution.
Setting folder permissions
The configuration screens in umbraco require the website to be able to modify files in the config and app_data folders. This can be configured as part of the deployment process using the following powershell script in octopus deploy:
Media Folder
As users can upload content into umbraco, it is recommended to set Umbraco’s media directory to a directory that will be persisted between deployments. This can be done by changing the umbracoMediaPath appsetting to point to a folder outside of the deployment directory, or configuring the website to have a virtual directory for the default “~/media” path. Umbraco App Settings
Security
By default umbraco uses an implmentation of the ASP.net identity provider for internal users and external membership, but does not have very practical
security options enabled.
If your site is using SSL (Which it should), require it for logging into umbraco with the appsetting <add key="umbracoUseSSL" value="true" />
I recommend setting the following attributes on the UsersMembershipProvider:
enablePasswordRetrieval=”false”
enablePasswordReset=”true”
requiresQuestionAndAnswer=”false”
passwordFormat=”Hashed”
allowManuallyChangingPassword=”true”
Extensions can go in App_Plugins to provide separation from standard umbraco content/features
All plugin.manifest files are loaded, when you’re in the backoffice, regardless of what page you’re on. Because of this, a ‘Shared’ plugin is not required, but is neater.
Custom backoffice sections
To create a new menu option in the Umbraco Back office:
Create new application - Provides the new menu ico
Create new menu tree - Defines the navigation structure within a tree
Newly added menus will be disabled for users by default. They can be enabled using the user settings menu in umbraco.
Umbraco’s menu structure is designed for each entity to exist a node in the tree structure, and to an edit.html for each. This doesn’t let itself well to large sets of data such as a list of orders. It’s possible to manipulate the route resolution to allow you to use a html file with a specific name instead of the default edit.html. This allows the addition of custom views that don’t have to confirm to umbraco’s expected structure, which has the upside of allowing quick and easy development for adding simple CRUD pages, but prevents proper integration with Umbraco’s features.
Folder structure maps to urls as described below:
Umbraco#/PluginName/PluginTreeName/PageName/0
~/App_Plugins/PluginName/backoffice/PluginTreeName/PageName.html
Umbraco uses angular ui router for its navigation, so it may be possible to define custom routes. As I am avoiding making any changes involving the contents of the umbraco and umbraco_client folders, I haven’t investigated this.
Javascript and css files used in the custom section can be listed in the package.manifest file in the root directory (~\App_Plugins\CustomSection\package.manifest)
Custom pages
Sample umbraco resource
List page example
Example of search page that lists results with a loading indicator and paging. The umbraco-property element is an element I created to make managing the layout of fields.
Edit page template
Example editing page that displays a save and back button on a menu at the bottom of the screen, matching the layout used by Umbraco on its screens. There is also a loading indicator for display while the the entity is saving and loading.
Backoffice Api Controllers
Umbraco provides controller implementations that integrate with the Umbraco back office authentication, simplifying the process of securing the backoffice api and pages.
Umbraco backoffice Controllers:
UmbracoAuthorizedJsonController - Authorised umbraco backoffice api controller that is autorouted to “/umbraco/backoffice/api/{controller}/{action}”
UmbracoAuthorizedController - Authorised umbraco backoffice mvc controller that is manually routed.
Code snippets:
Paging service is a small utility class to handle common paging methods
As we’re supporting paging in the search screens, it is helpful to have some base classes that can be used as base classes when there’s custom parameters, or by themselves when there’s no extra search parameters. This object allows page, sorting parameter, sort order and page size to be set.
As with the request, we want a reusable class for returning the paging information, as well as including the list of items for the current page.
Building the response is will be a common process for everything returning a paged list, so we can put this in a common base clase.
And finally we use all that code to create a stub controller and its request class, that will respond to the requests from the frontend.