Org Documentor - Custom Header Colors

Tweet

 

Overview

In my last post about the Org Documentor, I detailed the first customisation option for the template content outside of the actual org detail - the title and subtitle of the header page. Something that also seemed useful to configure was the header background colour and text colour - I like the current purple/dark grey combo, but I can't imagine everyone does.

What I wasn't sure about at the time was how to go about this. The colours come from the styles.ejs file, which is included into the various templates as required. I didn't want to move away from this to have specific style stanzas in the template itself, so considered rewriting the styles file. The downside to this was it would leave me able to override the colour once, which would apply to all pages, whereas I liked the idea of being able to override at any level.

And I've used the US spelling in the title of this post, and for my property names, as otherwise it jars against the CSS names. Hate on me if you want.

Solution

So I did some digging around what was possible when including files in EJS, and it turned out I needn't have worried. I can pass a JavaScript object as part of the include call, and use the properties of this just like I would in the main template:

   <%- include ('./common/styles', {header: content.header}) %>

While it might seem like a simple change to add a header property to the JavaScript object being passed to the template, there was a little more to it as:

• This is a Salesforce CLI plug-in, and is written in Typescript. This means that if I want to add properties to an object, I have to declare them, as opposed to JavaScript where I'd just chuck them on the end.
• I want to be able to override the header colours on a per-page basis, falling back on the parent page if no override is defined, and eventually falling back on default values, which meant I needed to add this to every one of my content objects that generates the documentation pages. 

First off I defined the HeaderStyle custom type:

interface HeaderStyle {
    backgroundColor: string;
    color: string;
}

Once I have this, I can add a property to each of my content types:

interface IndexContent {
    links: Array<ContentLink>;
    title: string;
    subtitle: string;
    header: HeaderStyle;
}

Note: there are other options around this in Typescript - I could define the property type as any, which would allow me to put whatever I like in there, much like regular JavaScript. A benefit of strong typing is that VS Code flags up anywhere I've used my content types but haven't added the header property, which saves me figuring it out manually.

I then changed the code that processes the configuration file to look for backgroundColor and color entries at the top level, at each processor level (objects, triggers, auraenabled) and at each group level, defaulting the values from the parent, if defined, and eventually falling back on the standard colours.

Finally, I updated the configuration file of my sample Salesforce metadata to override the objects page:

{

    "title": "Instance Overview",
    "subtitle": "From the metadata source",
    "objects": {
        "name": "objects",
        "description": "Custom Objects", 
        "backgroundColor" : "#ff8b00",
        "color": "#ffffff",
           ...
    }

and after generating my report, I get the default on the Home and most other pages:

while on the objects page, I get a particularly fetching orange background:

choose your colours with care though, as right now the breadcrumb is using the default bootstrap colours, so it's easy to make it hard to see.

Updated Plug-in

Version 3.4.4 of the plug-in has this new functionality and can be found on NPM. 

If you already have the plug-in installed, just run sfdx plugins:update to upgrade to 3.4.4 - run sfdx plugins once you have done that to check the version.

if you aren't already using it, check out the dedicated page to read more about how to install and configure it.

The source code for the plug-in can be found in the Github repository.

Related Posts

• The plug-in on NPMJS
• Documentation generated from the sample metadata
• Sample metadata repository
• Plug-in source repository
• Org Documentor - A Little More Configuration
• Org Documentor - Fields Usage in Page Layout
• Org Documentor and AuraEnabled Classes
• Documentor Plugin - Triggers (and Bootstrap)
• Documenting from the metadata source with a Salesforce CLI Plug-in - Part 5
• Documenting from the metadata source with a Salesforce CLI Plug-in - Part 4
• Documenting from the metadata source with a Salesforce CLI Plug-In - Part 3
• Documenting from the metadata source with a Salesforce CLI Plug-In - Part 2
• Documenting from the metadata source with a Salesforce CLI Plug-In - Part 1
• Offline mobile app template plug-in Dreamforce 18 session
• Salesforce CLI Play-by-Play
• Salesforce CLI Cheat Sheet

Follow @bob_buzzard