12 min read

Custom Macro Parameters with JavaScript

By Praecipio Consulting 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

*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

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. 

Topics: blog confluence javascript macros bespoke
1 min read

The Secure Content Macro for Confluence

By Praecipio Consulting on May 16, 2013 11:00:00 AM

That’s right, our highly anticipated Secure Content Macro is now available on the Atlassian Marketplace. Secure Content allows you to securely display sensitive data to the right people at the right time anywhere in Confluence.

How does it work?  Secure content blocks are stored, encrypted in the database, and are only decrypted when an authorized user provides their credentials. Users must be logged into Confluence to be able to decrypt a secure content block. Secure Content uses the currently logged in user and ensures that the provided password matches the user’s Confluence password. It’s that simple!

We’re thrilled for the release of this amazing plugin and hope you find it as useful as we have. Click here to download and begin collaborating in secret.

 

 

 

Topics: atlassian blog confluence marketplace secure-content-macro macros
7 min read

Team Calendars 2.3 Released

By Praecipio Consulting on Jun 26, 2012 11:00:00 AM

We’re excited to announce the release of Atlassian Confluence’s Team Calendars 2.3. For this Team Calendars release Atlassian focused a lot on helping you stay up to date with upcoming events in your team.

Here’s a list of highlights for this release…

Upcoming Events View

Atlassian’s created a new upcoming events view in the Team Calendars macro. It’s great for keeping your team informed of leave, travel or upcoming Jira project milestones. Embed it on your team homepage, or your project status page: 

 

Upcoming Events In Confluence Summary Email

Confluence 4.2 introduced weekly/daily summary email, helping you stay on top of popular and important content right from your email. Team Calendars now integrates nicely to these summary emails so you can stay updated with upcoming events in your team, project or company events right in your inbox: 

Learn more about using Jira Calendars to track your upcoming releases and issue dates.

 

Improved Confluence 4 Editor Experience

As of Team Calendars 2.2, Atlassian’s stopped adding new features for Confluence 3.5.x. You can now start taking advantage of all the new 4.0 editor plugin points.

Quickly Switch Calendar Views

Now that newer versions of Team Calendars support Confluence 4.0 or greater, you can start to make use of some of the Confluence 4.0 editor plugin points. So you can now quickly change calendar views using the editor property panel.

See Calendar Names

Previously, when you embedded a calendar on a page you would see something like “calendarID=349834j232″ in macro parameter list for the macro – which wasn’t helpful in identifying what calendars were embedded. As of Team Calendars 2.3, you will now see a preview of the calendar name(s) that you have embedded.

 
 

Other Improvements

  • For People Calendars, we now show the event summary in month and week views for some more context
  • To avoid any silly mistakes, Atlassian’s added a delete confirmation if you try to delete an event from the edit event dialog

Release Notices

  • Reminder: Team Calendars 2.2 was Atlassian’s last feature release for Confluence 3.5.x. Only critical bug fixes will be ported back to Team Calendars 2.2.x. These new features are available on Confluence 4.0 or greater.
  • The Email Summary Integration feature requires Confluence 4.2 or greater.

Upgrading to Team Calendars 2.3

Upgrading from a previous version of Team Calendars is straightforward. We recommend that you back up your Confluence database (which includes Team Calendars data) before upgrading.

  • In Confluence, simply click ‘Upgrade‘ in the Team Calendars entry of the Plugin Administration screen.
    Alternatively, download the latest release from our plugin exchange and install it via the Plugin Administration screen. This should upgrade Team Calendars to 2.3.0 (or higher).

Issues Resolved in this Release

 

 

Type
Key
Summary
Assignee
Reporter
Priority
Status
Resolution
Created
Updated
Due

 

 

 
TEAMCAL-652
Integrate with daily/weekly summary email
Matthew Erickson [Atlassian]
Matthew Erickson [Atlassian]
 
 Resolved
Fixed
22/May/12
23/May/12
 
 
TEAMCAL-116
Add new “Compact List View” to macro
David Chui [Atlassian]
Sherif Mansour [Atlassian]
 
 Resolved
Fixed
11/Jun/11
10/Jun/12
 
 
TEAMCAL-246
Add month, week and list view to Team Calendars macro properties panel
David Chui [Atlassian]
Bill Arconati [Atlassian]
 
 Resolved
Fixed
27/Jul/11
16/May/12
 
 
TEAMCAL-664
Constructing a mail should not result in resolving resources over HTTP
David Chui [Atlassian]
Fabian Kraemer [Atlassian]
 
 Resolved
Fixed
25/May/12
04/Jun/12
 
 
TEAMCAL-533
Adding a new calendar UX – clicking OK should give “Adding…” feedback.
Matthew Erickson [Atlassian]
Sherif Mansour [Atlassian]
 
 Resolved
Fixed
21/Feb/12
30/May/12
 
 
TEAMCAL-642
Macro placeholder image
David Chui [Atlassian]
Sherif Mansour [Atlassian]
 
 Resolved
