Skip to end of metadata
Go to start of metadata

The following page is a detailed overview of the Form Mail Macros and provides information on how to use them

Mail Form Macros

mail-form

This is the encompassing form within which all the other macros must be placed. The other macros will have undocumented behaviour in cases where they are placed outside of a {mail-form} macro. The form can either be linked to a configuration by id, have it's settings provided in parameters and encapsulated macros, or indeed both where the settings override that of the configuration.

Parameter

Description

Type

Default

Required

id

The Form Mail configuration ID - from the list of Form Mails in Confluence Administration

string

none

 

collector

Email or Bandana Caution: The Bandana setting stores emails on your Confluence server and is currently an unsupported feature.

string (email / bandana)

email

 

destination

Either the email address or the Form Mail ID or Confluence username(~username).

string

none

(unless valid id provided)

SubjectThe subject of outgoing mail from the mail form. stringnone 

 


mail-fieldset

A container to group related elements in a form. Adding a legend includes a custom text title with each group.

Parameter

Description

Type

Default

Required

legend

Include a legend title with this fieldset.

string

none

 

groupFields

Used for radio buttons and checkboxes to group options to the right of the legend or title.

boolean

false

 

Example

Showing a fieldset macro used to collect form fields into sections that can be described with 'legend' text. This helps to break up long forms into more manageable chunks.

Using 'group' will set the legend text beside a set of radio buttons or checkboxes. The default is above the form fields.



mail-input

This provides an input field synonymous to a HTML input field and has no body. Has label and description parameters to associate this information directly with each input.

Notes:

  • Use the same name for each input to create radio or checkbox groups. For a radio group this means only one option can be selected.
  • Only one input in each radio or checkbox group needs to be set to 'Required' for that field to be required.

Parameter

Description

Value

Default

Required

type

Type of Field

string (text / checkbox / radio / hidden)

none

 

name

Name of Field (also used as HTML node name)

string

none

 

id

HTML ID of Field (unused by FormMailNG)

string

none

 

value

Initial value of the Field

string

none

 

vtlValue

A Velocity value related to the Confluence user or page context. (overrides the above), see Available Velocity Context

velocity template string

none

 

validation

Validation mode, see Validation

string

none

 

labelTextText for Label associated with this fieldstringnone 
inputDescText for Description associated with this fieldstringnone 

required

Is this field require a value?

boolean

false

 

disabled

Is this field disabled from user interaction?

boolean

false

 

checked

Inital State (only valid for type=checkbox/radio)

boolean

false

 

cssClass

HTML CSS Class value

string

none

 

cssStyle

HTML CSS Style value

string

none

 

Example

Showing use of labels and descriptions with text input, radio buttons and checkboxes.

For more details on please see Checkboxes, Radio Buttons and Fieldsets


mail-select

This provides an select field (drop-down list) synonymous to a HTML select field, with options defined in it's body by the {mail-option} macro. Has label and description parameters to associate this information directly with each select.

Use this as a wrapper macro for mail-option macros.

Parameter

Description

Value

Default

Required

name

Name of Field (also used as HTML node name)

string

none

 

id

HTML ID of Field (unused by FormMailNG)

string

none

 

validation

Validation mode, see Validation

string

none

 

labelTextText for Label associated with this fieldstringnone 
inputDescText for Description associated with this fieldstringnone 

required

Is this field require a value?

boolean

false

 

disabled

Is this field disabled from user interaction?

boolean

false

 

nullLabel

The text for the option at the top of the select list

string

none

 

cssClass

HTML CSS Class value

string

none

 

cssStyle

HTML CSS Style value

string

none

 

Example

Showing a dropdown select with label text and the 'null option' text as the first select item.

 


mail-option

This provides an option field synonymous to a HTML option field, its body is wiki rendered and is the outputted label for the option.

Use inside a mail-select macro.

Parameter

Description

Value

Default

Required

value

Value of the Field

string

empty

 

selected

Is this Option Selected

boolean

false

 

Example

See mail-select

For details please see Drop Down Select Lists

 


mail-textarea

This provides an textarea field synonymous to a HTML textarea field, with the unrendered body being it's value. Has label and description parameters to associate this information directly with each textarea.

Parameter

Description

Value

Default

Required

name

Name of Field (also used as HTML node name)

string

none

 

id

HTML ID of Field (unused by FormMailNG)

string

none

 

validation

Validation mode, see Validation

string

none

 

labelTextText for Label associated with this fieldstringnone 
inputDescText for Description associated with this fieldstringnone 

required

Is this field require a value?

boolean

false

 

disabled

Is this field disabled from user interaction?

boolean

false

 

cssClass

HTML CSS Class value

string

none

 

cssStyle

HTML CSS Style value

string

none

 

Example

Showing text area field with label text and description

For more details, please see Text Area


mail-datepicker

