Search the Confluence 4.1.x Documentation:

Index
Downloads (PDF, HTML & XML formats)
Other versions

This documentation relates to Confluence 4.1.x
If you are using an earlier version, please view the previous versions of the Confluence documentation and select the relevant version.
Skip to end of metadata
Comment: Corrected links that should have been relative instead of absolute.
Go to start of metadata

Please note, form field markup should only be used in templates. It does not work in wiki pages.

Templates are written using wiki markup, with special markup to insert form fields. When a user creates a page using a template that contains form fields, the user will be prompted to key in data. The data will be captured and stored in the new page.

Here are the three kinds of form fields supported and the markup to create them:

Text field 

@VAR@


Creates a text input field for a variable called VAR.

Text area 

@VAR|textarea(5,10)@


Creates a 5 x 10 text-area for a variable called VAR.

Drop down menu 

@VAR|list(one,two,three,four)@


Creates a drop-down box containing the values "one", "two", "three" and "four".
Note: The values in the drop-down list can only contain letters, numbers and underscores.
The dropdown list values cannot include:

  • special characters, such as '&'
  • punctuation marks, such as ':'
  • brackets, such as ')'

Every input field must have a unique name. If you have more than one text input field in the same template with the same name, Confluence will make sure that they all end up with the same value (This is useful if you need the same information in more than one place in the page).

For an example, please see Adding a Template.

Warning

There must be no spaces between the @-signs in the markup. This means you can't have items in your drop-down lists that contain spaces.


Improved Markup

The above formatting is the basic markup bundled with Confluence, but some plugins expand on this markup to provide greater functionality. Links to these plugins and a comparison can be found in the Working with Templates.

Related Topics

Working with Templates
Scaffolding Plugin
Adding a Template
Editing a template
Creating a Page using a Template

Take me back to Confluence User's Guide

60 Comments

Hide/Show Comments

  1. Sep 10, 2008

    Burke Mamlin

    Is it possible to change the size of a text input field in a template?  I tried  (VAR|textfield(50)),  (VAR|text(50)),  (VAR|size(50)),  (VAR|length(50)),  (VAR|50), and  (VAR|(50)) with no success.  The default text field size is too small when I want to ask for a phrase or sentence.  Since you can control the size of the textarea, it only seems logical that you could do the same with the textfield. (smile)

    I tried searching/googling.  Maybe I'm just overlooking something simple?

    1. Sep 16, 2008

      Azwandi Mohd Aris [Atlassian]

      Hi Burke,

      Currently, only the size of text areas can be specified in the template markup. There is an improvement request on this at CONF-1475. Feel free to put your comments, be a watcher and cast your vote to increase the popularity of the request. Also, please bear in mind on how we schedule new features in our product. Hope that helps.

      Cheers,
      Azwandi

  2. Sep 12, 2008

    Anonymous

    I'm trying to create a variable inside of a link in a template:

    *

     In all of these cases, the variable gets treated as the link or file name by the template, so rather than getting in input box, they get @filename1@

    Escaping the brackets/exclaimation points doesn't work either. Any suggestions?

    1. Sep 22, 2008

      Azwandi Mohd Aris [Atlassian]

      Hi there,

      As far as I am concerned, this is due to the priority in Confluence to render the wiki markup over the template field markup. However, you can try to add another field with the same variable name, since the same value will be applied to the copied field:

      Insert link: @pageToLinkTo@
