Overview
Continuing off of last month's post entitled "Build an user macro in Confluence", this document will show you how to write an user macro that accepts input from the user. We will be creating an feature that allows for page redirects in Confluence. The macro will accept two inputs from the user: 1- page title to redirect the current page to and 2- delay before current page is redirect (which should include a default of 10 seconds). From there, the macro will display a basic redirect message, derived in part from the user's input, and load the target page after the delay has passed.For this tutorial, you should have completed either last month's tutorial and/or Guide to User Macro Templates, Velocity, and be comfortable with HTML and JavaScript.
Parameters
This user macro will take two user inputs: page title to redirect the current page to and a delay time. Let's take a look at these parameters and then break them down:
## @param URL:title=URL|type=string|required=true|desc=URL to redirect to.
## @param Time:title=Time|type=int|default=10|desc=Time to redirect (in seconds). Defaults to 10 seconds.
To declare a parameter, we use the
## @param <parameter name> definition. The parameter name can be anything as long as there are no spaces or starts with a number. It's a good habit to get into naming the parameter names by their purpose.Next, we have the title of the parameter. The parameter is displayed in the macro's properties when entering the value for the parameter. Here, you can use any combination of characters and spaces as you see fit. The title value should be human readable.
To help the Confluence user macro determine what kind of value it is using and to make the user macro more user friendly, we define the type of input we are providing to the user macro. For the URL parameter, we declare the type to be a basic string (which means the value can be anything). For the Time parameter, we set the type to be int (integer (numbers only)).
For the URL parameter, we set a property called required to be true which tells Confluence that this parameter is mandatory. Not setting this parameter will result in an undefined value and thus disable the macro under it is defined.
For the Time parameter, we use the default property to provide the macro with a default value of 10 (seconds). This is a convenience for the user as they won't need to enter a value unless they want to use something other than the default value.
The last property in both of these parameters is the description (desc). This is the text that will be displayed in the user macro window when filling out the various parameters. You should strive to keep it short, simple, and direct to the point.
Macro Browser Information
As mentioned in the previous tutorial, you don't necessarily need to fill out every field in this section of the user macro but you are required to at least fill out the Macro Name and Macro Title. The others are up to you fill out as needed. But for this user macro I included the following values:
- Macro Name: redirect
- Visibility: Visible to all users in the Macro Browser
- Macro Title: redirect
- Description: Redirect current page to a new URL within a user specified time (seconds).
- Categories: Navigation
Definition of User Macro
Since we won't be including any body information in this user macro, we'll set the Macro Body Processing to No macro body.
Template
For the template (code) of the user macro, we'll break it down into two sections: Setting Velocity variables and the rest of the code.
Setting Velocity variables
We set Velocity variable like this:
#set($variable=value)For our macro's delay, we need to use the following to set up the input variable as milliseconds:
#set($timeOut= $paramTime + "000")Here, we are setting the variable
$timeOut to be the value of the Time parameter which the user supplies in the macro or the macro provides via it's default value.Basic redirect message
Next, we need to set up the basic message that this page will redirect the current page to the target page.
<div id="redirectBox">This page will be redirected to <a href="$paramURL">$paramURL</a> in $paramTime seconds.</div>
Note the usage of the parameter variables and not the Velocity
$timeOut variable so far. The code provides the wiki page with a few elements that displays a basic redirect notice and provides the user with a link in case the redirect function doesn't work automatically or the user wants to forego the delay and visit the target page sooner than later.Redirect function
The last bit is the JavaScript function to redirect the page after the specified delay:
<script type="text/javascript">
function Redirect() {
window.location="$paramURL";
}
setTimeout('Redirect()', $timeOut);
</script>
Ideally, this JavaScript function would be included in a library that your Confluence server makes available globally but since it's a small and, hopefully, rarely used macro, it wouldn't hurt the page load time too much if we just include this function on every instance of the macro.
Complete macro code
## @param URL:title=URL|type=string|required=true|desc=URL to redirect to.
## @param Time:title=Time|type=int|default=10|desc=Time to redirect (in seconds). Defaults to 10 seconds.
#set($timeOut= $paramTime + "000")
<div id="redirectBox">This page will be redirected to <a href="$paramURL">$paramURL</a> in $paramTime seconds.</div>
<script type="text/javascript">
function Redirect() {
window.location="$paramURL";
}
setTimeout('Redirect()', $timeOut);
</script>
No comments:
Post a Comment