This provides an input field synonymous to a HTML date picker, when clicked on the field, a calendar drop-down will appear

ParameterDescriptionValueDefaultRequired
Date FormatOutput format of dates

dd/mm/yyyy

mm/dd/yyyy

none(tick)
nameName of fieldstringnone(tick)
IdHTML ID of Fieldstringnone 
labelTextText for Label associated with this fieldstringnone 
inputDescText for Description associated with this fieldstringnone 
requiredIs this field require a value?booleanfalse 
labelwidthOptional custom label width or left marginstringnone 
cssClassHTML CSS Class valuestringnone 
cssStyleHTML CSS Style valuestringnone 

Example:

For more details please see Date Picker


 

mail-outgoing parameter

This provides a drop-down list with options of destinations to which the mail form can be sent.

ParameterDescriptionValueDefaultRequired
labelText for Label associated with this fieldstringnone(tick)
labelwidthOptional custom label width or left marginstringnone 
inputDescText for Description associated with this fieldstringnone 
cssClassHTML CSS Class valuestringnone 
cssStyleHTML CSS Style valuestringnone 

mail-destination

This allows you to set the destination of mail sent via the mail form

Use inside a mail-outgoing parameter macro

ParameterDescriptionValueDefaultRequired
labelText for Label associated with this fieldstringnone(tick)
destinationcomma separated list of email addresses & form mail ID'sstringnone 
subjectSubject for outgoing mailstringnone 
successsuccess message to be displayed on submitting the formstringnone 

Example:

For more details, please see Destination & Subject of Form Responses



mail-label

This provides a label element synonymous to a HTML label element, its body is wiki rendered and is used as the label element's contents.

Note: All field macros now have a label parameter which should be used instead of this macro. Macro retained for legacy support.

Parameter

Description

Value

Default

Required

for

Field ID this label is for

string

empty

 

Example

Showing the label macro used with an input field. Note how this does not line up as neatly as the recommended 'label' option included with all field macros.

 


mail-success

On submitting the mail form, any content given in the mail success macro will be displayed on the page. 

Mail Success macro over-writes the Success message given when setting up your Form Mail in the "Form Mail Configuration" Section

Example : 

Showing the body of the mail-success macro 

The success message that appears after submitting the form.

 


 

mail-captcha

Adds the Captcha challenge image and input field into the form. This is required if your Confluence has Captcha enabled.

You must have the Confluence Captcha turned on to use this macro. See  https://confluence.atlassian.com/display/DOC/Configuring+Captcha+for+Spam+Prevention

Example

Showing the captcha in place on a form

For more details, please see Spam Prevention


mail-submit

This provides a submit button synonymous to a HTML submit button. While there is no requirement for a button to exist, there wouldn't be any other way for the user to submit the form. Has an optional reset form link.

Parameter

Description

Value

Default

Required

name

Button Text

string

Submit

 

cssClass

HTML CSS Class value

string

none

 

cssStyle

HTML CSS Style value

string

none

 

resetButtonAdd Reset Buttonbooleanfalse 
receiptSend a copy of the sent email to the user who clicks the submit buttonbooleanfalse 

Example

Showing a form submit button with customised text and a form reset link.


mail-submit-img

This provides an image based submit button. Has an optional reset button.

Parameter

Description

Value

Default

Required

src

Image URL

string

 

alt

Alt Text for the image

string

 

cssClass

HTML CSS Class value

string

 

cssStyle

HTML CSS Style value

string

 

resetButton

Add Reset Button

boolean

false

Example

Showing an image used as the submit button.

 


mail-body-formatter

Create templates for the output of a forms response

Parameter

Description

none

The mail body formatter macro allows you to set a template for all outgoing mail from the current mail form.

You can access the value of a macros on the page using #macro-name, which will taken the inserted value when the user presses the submit button.

The default button will reset the contents of the mail body formatter macro to form mails default output template.

 

 


Validation

The validation is all performed client-side.
The validation parameter for the {form-input}, {form-select} and {form-textarea} macros take the following values:

Validator

Requirement

Invalid Message

alpha

a-z / A-Z

This field can only contain letters.

num

0-9

This field can only contain numbers.

alphanum

a-z / A-Z / 0-9

This field can only contain letters and numbers.

email

Email Address

Invalid Email Address.

If validation fails, the invalid CSS class is added to the offending field and, if attempting to submit, then a message box listing the errors and their corresponding field names is shown.

Available Velocity Context

A Velocity value related to the Confluence user or page context.

When rendering a VTL value (via the vtlValue parameter or when using render=velocity) you will want to know what context variables are available:

Variable

Injected By

Value

$user

Form Mail NG

AuthenticatedUserThreadLocal.getUser()

$ceo

Form Mail NG

((PageContext) renderContext).getEntity()

$req

Confluence

HTTPServletRequest

  • No labels