Fixed
13/May/12
10/Jun/12
 
 
TEAMCAL-33
People calendar should show event description in month and week views
Matthew Erickson [Atlassian]
Sherif Mansour [Atlassian]
 
 Resolved
Fixed
24/Apr/11
10/Jun/12
 
 
TEAMCAL-634
Space picker when creating a new calendar should span the full width of the field
David Chui [Atlassian]
Sherif Mansour [Atlassian]
 
 Resolved
Fixed
08/May/12
28/May/12
 
 
TEAMCAL-605
Delete Confirmation Required in Event Edit Window too
Matthew Erickson [Atlassian]
Mark Russom
 
 Resolved
Fixed
12/Apr/12
30/May/12
 
 
TEAMCAL-668
‘Unable to format date/time’ error when viewing an event anonymously
David Chui [Atlassian]
Foo Guan Sim [Atlassian]
 
 Resolved
Fixed
28/May/12
28/May/12
Topics: jira atlassian blog calendars confluence release teams upgrade integration macros marketplace-apps
2 min read

Atlassian's Confluence 4.0 is HERE!

By Praecipio Consulting on Sep 20, 2011 11:00:00 AM

Introducing a New Standard in Content Collaboration

Confluence 4.0 is here! After more than a year of development, and many more years of listening to your feedback, we’re stoked to deliver you Confluence 4.0 – the fastest, richest, most intuitive collaboration experience ever.

Boost Adoption with a Brilliantly Simple Editor

The new editor in Confluence 4.0 is brilliantly simple, intuitive, and yet still packed with powerful features.

Completely Redesigned

A new streamlined toolbar puts new users at ease with familiar editing operations exactly where they’re expected. A single editor makes for a more reliable experience for your users and saved work that looks exactly like what was crafted in the editor. What you see is really what you get. 

Intelligent and Lightning Fast

While new users will feel at home with the new editor, power users will thrive on innovative new features like Autoformatting. In the blink of an eye, Confluence converts wiki markup to rich text as you type; careful, you might miss it! They’ll love the performance improvements we’ve made to Autocomplete, putting links, images, media, and hundreds of powerful macros a couple of keystrokes away. Not to mention all the new keyboard shortcuts we’ve added to give them a faster editing experience than ever before.

Familiarly Social

Confluence 4.0 takes team collaboration to the next level. Just like Twitter and Facebook, it’s easy to bring others into the conversations taking place in Confluence with @mentions. Whether you’re editing a page, replying to a comment or publishing a blog post, it’s never been easier to foster team collaboration around your content in Confluence.

Hundreds of New Features

This post barely scratches the surface of Confluence 4.0. Take the tour and learn about all the new features today!

Topics: atlassian blog confluence facebook twitter wiki collaboration features macros
2 min read

Atlassian: SharePoint Gets Social With Confluence

By Praecipio Consulting on Jun 7, 2011 11:00:00 AM

The latest release of the Atlassian’s Confluence SharePoint Connector is loaded with new features that turn SharePoint into the social collaboration platform you always wished it was. Best of all, it’s available for download today…here’s the scoop:

Unlock Documents and Lists stored in SharePoint
With Atlassian’s redesigned SharePoint list macro, anyone can insert their favorite SharePoint lists into Confluence without needing to know wiki markup.

1. Smarter SharePoint List Macro
New ‘Smart Fields’ for the ‘SharePoint List Macro’ in the Confluence ‘Macro Browser’ make light work of finding your ‘Lists’ from SharePoint and embedding them into a Confluence page for others to see.

2. Custom SharePoint List Views in Confluence
We’ve also made it easy for users to reuse the custom list views they’ve configured in SharePoint. Getting your personalized SharePoint experience in Confluence is now just a couple of keystrokes away.

Bring Social Collaboration into SharePoint
Experience the collaborative advantages of Confluence inside SharePoint like never before with new social features for SharePoint users.
1. Bring Confluence Blogs into SharePoint
A new Blog Post Web Part lets you bring the rich discussions and newsworthy content shared in Confluence, into SharePoint. And, with the power of Web Part Connections, you can connect a Blog Post Web Part to the new Blog Post Tree View Web Part. This lets SharePoint users browse all the blog posts in a Confluence Space directly from SharePoint. Now everyone can stay-up-to-date on the important announcements published in your intranet.

2. Post comments on Confluence content from SharePoint
Users can now make comments on the Confluence pages and blog posts they consume in SharePoint allowing more people to contribute to the conversations taking place inside your Confluence wiki.

For Administrators…
One-step Farm-wide Settings
We’re always striving to make the life of administrators easier. In this release we’ve added a huge time-saving feature – connecting your entire SharePoint farm to Confluence is now single-step process. Now when you add more SharePoint sites to your Farm, they’ll be automatically connected to your Confluence wiki.

Available Today!
There are even more improvements in the SharePoint Connector 1.4. Go get it, try it out, and let us know what you think. Check out the release notes here, or go ahead and download!

Topics: atlassian blog administrator confluence release sharepoint wiki collaboration download integration macros

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