5 min read

Tips for a More Organized Confluence Space

By Praecipio on Aug 9, 2021 10:00:00 AM

1102x402 - Blog Featured (10)

What makes a great team? Is it the people, process, or tools used?

Of course, all three components are essential to make a successful team. But even with the right technology and incredibly talented people, sometimes you don’t always get the desired results.

This has been the case for the hugely popular Atlassian tool, Confluence. The online knowledge base and wiki solutions are of immense help for teams to get real-time hyper-access to all types of information from anywhere, anytime, and from any device. Confluence also provides a great way to build team collaboration and helps track all your essential documents with a centralized version control system. But not everyone seems to be using it to its fullest potential. Here are some excellent tips that can help you unlock the true potential of the tool.

Confluence Best Practices: What Is The Best Way To Organize Your Confluence Space?

Confluence serves as the centralized knowledge base across your organization. So, you have to understand that it is not just for personal use or for a particular team’s benefit. Everything stored in Confluence should be named and organized to make it easy to search for and navigate the topic in question. The main goal of Confluence is to make information sharing and knowledge discovery more accessible and more collaborative. Consider making your documents easy to find for anyone, even when they’re complete beginners to the system.

Here are some significant criteria you should keep in your mind when creating new Confluence pages and organizing your current information:

  • Information organization and structuring of your spaces and pages
  • Formatting and style
  • Ease of information gathering and search
  • Integrations with other tools

Why Does Having A Mature Confluence Space Matter?

So why is it essential to keep your Confluence Space neat and clean? Well, for starters, the very reason why you use Confluence is to make discovery and information-sharing easy. When pages and spaces are sloppy and disorganized, searching for information and keeping track of all the different versions of data stored in Confluence becomes too difficult.

Here are some reasons why you should always aim to maintain a mature confluence space:

  • A mature Confluence space is decluttered and helps you search for and make edits to the information quickly.
  • By reorganizing the page trees, you can identify obsolete pages and make sure they are correctly tagged to get accurate information.
  • With proper version control of your pages and documents, you can ensure that information is up-to-date and accurate.

A well-organized Confluence space can easily integrate with other Atlassian marketplace apps and efficiently incorporate page archiving, page discovery, and information identification.

When you have a well-organized Confluence:

  • It becomes easy to identify outdated data and take the necessary action to archive them or update them properly.
  • You’ll save disk space and lower database storage requirements by identifying duplicate data and removing old and inaccurate data from Confluence.
  • If your Confluence space is mature, deletion of data, identification of large attachments that are no longer needed, backup, and restoration become more efficient.

Some Tips On Decluttering Your Atlassian Confluence Space

Here are some tips to help you achieve a mature Confluence space required to make your team more efficient.

Start Making Use Of Spaces

Many beginners tend to create pages and store them in their Confluence just as a standalone document. This method can be an organizational mess when you have thousands of documents that range in topic from installation instructions to meeting notes stored in one space. Start creating and making use of spaces. Spaces help create an information hierarchy and act as a home for various types of content. Spaces are also a great way to implement effective content management and knowledge management within Confluence.

For instance, you can create a separate space for a particular project or team, Confluence allows you to create as many spaces as you want. It's important to remember to associate your pages with the relevant space to avoid orphan pages. You can also have team spaces, project spaces, and personal spaces. Once your spaces are ready, assign parent pages and child pages to organize the pages and form a meaningful content hierarchy.

Make Use Of Page Templates

Remember, when you add something to Confluence, it is not just for your use. It is shared, stored and versioned as more people access the document. So it makes sense to follow a proper structure and consistency to your documents. Use pre-defined templates or create a custom template that makes it easy for anyone to understand and navigate through a page quickly. You need to ensure that your pages are aptly formatted and easy to navigate. Making use of templates will help you achieve that and more by enforcing uniformity across your pages.

Space Layouts Help You Highlight The Most Important Content

When designing your templates and page content, use a hierarchy that will display the most critical content at the top to make it more visible to readers. You can also customize the space around the page to add custom sidebars and search bars or any custom macros to enable faster information discovery.

Categorize Your Spaces

By categorizing your spaces, you can help Confluence users get access to related information quickly. For instance, content marketing space, customer insights, user persona, and such can be grouped into the marketing category, whereas your project management documents can be grouped in another category.

Archive Old Pages

Eliminating old pages helps you maintain an organized page track and helps people find what they are looking for quickly. For example, if the user searches for a topic and finds two documents on the same topic, they might get confused about what to follow. Archiving old and outdated pages allows users to gain clarity and always receive the most up-to-date information.

Promote Collaboration And Engagement

Make it easy to share the confluence pages across your team members. Confluence can be of enormous help as a collaboration tool to create transparency at work and promote productivity. Allow users to get ownership of the confluence pages and enable sharing options. You can also promote internal blogging to enhance a transparent and open culture. You can also measure your engagement with the analytics functionality provided by Confluence to see the active reader count, most active users, the popular spaces, and common searches.

All this information can also help you build better Confluence governance and a user experience that fosters collaboration.

Creating a Confluence infrastructure to support your ITSM and other teams can be a time-consuming task, mainly as your organization is growing and information updates begin to be overwhelming. As an Atlassian Platinum Solution Partner, we'll help you get the most out of your infrastructure and enhance it to meet your business goals now and as your company grows. Contact us today!

Topics: confluence tips macros organization atlassian-products
12 min read

Custom Macro Parameters with JavaScript

By Praecipio on Mar 12, 2018 11:00:00 AM

Introduction 

