Changing content or style in Portal UI

Themes
1

To save others the journey, here’s what I’ve learnt trying to make changes to the content/style of the out-of-the-box Portal UI.

I’ve been surprised and pleased that I’ve been able to make relatively large scale customisations to the default site appearance without resorting to replacing the Casper Theme with a custom variant. I’ve been able to apply colour schemes, reposition elements, style images, change text, modify icons and even add minor animations, just by adding CSS and Javascript to Code injection.

The same cannot be said for the Portal. It provides a tremendous amount of out-of-the-box functionality, but because it is loaded dynamically into an iframe using an external js file, Code injection just can’t quite get the job done. Even waiting in JavaScript for the dynamic ghost-portal-root div to be added, and then catching when the dynamic pop-up iframe is added, the contents of the frame are still empty at that point. So modifying DOM elements or even editing the style is impractically convoluted.

Instead, the procedure described here is a good alternative. In summary:

git clone https://github.com/TryGhost/Portal.git
cd Portal
npm install --global yarn
yarn
# make changes to Portal source, then
yarn build

The docs then say to put the resulting umd/portal.min.js file in your theme folder under assets/built/. The seems non-ideal because I think:

  1. Portal is deliberately not part of the theme
  2. it will get overridden when the theme (and probably Ghost itself) is updated, and
  3. it would be a pity to have to modify the theme just for this.

I spent ages trying to figure out what other paths might be accessible via URL and even resolved at one point to serve it via a different, dedicated nginx site (on the same server). But the modern fixation with SSL-for-all put that in the too hard basket, so my fallback was to put it under a dedicated folder in content/images. Although the name “images” is not great, that path is one of the few accessible by URL, is self-contained within the Ghost site, and is a normal part of backing up/copying/upgrading a Ghost site.

So the last step was simply to add this to the bottom of config.production.json:

 "portal": {
    "url": "https://www.mysite.com/content/images/other/portal.min.js"
  }

and restart Ghost. Voila, the Portal has my ever so slight changes.

It turns out my changes are implementable by improving Portal itself, so I’ve submitted a PR.

2 Likes