projectdoc Toolbox

Renders a vertical banner on the left side of a Confluence page with space information fetched from a projectdoc service.

Tags
Identifier
de.smartics.userscripts.confluence.vertical-banner-projectdoc
Type
Repository
Since
1.0

The script renders a vertical banner with the subject defined for the space on the left side of every page.

The banner contains text if the padding of the page is larger than the given threshold. If not, the banner is only a few pixel wide in the specified color.

The script renders class attributes that can be used to alter the styles applied to the banner.

Code

The code of the script for reference.

vertical-banner-projectdoc.js
/*
 * Copyright 2019-2024 Kronseder & Reiner GmbH, smartics
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
"use strict";

AJS.toInit(function () {
  const API_URL = "/rest/projectdoc/1";
  const logToConsole = false;
  const bannerWidthWithLabel = 32;
  const bannerWidthWithoutLabel = 6;

  if (logToConsole) {
    AJS.log("[vertical-banner] Locating ...");
  }

  const $main = AJS.$("#main");
  if ($main.length) {
    const fetchSpaceCategory = function () {
      const baseUrl = AJS.Meta.get('base-url');
      const spaceKey = AJS.Meta.get('space-key');

      const i18n = PDBMLS.fetchI18n(baseUrl, ["subject"]);
      const spaceSubjectPropertyName = i18n["subject"];
      const url = baseUrl + API_URL + "/space/" + encodeURIComponent(spaceKey) + "/property/" + encodeURIComponent(spaceSubjectPropertyName) + ".json";
      let spaceCategory = AJS.Meta.get('space-name');
      AJS.$.ajax({
        url: url,
        async: false,
        contentType: 'application/json'
      }).success(function (data) {
        AJS.log("[vertical-banner] Data: " + JSON.stringify(data));
        spaceCategory = data["value"];
      }).error(function (jqXHR, textStatus) {
        AJS.log("[vertical-banner] Error fetching space category: " + textStatus);
      });
      AJS.log("[vertical-banner] Returning: " + spaceCategory);
      return spaceCategory;
    }

    const encodeCss = function (prefix, input) {
      return prefix + "-" + input.replace(/[^a-z0-9_-]/g, function (string) {
        var char = string.charCodeAt(0);
        if (char === 32) {
          return '-';
        }
        if (char >= 65 && char <= 90) {
          return string.toLowerCase();
        } else {
          return '_';
        }
      });
    };

    const paddingLeft = parseInt($main.css("padding-left").replace('px', ''));
    const minWidth = paddingLeft > bannerWidthWithLabel ? bannerWidthWithLabel : bannerWidthWithoutLabel;
    const $sidebarContainer = AJS.$("#sidebar-container");
    if ($sidebarContainer.length) {
      const spaceCategory = fetchSpaceCategory();
      if (spaceCategory) {
        const sizeCss = minWidth == bannerWidthWithLabel ? "large" : "small";
        const $banner = AJS.$("<div id=\"userscripts-vertical-banner\"></div>\n");
        const spaceCategoryCss = encodeCss("projectdoc", spaceCategory);
        $banner.addClass("projectdoc-" + sizeCss);
        $banner.addClass(spaceCategoryCss);

        if (minWidth == bannerWidthWithLabel) {
          const $label = AJS.$("<div id=\"userscripts-vertical-banner-label\"></div>\n");
          $label.addClass(spaceCategoryCss);
          $label.text(spaceCategory);
          $banner.append($label);
        }
        $sidebarContainer.append($banner);
      }
    }
  }
})
;

Details

More information on using this userscript.

Banner Rendering

If the page provides enough padding, the banner contains the name of space. If the padding is too thin, only a thin line is rendered.

Screenshot showing the banner with space subject on the left.Screenshot showing the banner without label on the left.

In case the space defines no Subject property, the space name is rendered as default.

Requirements

The script requires the following apps to be installed on Confluence.

The projectdoc Toolbox for Atlassian Confluence
The projectdoc Toolbox supports agile teams in writing project documentation collaboratively. This is an introduction to use cases for and features of the projectdoc Toolbox.
Web API Extension
Add-on to extend projectdoc with an API to access on the web.
Bookmarklets Extension
Add-on to extend the Toolkit with Bookmarklets. Allows to execute tools via the browser.

Style Sheet

There is a CSS style sheet to be used as a template to configure the banner.

vertical-banner-projectdoc.css
/**
 * Copyright 2019-2020 Kronseder & Reiner GmbH, smartics
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
#userscripts-vertical-banner {
    background-color: blueviolet;

    visibility: visible;
    display: block;
    position: absolute;
    z-index: 100;
    min-height: -webkit-fill-available;
    top: 0;
    left: 0;
    margin-top: 0;
    margin-left: 0;
}

#userscripts-vertical-banner.projectdoc-small {
    min-width: 6px;
    max-width: 6px;
}

#userscripts-vertical-banner.projectdoc-large {
    min-width: 32px;
    max-width: 32px;
}

#userscripts-vertical-banner-label {
    color: white;
    font: bold 12px Sans-Serif;
    letter-spacing: 2px;
    line-height: 24px;
    text-transform: uppercase;
    transform-origin: 0 0;
    transform: rotate(-90deg);

    position: sticky;
    z-index: 200;
    width: 30em;
    height: 100%;
    margin-top: 400px;
    margin-left: 5px;
}

The userscript renders a class with the lower-cased subject name (invalid chars are replaced with an underscore, spaces by a dash) with a "projectdoc-" prefix.

 

Glossary is translated to projectdoc-glossary.

Space Repository is translated to projectdoc-space-repository.

Modify the CSS rules according to your needs. Add these rules either to the global space stylesheet or to the stylesheet of a single space.

 

For more information on using CSS with Confluence, please refer to Styling Confluence with CSS

Configuration of Userscript

Typically the banner is not required for every space of a Confluence site. To activate the script for specific spaces, the userscripts administrator may define a space category, like banner, to be set.

Screenshot of the REST API Browser with the configuration for this userscript.

Configure the space category via the Space Tools.

Screenshot with Space Details on Space Tools.

Once the categories contain a category 'banner', as specified in the activation record via activation-space-categories, the banner will be shown on every page of that space.

Related Scripts

NameShort Description
Vertical Banner
Renders a vertical banner on the left side of a Confluence page.

Resources

More information on this topic is available by the following resources.

Vertical Banner
Renders a vertical banner on the left side of a Confluence page.
The projectdoc Toolbox for Atlassian Confluence
The projectdoc Toolbox supports agile teams in writing project documentation collaboratively. This is an introduction to use cases for and features of the projectdoc Toolbox.