This is the link to my page: [@pageToLinkTo@]

      This will result in unnecessary extra information, but still, a workaround that you can give a try. Hope that helps.

      Cheers,
      Azwandi

      1. Dec 20, 2011

        Andrew Spina

        Hi Azwandi,

        I'm working on a similar problem. Is there a way to make it so that the definition of @pageToLinkTo@ variable is hidden or deleted once the template has been filled out? This would allow the 'duplicate' information to be absent from the resulting product?

        I'm working on a template that allows the user to paste code into it. I want to do something like this:

        My Confluence Layout Code

        But the result isn't what I expect. It would be great to be able to save my users the work of specifying their code block.

        Thanks,

        Andy

  3. Sep 25, 2008

    Anonymous

    Hi,

    Can you anyone provide me a pointer on how to create tabs in the page? I want to create tabs in the home page, so that user can navigate between tabs.

    Thanks for your help in advance.

    1. Sep 25, 2008

      Azwandi Mohd Aris [Atlassian]

      Hi there,

      You might want to check out the {card} macro of third-party Composition Plugin. Hope that helps.

      Cheers,
      Azwandi

  4. Oct 09, 2008

    Anonymous

    Is there a way to name the page when you inserting the variables, so that it takes one of the variables as the page name?

    1. Jun 03, 2011

      Azwandi Mohd Aris [Atlassian]

      Hi there,

      I am afraid that this is not possible using the Confluence templates. However, may I suggest you to ask in Atlassian Answers?

      Cheers,
      Azwandi

  5. Oct 13, 2008

    Anonymous

    Is it possible to make fields mandatory?

    1. Oct 13, 2008

      Azwandi Mohd Aris [Atlassian]

      Hi there,

      Please see the improvement request at http://jira.atlassian.com/browse/CONF-7236. You might want to cast your vote to increase the popularity of the issue. Hope this helps.

      Cheers,
      Azwandi

      1. Oct 13, 2008

        Anonymous

        Hi,

        thank you for the Information about this, but at the moment there is no way to make fields mandatory? not even in the Scaffolder Plugin?

        1. Jun 06, 2011

          Azwandi Mohd Aris [Atlassian]

          Hi,

          I am sorry that I could not find any other alternative, but I believe it is worth to ask this question in Atlassian Answers.

          Cheers,
          Azwandi

  6. Oct 13, 2008

    Anonymous

    Is there a way to insert default text into a text field, that can be edited when filling in the field?  Thanks!

    1. Oct 16, 2008

      Azwandi Mohd Aris [Atlassian]

      Hi,

      I am afraid that this is not possible yet, however, there is an improvement request at http://jira.atlassian.com/browse/CONF-1623 in regard to this. You may want to add your comments, be a watcher and cast your vote to increase the popularity of the issue. Thanks.

      Cheers,
      Azwandi

  7. Oct 24, 2008

    Anonymous

    When creating templates is it possible to do something like

     

     Then fill in @var when we add the template

    1. Oct 31, 2008

      Ming Giet Chong

      Hi,

      Yes, it's possible to create the template with the wiki markup above. Please note that you should use @var1@ instead of @var1. So the wiki markup should look like:

      {section:width=60%}
@var1@
{section}

