If you have a few add-ons, it's good to make the Settings a consistent layout and behavior across them. It's good for the add-on user, since they can go between your add-ons and immediately understand how everything fits together. All my recent add-ons use the same code for their settings, and they all work the same way. The first one took a while to get right, but afterwards it was just a question of configuration using exactly the same code.
Firstly, I use Material Design in all add-ons. The framework I use is muicss , but there are a few out there and it's mainly just a question of replacing the class names with the equivalent ones from the framework you are using. muicss is less complete and fancy than some of the others, but it's very simple to use and what there is seems to be rock solid.
If you're using muicss, you'll need these in your project
For this post, I'll use my Dicers add-on, but my other add-ons have exactly the same layout and use the same code.
The root settings screen looks like this
Each of these selectors lead to more screens, and so on recursively.
Creating an elementer is simply this, where setup is the object containing the setting configuration.
The Html is as follows.
elementer-root is the Div that's activated when the Settings tab is activated
All of the elements managed by the Elementer are kept in a flat structure, even though the layout can be a tree structure of any depth. This means that moving settings from one page to another is simply a layout configuration option. Your code to access the contents of these elements doesn't need to change regardless of where in the Settings screens your target element appears.
That's why you see these.
Detail describes the elements to be created, and layout describes where to put them.
Here's an extract of layout for the first page of settings
which produces this. You'll see that each member of items, refers to a row in the settings page.
The items refer to properties of the detail object, which can be actual Dom elements or further pages of settings. Let's look at a couple.
creates this ,
And so on. You can see here that some of the items go on to generate actual Dom elements, and the "colors" item, whose layout looks like this
creates yet another screen that looks like this
Navigation is automatically handled by the elementer, and there is the option of allowing it to generate back icons to get back to the previous page, or you can add a specific back button. Since I allow the viewing of the effect of the settings before necessarily applying them, I instead have a specific back button, and an apply button (which becomes active if any changes happen), which commits the changes.
That means that we need to be able to potentially call back some code when a screen is entered or exited. You'll have noticed the .on property in some of these configurations. I use this same pattern on all my pages to save the current values on entry to that page, and to reset them on exit. This simple approach means that the user can flip over to other tabs in the middle of changing settings to see what the changes look like before committing to them with the Apply button.
Of course both these buttons are automatically generated by the Elementer configuration too. You'll see "resetButton_colors" is included in the layout item list, and it is defined like this
You'll have noticed that templates are referred to in some of the configuration detail items. All the usual ones are already set up in the Elementer. It's the use of these templates that maintains a consistent look to all the settings pages across all the add-ons.
Here's an example.
Any of the template properties can be overridden in the detail of course, as in this example.
as opposed to the more usual
both of which reference this template
and are part of a page that looks like this
Of course I've only scratched the surface of how to use and configure this very useful capability. I used to find the creation and layout of many settings and the management of them throughout the code, the most laborious and error prone part of any project, but nowadays it's very quick and easy, is usually right first time, and of course it's very easy to move stuff around as you protoype different layouts.
I'll be writing this up in more detail in further posts, and of course the code is on github as usual. In the meantime if this has piqued your interest and you want a bit of guidance on getting started, then contact me and I'll see if I can help.
Services > Desktop Liberation - the definitive resource for Google Apps Script and Microsoft Office automation > Add-ons >