Set Flag

The Set Flag macro sets, unsets or removes a flag, which can then be read by Panel Show, Panel Hideand any other ThemeBuilder macro through the flag and notflag parameters.

The macro renders nothing on the page.

Root Skin Location

In ThemeBuilder, ROOT skin flags are set in the flagLogic panel. ThemeBuilder renders that panelbefore the rest of the skin, so flags set there are available everywhere. See Flag Logic in Skins.

Usage

Follow the steps below to insert a Set Flag Macro on your page:

Go to a page where you want to add the Set Flag Macro.
Click the Insert More Content dropdown menu and choose Other Macros.
Type set flag in the search bar and select Set Flag from the results.
Fill in the desired parameters.

Storage Format

<ac:macro ac:name="set-flag">
<ac:parameter ac:name="name">value</ac:parameter>
</ac:macro>

Wiki Markup

{set-flag:name=myflag}

In wiki markup you can also give the name as the first unnamed parameter, which is the form used in most examples:

{set-flag:myflag}


Parameter	Name	Description	Type	Default	Required
name	Name	The flag name. Case sensitive. In wiki markup this may be given as the first unnamed parameter.	string	-	Yes
state	State	What to do with the flag: true — set the flag false — store an explicit false, which unsets the flag and masks any value held by a longer-lived target remove — delete the stored value, letting any longer-lived target show through again	enum	true	No
type	Type	Which target to store the flag against: `request`, `session`, `user`, `page`, `space` or `global`. See Flag Targets.	enum	request	No
flag	Flag	A list of flags, one of which must be set for this macro to run.	string	-	No
notflag	Not Flag	A list of flags, none of which may be set for this macro to run.	string	-	No

name is the only parameter you must supply — the macro reports an error without it. Any value ofstate other than false or remove is treated as true, and an unrecognised type falls backto request.

flag and notflag apply to the Set Flag macro itself, which is how you make one flag depend onanother without wrapping it in a Panel Show macro:

{set-flag:show-edit|flag=registered-user|notflag=top-level-page}

Things to know

`type` decides how long the flag lives

Omitting type gives you a request flag, which lasts for a single page load. That is the rightchoice for skin logic. Use session, user, page, space or global when the flag needs tooutlive the request — for example a user's sidebar preference (user) or a site-wide banner(global).

Writing to page, space or global requires permission (edit on the page, space administer, orConfluence administrator respectively), and user requires the visitor to be logged in. If theuser doesn't have the required permission the macro does nothing and reports no error.

Setting a flag clears shorter-lived copies of it

Before storing the new value, the macro removes the flag from the target you chose and from everyshorter-lived target above it in the priority order. So {set-flag:sidebar|type=user} first clearsany request and session value of sidebar, then stores true against the user. This makessure the value you just set is the one that gets read back.

`state=false` and `state=remove` are different

false stores a value. Because reading a flag stops at the first target that holds a value, astored false hides anything set against a longer-lived target — which is what makes it useful forasserting defaults at the top of your flagLogic panel.

remove deletes the value instead, so a longer-lived target becomes visible again. Withtype=global, or with no type at all, remove clears the flag from all six targets at once.

There is no `clear` parameter

Older examples show {set-flag:myflag|clear=true}. clear has never been a Set Flag parameter, andunknown parameters are ignored — so that markup sets myflag to true. Use{set-flag:myflag|state=false} or {set-flag:myflag|state=remove} instead.

Only some flags reach your CSS

Request, session and user flags add a flag-FLAGNAME class to the <body> element. Page, space andglobal flags do not, even though they still work in flag and notflag conditions. See CSS Customization with Flags.

Read-only mode

In Confluence Data Center read-only mode the macro renders nothing and sets no flag.

Example

Set a simple flag.

<ac:macro ac:name="set-flag">
<ac:parameter ac:name="name">myflag</ac:parameter>
<ac:parameter ac:name="state">true</ac:parameter>
</ac:macro>
{set-flag:name=myflag|state=true}

Setting this simple flag will result in the following:

With ThemeBuilder Debug turned on, you can see the flags in use in the page source code.