Skip to main content

Freeform:Composer template tag

The Freeform:Composer tag is used to display forms that were created using the Composer tool in the Freeform Classic control panel. This tag can be used in two different ways. While each requires a very similar amount of work and similar approach, the latter (EE template formatting approach) can be more flexible:

  1. Simply specify the form name or ID, and the style template name or ID and this tag will do the rest. All other controls and notifications are handled within the Freeform Classic control panel. Formatting and styling can be done with a Composer Template (in Freeform Classic control panel) and CSS. See code example.
  2. Specify a form name or ID, and then use the variables and variable pairs below to build a template directly into your EE template for your Composer data to run through. See code example.

For editing entries submitted to a Composer-based form, see the Freeform:Composer_Edit documentation. For forms that you wish to create manually inside EE templates, please refer to the Freeform:Form tag.

{exp:freeform:composer}

OR

{exp:freeform:composer} content {/exp:freeform:composer}

[[toc]]

​Parameters

In additional to all of the parameters in Freeform:Form (available as overrides to defaults), the following parameters are available for use:

​form_id=

form_id="4"

Specify the ID of the form you created in the Freeform Classic control panel so that Freeform Classic knows which form to pull and which form the submissions should be tied to. Alternatively, you can use the form_name parameter.

​form_name=

form_name="contact_form"

Specify the short name of the form you created in the Freeform Classic control panel so that Freeform Classic knows which form to pull and which form the submissions should be tied to. Alternatively, you can use the form_id parameter.

​composer_template_id=

composer_template_id="1"

Specify the ID of the styles/formatting template you created for the Composer-based form you created in the Freeform Classic control panel. Alternatively, you can use the composer_template_name parameter.

​composer_template_name=

composer_template_name="contact_form"

Specify the short name of the styles/formatting template you created for the Composer-based form you created in the Freeform Classic control panel. Alternatively, you can use the composer_template_id parameter.

​return=

return="template_group/template" or return="template_group/template/%%entry_id%%"

This parameter lets you set where to send users once they have submitted the form. If not specified, the user will be returned to the same page. If you'd like to send the user to a page with the newly created Freeform entry ID in the URI, just add %%entry_id%% to the end of the URL you've specified in the return parameter. That variable will be replaced by the Freeform entry ID of the newly submitted entry.

​Variables

​composer:column_count

{composer:column_count}

This variable displays the current count of columns that exist in the row for the given page. For example, if you have 2 columns in the same row in a given page in your Composer form, and you are on the first one, this will parse as 1. If you have a row that is empty, it will not parse.

​composer:column_total

{composer:column_total}

This variable displays how many columns exist in the row for the given page. For example, if you have 2 columns in the same row in a given page in your Composer form, this will parse as 2. If you have a page that is empty, it will parse as 0.

​composer:field_label

{composer:field_label}

This variable parses as the label for the form field. Used inside of the composer:fields variable pair.

​composer:field_name

{composer:field_name}

This variable parses as the name for the form field. Used inside of the composer:fields variable pair.

​composer:field_type

{composer:field_type}

This variable parses as the name of the fieldtype for the form field. Typically used as a conditional for handling different formatting for different field types. All non-field type form elements such as titles, paragraphs, captcha, submit buttons, dynamic recipients, and user recipient, are all prepended with nonfield_. So for example, this variable would parse as nonfield_submit for all Submit buttons. You can easily check the fieldtype names for these by hovering your mouse over the cog icon on the given form element in Composer. Used inside of the composer:fields variable pair.

​composer:field_output

{composer:field_output}

This variable parses as the final output for each element of the form, including custom fields, titles, paragraphs, captcha, etc. Used inside of the composer:fields variable pair.

​composer:field_count

{composer:field_count}

This variable displays the current count of fields that exist in the column for the given row. For example, if you have 2 fields in the same column in a given row in your Composer form, and you are on the first one, this will parse as 1. If you have a column that is empty, it will not parse.

​composer:field_total

{composer:field_total}

This variable displays how many fields exist in the column for the given row. For example, if you have 2 fields in the same column in a given row in your Composer form, this will parse as 2. If you have a column that is empty, it will parse as 0.

​composer:column_total

{composer:column_total}

This variable displays how many columns exist for the given row. For example, if you have 3 columns in a given row in your Composer form, this will parse as 3.

​freeform:error:FIELD_NAME

{if freeform:error:FIELD_NAME}<strong>{freeform:error:FIELD_NAME}</strong>{/if}

This variable is for serving inline errors in your form (to be used with inline_errors parameter), and parses out as the appropriate error message for each form field if there are errors in the form submission. Simply construct your variables like this: freeform:error: + FREEFORM_FIELD_NAME. Because Composer is automatically generating the field output, you'll need to embed the {composer:field_name} variable directly into the error variable, so it will look like this:

{freeform:error:{composer:field_name}}

All other non-field errors will parse through the freeform:general_errors variable pair.

Your final output might be something like this, placed within the composer:fields variable pair:

{if freeform:error:{composer:field_name}}
<strong>Error: {freeform:error:{composer:field_name}}</strong>
{/if}

​Variable Pairs

​composer:page

{composer:page} {/composer:page}

This variable pair is used for handling the overall formatting wrapper for the form. Multipage forms will loop through this variable pair.

​composer:rows

{composer:rows} {/composer:rows}

This variable pair handles formatting for each row in the form.

​composer:columns

{composer:columns} {/composer:columns}

This variable pair handles formatting for each column in the form. Important for when forms have more than 1 column.

​composer:fields

{composer:fields} {/composer:fields}