{section:width=40%}
{panel}
Navigation panel
{panel}
{section}

      Hope this helps. Thanks.

      Regards,
      MG

  8. Jan 21, 2009

    Anonymous

    Hi all,

    I would like to be able to reuse a variable to list members of a specific group.

    Here is how I wrote it with no success, department-technical and department-projectmanagement exist in my groups when i check on the Confluence admin

    Thanks

    1. Sep 27, 2011

      Azwandi Mohd Aris [Atlassian]

      Hi,

      I have tested this with confluence-users and confluence-administrators, and it works fine. You might want to check whether the {userlister} macro is working on your instance. Perhaps, the documentation on that plugin would be a good start:

      Hope that helps.

      Cheers,
      Azwandi

  9. Feb 16, 2009

    Anonymous

    Is it possible to create a Dropdown form element (Example: list of clients)? when selecting a client from the dropdown list it will link to that client page.

    1. Feb 16, 2009

      Anonymous

      to further add: I can figure out how to make list elements to link to a page:
       (VAR)

      1. Mar 04, 2009

        Komathi Krishnan [Atlassian]

        Hi,

        I believe that this can be done using the {html} macro inside your page. You might want to try out the example code given here in your page. Try placing the code in between the {html} macro.

        Cheers
        Komathi

        1. Jul 22, 2009

          Thomas Dudey

          Hi,

          sorry, but your suggestion did not help me. I tried the html-macro with a <form>-element inside, but no matter where I try to put the @...@ I am unable to create a template with a drop-down-box where the values are links to different (already existing) Wikipages.

          I already tried the obvious, e.g.:  @var|list([page1],[page2])@ but that does not work.

          Thanks for any thoughts,
          Thomas

          1. Jul 28, 2009

            Azwandi Mohd Aris [Atlassian]

            Hi Thomas,

            I believe that you should not mix up the HTML markup with the template markup. If you choose to use the HTML macro, you will need to use plain HTML inside it, as demonstrated at this page. Hope that helps!

            Cheers,
            Azwandi

            1. Jul 28, 2009

              Thomas Dudey

              Hi Azwandi,

              thanks for your answer. I believe if I put the HTML-macro with some plain HTML inside into my template, then the whole thing (i.e. the whole selection of links to wiki pages) will end up in the real (resulting) page. I would like to have a selection of a few links to different wiki pages in my template. Then a user creates a new page using the template. While creating the user chooses one of the links. Finally, the resulting wiki page should contain only the one link that the user chose while creating the page. The other links should not be visible any more (not even in the wiki markup).

              I found the the scaffolding plugin can do this, but this has other drawbacks. I would prefer a solution with "standard" tools.

              Thanks,
              Thomas

              1. Jul 29, 2009

                Azwandi Mohd Aris [Atlassian]

                If I understand you correctly, you can probably create a template similar to the following:

                Note that the first line is needed to supply the variable value to the second line. It is a behaviour of the template where same variable names will use the same value.

                1. Jul 29, 2009

                  Thomas Dudey

                  Thanks a lot, that does help. In principal it works. (Even though it has some drawbacks, e.g. it does not work for links wki pages with special characters or even only a " " (space) inside the wiki-title. Also, the page name appears twice on the resulting page, once without and once with link to the page.)

                  In any case, for our requirements we decided to use the choose-label / add-label macro plugin. The pages that we originally wanted to link to will have the "contentbylabel" macro in it and thus list all pages created from the template (users will have to apply the label after (not while) creating the page). We will not have links in both directions, only from the "pages-with-contentbylabel-macro" to the "page-created-with-template".

                  Thanks for your support, nonetheless.

  10. Mar 11, 2009

    Anonymous

    I want to use form fields to have the user enter a value that is a parameter for a macro, e.g.

    The page @Page@ does not exist.

    Is this possible at all? I know that if you define the  (Page) variable somewhere else as well, the same value will be applied inside the macro as well, but this is not exactly what I want.

    Essentially I want to define a "hidden" form field that the user enters when creating the template, but that isn't then displayed explicitly on the page.

    Since it seems the rendering of the wiki markup is done first, and the form fields then on top of that, it doesn't seem possible to hide the form field in some kind of hidden macro either.

    Might support for this be added in the future?

    1. Mar 26, 2009

      Azwandi Mohd Aris [Atlassian]

      As far as I am concerned, you might be interested in the following improvement request:

      Feel free to add your comments, cast your vote and watch the request.

  11. Apr 03, 2009

    Jason Kwong

    I think someone before my asked this but I would like to have form field to be the title of the page but would like to hide it after submission of the form.

    Can this be done?

    Thanks,
    Jason

    1. Apr 08, 2009

      Azwandi Mohd Aris [Atlassian]

      Hello Jason,

      I am afraid that is not possible with the current feature set. However, you might be interested in this feature request:

      Cheers,
      Azwandi

  12. May 01, 2009

    Nathan Tolbert

    Is there any way to specify description text for a form field, which only displays when they are editing the form fields, but is not displayed on the actual page?  It looks like the variable name is displayed, but this is rather limiting, as the documentation indicates that it cannot contain spaces...

    Thanks!

    Edit:  originally had a 2nd question, but removed it, as I realized it had already been asked and answered above.

    1. May 05, 2009

      Arie Murdianto

      Hi,

      I am sorry that it is not possible to be done. Confluence uses renderer that is not giving you a way to put the value in textfield or textarea. It can only give you a way to create those html elements. Perhaps, you want to modify the code in TemplateParamRendererComponent.java. The renderer for this template is done by this class.

      Cheers,

  13. Jun 10, 2009

    Dionne Wrights

    Is it possible to create a multi-select checkbox using form field markup and if so does anyone know how to do it?  I would like to create a template page that displays a list of keywords which the user can select, and then use those keywords as lables for the new page (which I'm also unsure about how to do or if it's possible).

    1. Jun 23, 2009

      Zed Yap [Atlassian]

      Hi Dionne,

      Is it possible to create a multi-select checkbox using form field markup and if so does anyone know how to do it?

      As far as I know, the Form Field Markup for Templates do not provide the syntax for check box. However, there is a feature request being raised to create a check box for Form Field Markup in Templates.

      Please add your comments to the discussion, vote on it and add yourself as a watcher for future updates. Also, please bear in mind the following document on how we schedule features for inclusion in our products: Implementation of New Features and Improvements.

      I would like to create a template page that displays a list of keywords which the user can select, and then use those keywords as lables for the new page (which I'm also unsure about how to do or if it's possible).

      If you are concern with this function, then you might want try the Label Tools Plugin. This plugin might be able to satisfy some of your requirement.

      Hope that helps.
      Best rgds,
      Zed

  14. Aug 04, 2009

    Anonymous

    why can't a list() function contain special characters like '/'? is there a feature request for this too?

  15. Dec 28, 2009

    Anonymous

    Is there a why to add 'radio' buttons to a template? The user needs to be able to select more than one variable.

    1. Dec 30, 2009

      Zed Yap [Atlassian]

      HI,

      Is there a why to add 'radio' buttons to a template? The user needs to be able to select more than one variable.

      As far as I know the feature requested is not available yet. However, I found a feature request which is almost similar to your request:

      Please add your comments to the discussion, vote on it and add yourself as a watcher for future updates. Also, please bare in mind the following document on how we schedule features for inclusion in our products: Implementation of New Features and Improvements.

      If you are less happy on the feature request feel free to launch a feature request in JIRA:

      Hope that helps.

      Best rgds,

      Zed

  16. Jan 19, 2010

    Anonymous

    Hi

    I have seen that a couple of people have commented about making fields mandatory in the past.

    Have there been any updates yet, as I would like to create Mandatory fields in a template that have to be filled in before the person can proceed with the saving of the template.

    This is vital to my template as people often do not fill in all the fields required for me to continue. It would be ideal if there was a warning massage that popped up telling the user that they have not filled in all fields required.

    Thank you

    Kyle Armstrong

    1. Jan 20, 2010

      Zed Yap [Atlassian]

      Hi Kyle,

      I have seen that a couple of people have commented about making fields mandatory in the past.

      Have there been any updates yet, as I would like to create Mandatory fields in a template that have to be filled in before the person can proceed with the saving of the template.

      This is vital to my template as people often do not fill in all the fields required for me to continue. It would be ideal if there was a warning massage that popped up telling the user that they have not filled in all fields required.

      As far as I know the feature requested is not available yet. However, I found an improvement request in JIRA:

      Please add your comments to the discussion, vote on it and add yourself as a watcher for future updates. Also, please bear in mind the following document on how we schedule features for inclusion in our products: Implementation of New Features and Improvements.

      Hope that helps.
      Best rgds,
      Zed

      1. Jan 20, 2010

        Anonymous

        Thanks for the swift reply Zed. 

        I have voted on this issue and hope that I make a change. :-)

        Kyle Armstrong

  17. Feb 12, 2010

    Eduardo F. Sandino

    I am trying to create a list as User Template and use it after for creating a page but it isn't reconized as a variables, just always is rendering the list in the page.

    Can anyone help me, how to make this?

  18. Mar 16, 2010

    Jason Brison

    Hello,

    I am trying to create a field that a user can input a string into and then have that data used in a macro below:

     (var)

    Is there a way to make this work?

    Thanks,

    Jason

  19. Apr 12, 2010

    Patricia Zumaeta

    Hello,

    There is an error when I create a template with variables and the macro: pagetreesearch (see below). 

    An error message in red appears: "The selected context is not a valid hierarchical page"

    And it is impossible to "Insert Variables"

    Do you know how to solve it?

    Best Regards,

    Patricia

    P.S. Template code

     Minutes of the meeting

    {*}Purpose:  (DESCRIPTION|textarea(5x20))*

    Navigate space

    *

    The selected context is not a valid hierarchical page
    {*}

    ||Date |  (DATE) |
    ||Location|  (LOCATION) |
    ||Beginning|  (BEGINNING) |
    ||End|  (END) |
    ||Created by|  (CREATED_BY) |

    1. Jan 04, 2011

      Klaus Feldmann

      You get errors in view mode if you use macros that relates to content or information that they cant find inside the environment of the admin page.

      So if you see in error within the template view mode would not tell you wether ist wrong or not – you have to check your templates within a space to see if they do what you want.

      Variables should be inserted while you create a new page with a template using variables but you can use scaffold-plugin from CustomWare if you need to insert default values. The disadvantage using scaffold will be that you cant use RichText editor within such a page and inserted links within a page wont get updated after page-title of such a page got changed.

  20. May 14, 2010

    Mark Doty

    Is it possible to not have the user select the Insert Variable button, then be in edit and for them then to need to save it.

    I am using the form field with the

    Unknown macro: {create-page}

    macro...with no edit.  Thus, a page is created (skipping the Insert Variables option).  But, the page never renders to Insert (meaning the drop down option is available for all fields).  is there a way to force the variable to be inserted, with one click instead of forcing users to go to edit?

    Thanks, Mark

  21. Oct 06, 2010

    Rich Meyer

    I want one of the variables on the page to also be the page title.  Can the page title be populated using a template?

    1. Nov 16, 2010

      Olivia Coffey

      I am interested in this as well.

      1. Jan 04, 2011

        Anonymous

        me too

  22. Jan 04, 2011

    Klaus Feldmann

    Every template will be pulled in after a page is created – thats why standard confluence does not support templates to change a page-title - this would be a feature request. 

    You could use add-page from Adaptavist or link-to macros from Custom-Ware to create pages that have pre-defined page-titles or page-titles with prefix and/or suffix, even you can implement strings for some system data to be collected to create a unique title based on ID’s or dates etc.

    Those macro needs to be setup according your requirements and they could be extended to also call up a template to be pulled in.

    So you get what you want with one click fully automatically or with a step between to name a new page-title prior creation.

     

  23. Mar 24, 2011

    Bhrat Kapoor

    Hi,

    After taking value in form field I want to pass this value in to template by using 

    Unknown macro: {link-page}

    macro how can I do that ?

    please help 

    Thanks,

    Bhrat Kapoor

  24. Mar 28, 2011

    Anonymous

    I have a template that uses a form to collect data about attachments.  Is it possible to create a table that lists all the pages created with the template, and exposes the data collected in the template?

  25. Apr 14, 2011

    Anonymous

    I want to create a template that has a table. I'll need to dynamically build the contents of the table. I know the headings but I don't know the number of row's I'll need to create. Is there a way to build the table contents dynamically?

    1. Apr 15, 2011

      Klaus Feldmann

      I use table-macro from customware to achieve this. This macro is useful if you want to create custom forms.

  26. Jul 06, 2011

    Anonymous

    I am trying to find out how I add an "ADD AN ATTACHMENT BOX" to a form. We currently have a issue request form and would like users to be able to add a screen shot attachment into the form area. Thanks Dawn

  27. Oct 10, 2011

    Anonymous

    Hi, I would like to be able to specify a list-data set and then reuse the same list-data just by referencing the variable name (rather than copying all list-options again). Is this possible? Thanks.

  28. Nov 16, 2011

    Anonymous

    I can't seem to find the difference between using the Scaffolding plugin and using this Form Field Markup, could anyone explain this?

    1. Nov 16, 2011

      Anonymous

      NM, I think I got it; with this style the user inputs variables, which are then generated to the normal page and lose their status as variable once the page is made (at this point this is just a normal page). With Scaffolding, the inputs stays a variable, and is thus easier to relocate and such.

  29. about 7 hours ago

    Anonymous

    Is it possible to have a template that prompts for a variable like

    @Var1@

    And the pass that variable into part of a macro definition like

    1. about an hour ago

      Bill Arconati [Atlassian]

      It's only possible with a macro body eg:

      But not with standard macro parameters.