- Created by Robert Reiner, last modified on 10. Oct 2020
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.
/* * 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.
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.
/** * 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.
Configure the space category via the 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
Name | Short 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.