This variable pair acts as a wrapper for handling formatting for the field contents, including custom field labels, form fields, and descriptions, as well as titles, paragraphs, submit buttons and any other advanced features like CAPTCHA, dynamic recipients, and user recipient fields.

​freeform:general_errors

{if freeform:general_errors}
<h2>There were some error(s) with your submission:</h2>
<ul>
  {freeform:general_errors}
  <li>{freeform:error_message}</li>
  {/freeform:general_errors}
</ul>
{/if}

This variable pair is available for parsing all general errors such as incorrect CAPTCHA, user banned, login required, spam keyword ban, secure form timeout, invalid form, etc, inside of the form. It is used in conjunction with the inline_errors parameter. When a user submits the form and any general, non-field error is triggered, it will parse through this variable pair. Field-specific errors will parse through the freeform:error:FIELD_NAME variable.

​Conditionals

All of the above variables can be used as conditionals. Additionally, the following conditionals are available for use:

​composer:field_required

{if composer:field_required}<span class="required_item">*</span>{/if}

This conditional displays its contents if the field has been set to required in Composer. Typically used as a conditional where you can then specify additional formatting and indication in the form that the field is required. Used inside of the composer:fields variable pair.

​Examples

​Pre-built custom Composer Template

Your template code will look really simple since the work was done in the Composer tool and the styling/formatting was done in the Composer Templates tab in the Freeform control panel:

{exp:freeform:composer form_name="contact" composer_template_name="contact"
return="contact_us/thank_you" }

​Custom template formatting built directly into EE Template

Your template code will look a little more advanced because the styling/formatting is being done directly in the EE template:

<style type="text/css">
    .ff_composer * {
        -webkit-box-sizing: border-box;
        -moz-box-sizing: border-box;
        box-sizing: border-box;
    }
    .ff_composer .line,
    .ff_composer .line:last-child,
    .ff_composer .last_unit{overflow:hidden; *overflow:visible;*zoom:1;}
    .ff_composer .unit{float:left; padding:10px; *padding:0;/*because ie7 doesn't do border-box*/}
    .ff_composer .unit_right{float:right;}
    .ff_composer .size1of1{float:none;}
    .ff_composer .size1of2{width:50%;}
    .ff_composer .size1of3{width:33.33333%;}
    .ff_composer .size2of3{width:66.66666%;}
    .ff_composer .size1of4{width:25%;}
    .ff_composer .size3of4{width:75%;}
    .ff_composer .line:last-child,
    .ff_composer .last_unit{float:none;width:auto;}
    .ff_composer p,
    .ff_composer h1,
    .ff_composer h2,
    .ff_composer h3,
    .ff_composer h4,
    .ff_composer h5,
    .ff_composer h6 {margin-top: 0;}
    .ff_composer .required_item {margin-left: 4px; color:red;}
    .ff_composer textarea,
    .ff_composer input[type="text"],
    .ff_composer input[type="email"],
    .ff_composer input[type="url"],
    .ff_composer input[type="number"],
    .ff_composer input[type="password"],
    .ff_composer input[type="search"] {width: 75%;}
    .ff_composer ul.dynamic_recipients {list-style: none; padding:0;}
</style>

{exp:freeform:composer
    form_name="contact"
    composer_template_name="contact"
    return="contact_us/thank_you"
}
    <div class="ff_composer">
{composer:page}
    {composer:rows}
            <div class="line">
        {composer:columns}
                <div class="unit size1of{composer:column_total}">
                {if composer:field_total == 0}

                {/if}
            {composer:fields}
                {if composer:field_label}
                    {if composer:field_type == 'nonfield_captcha'}
                        {if freeform:captcha}
                        <p>
                            {composer:field_label}
                        </p>
                        {/if}
                    {if:else}
                        <label {if composer:field_name != ''}
                            for="freeform_{composer:field_name}"
                            {/if}>
                            {composer:field_label}
                            {if composer:field_required}
                            <span class="required_item">*</span>
                            {/if}
                        </label>
                    {/if}
                {/if}
                {if composer:field_output}
                    {if composer:field_type == 'nonfield_title'}
                        <h2>{composer:field_output}</h2>
                    {if:elseif composer:field_type == 'nonfield_captcha'}
                        {if freeform:captcha}
                                {freeform:captcha}<br />
                                <input
                                    type="text"
                                    name="captcha"
                                    value=""
                                    size="20"
                                    maxlength="20"
                                    style="width:140px;" />
                        {/if}
                    {if:else}
                        <p>{composer:field_output}</p>
                    {/if}
                {/if}
            {/composer:fields}
                </div>
        {/composer:columns}
            </div>
    {/composer:rows}
{/composer:page}
    </div>
{/exp:freeform:composer}

​Using the HTML5 required attribute with composer

If you want to use the HTML5 required attribute with required fields in Composer you can use a conditional pair to check that it's required and is a custom field, then add the attributes to the field:

<p>
  {if composer:field_name AND composer:field_required}
  {freeform:field:{composer:field_name} attr:required="required"
  attr:class="required"} {if:else} {composer:field_output} {/if}
</p>

Avoid nesting composer based conditionals here unless you understand how EE parse order works. Complex conditionals and nested conditionals will parse very late and wont pass attributes.

​Will not work due to parse order and advanced conditionals

<!-- Example of bad code for reference. Will not work. Do not copy/paste. -->
{if composer:field_name} {freeform:field:{composer:field_name} {if
composer:field_required}attr:required="required" attr:class="required"{/if}}
{if:else} {composer:field_output} {/if}
Page Feedback