Custom macros are a popular, supported, and versatile addition to any confluence page. Confluence users are able to use macros by making their own, searching the macro library, or by getting access to additional macros through add-ons. If you are making your own macro through an add-on, you will know that the parameter types, aka fields, are limited to the following: 

    • boolean - displays a check box.
    • enum - displays a select field.
    • string - displays an input field (this is the default if unknown type).
    • spacekey - displays an autocomplete field for search on space names.
    • attachment - displays an autocomplete field for search on attachment filenames.
    • username - displays an autocomplete field for search on username and full name.
    • confluence-content - displays an autocomplete field for search on page and blog titles.

Using JavaScript and Soy templates, you are able to inject custom parameters into a macro. The following tutorial is an example of a custom field injected into a basic macro form. The goal is to create a multi-select drop down menu comprised of static predetermined menu items. Note- JS functionality to create a multi-select list and the CSS are not included. 

 

Steps for injecting an element into a macro 

Building the macro

Example code of plugin.xml 

<xhtml-macro name="macro-list" key="macro-list" class="your.class.name"  documentation-url="#"
             icon="/path/to/yourPic.jpg">
    <category name="external-content"/>
    <parameters>
        <parameter name="User" type="username"/>
        <parameter name="Page" type="confluence-content"/>
        <parameter name="StatusSelect" type="string"/>
        <parameter name="Status" type="string"/>
        <parameter name="Width" type="percentage" default="100%"/>
        <parameter name="Max Results" type="int" default="30"/>
    </parameters>
</xhtml-macro>

 

Macro prior to injecting content

Edit DocuSign Envelope Screenshot

*Note: The "Status" parameter is not visible in this image. That is because the element is hidden with CSS. More on why the element is hidden in the JavaScript section. 

 

Configuring the Soy template multi-select code

{template .multiSelect}
    <div class="status-container">
        <div class="closed-status-margin status-selected-container macro-input-fields text">
            <span class="aui-icon aui-icon-small aui-iconfont-arrow-down select-icon" onclick="toggleStatuses()"></span>
        </div>
        <ul class="status-list hide-statuses">
            <li value="created" onclick="statusSelect(this)">Created</li>
            <li value="deleted" onclick="statusSelect(this)">Deleted</li>
            <li value="sent" onclick="statusSelect(this)">Sent</li>
            <li value="correct" onclick="statusSelect(this)">Correct</li>
        </ul>
    </div>
{/template}


JavaScript injection

JS code with explanation

//Run function on ajaxComplete to capture edit macro view.
$(document).ajaxComplete(function() {
    //looking for the macro-list macro to start running
    if( AJS.$("table[data-macro-name = 'macro-list']")){
            //must verify that the MacroBrowser is available to prevent errors
            if (AJS.MacroBrowser) {
            //override command that selectes the ds macro and the field/s selected
            AJS.MacroBrowser.setMacroJsOverride("macro-list", {
                fields: {
                    //calls anonymous function on string fields
                    "string": function (param) {
                        //checks specifically for the string input we want to inject to
                        if (param.name == "StatusSelect") {
                            //calls our function with the input's selected string param
                            return handleSpacesLookup(param);
                        }
                    }
                }
            });
        }
    }
});
//globally available but only called if the above criteria is met
function handleSpacesLookup() {
    //grabbing the div that surrounds our selected input/param
    var paramDiv = AJS.$(Confluence.Templates.MacroBrowser.macroParameterSelect());
     
    //create a variable for our desired template
    var docStatus = path.to.your.template.multiSelect();
     
    //setting a variable to the paramDiv that corresponds to our desired input area via ID
    var select = AJS.$("#macro-param-div-StatusSelect", paramDiv);
     
    //adding our docStatus element to the selected div
    paramDiv.append(docStatus);
 
    //return the selected/created element to the macro
    return AJS.MacroBrowser.Field(paramDiv, select);
};
  
//Functional logic for the multiselect not included.
 

Completed front-end example with JavaScript

Edit DocuSign Status Screenshot

Edit DocuSign List Screenshot

Why is the Status Parameter Gone? 

The drop down multi-select captures the user's selection on the front end. When passing the macro form information back to the server via the preview or the save button, the Status Select format is not readable. To make sure that your information is able to be parsed, you may insert relevant information into another macro field. In this case, the user's responses are sent to the hidden Status parameter each time he/she makes a change to the StatusSelect. On save or on preview, only the hidden information is sent to be parsed. 

 

Potential Issues 

  • I only see an empty field when opening the edit macro, I can only see my field when reloading the page with the editable macro, OR I am getting null variable errors. 

    This may be a JS async error, which could explain some inconsistencies. Make sure that this JS file is accessible to the page, that functions are properly nested, and that the initial if clause is triggered as expected. The edit screen and dialog boxes are not connected to a page reload so queries done "on load" of the page will not be caught at this point. Use .ajaxComplete or an event trigger to re-run necessary functions. 

  • My new element works but now I am missing functionality from other parts of my page.

    Make sure that your selectors are unique and as specific as possible. Try to limit using css and JS selectors by the AUI class names as these are repeated through out Confluence. 

  • I am appending my element but only see a blank input box. 

    Your parameter type may limit the content that can be appended to it. For example, select lists cannot have non-option items added to it and will instead render a broken input box. Confirm that your template has the appropriate wrappers if any. You may need to append your template to the container instead of the parameter. 

At Praecipio Consulting, we know that using Javascript can be tricky. Let us help you with any issues you come across while building your macro. Contact us with questions and concerns.

Topics: blog confluence tips javascript macros bespoke

Praecipio Consulting is an Atlassian Platinum Partner

This means that we have the most experience working with Atlassian tools and have insight into new products, features, and beta testing. Through our profound knowledge of Atlassian environments and their intricacies, we can guide your organization as you navigate these important changes.

Atlassian-Platinum-Solution-Partner

In need of professional assistance?

WE'VE GOT YOUR BACK

Contact Us