TIP

WE'RE HIRING! 💼

The Solspace team is expanding! If you love Craft CMS and you’re looking for an exciting full-time remote position working on software development for the Freeform and Calendar plugins for Craft and more, we’d love to hear from you!

Check Out Job Listing!

freeform.submissions function

The freeform.submissions template function fetches a list of submissions based on some or no criteria.

Submissions

Parameters

  • id #
    • An ID of a submission, or array of ID's, e.g. [54, 62, 68].
  • form #
    • Handle of the form, e.g. "myForm".
  • formId #
    • An ID of the form, e.g. 2.
  • limit #
    • Supply an int to limit the amount of submissions returned.
  • orderBy #
    • Use any field handle to order by that value and include the ASC or DESC parameter in the string, e.g. orderBy: "firstName ASC" or orderBy: "rand()".
  • status #
    • Specify status to fetch submissions with a certain status.
    • status: "open" if you have a status with a handle open.
  • token #
    • Specify a token to more securely fetch a specific submission.
    • A common use-case would be when you want to display submission data in a success page, by loading the newly created token in the return URL.
    • Can be used in conjunction with or in place of id.
  • fieldSearch #
    • Specify an object of field handles as keys and search parameters as values to search the submissions that contain specific field values.
      • Please use the original field handle name for searches, e.g. if you reused a field named firstName and renamed it to just name, make sure your search query uses firstName.
    • You can use a wildcard * to search for values that contain different values. For example *car or doc*.
    • When searching on fields that store data as arrays (including Email fields), please wrap wildcards (*) around the values, e.g. email: "*name@domain.com*".
    • See searching example below.

Usage in Templates

Display a simple list of submissions:

{% set submissions = craft.freeform.submissions({
  orderBy: "firstName ASC, lastName DESC",
  status: ["pending", "closed"],
}) %}

{% for submission in submissions %}
  <div>
    {{ submission.title }} - {{ submission.firstName }}
  </div>
{% endfor %}
1
2
3
4
5
6
7
8
9
10

Print out all submissions and check if fields exist for the submitted form, before printing them out:

{% set submissions = craft.freeform.submissions({
  orderBy: "firstName ASC, lastName DESC",
  status: ["pending", "closed"],
}) %}

{% for submission in submissions %}
  <div>
    <div>{{ submission.title }} - {{ submission.form.name }}</div>

    {% if submission.firstName is not null %}
      {{ submission.firstName.label }}: {{ submission.firstName }}<br>
    {% endif %}

    {% if submission.lastName is not null %}
      {{ submission.lastName.label }}: {{ submission.lastName }}<br>
    {% endif %}
  </div>
{% endfor %}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

To paginate submissions, use Craft's Pagination. Here's an example:

{% paginate craft.freeform.submissions({limit: 5}) as pageInfo, submissions %}

{% for submission in submissions %}
  <div>
    <div>{{ submission.title }} - {{ submission.form.name }}</div>
  </div>
{% endfor %}

{% if pageInfo.prevUrl %}
  <a href="{{ pageInfo.prevUrl }}">Previous Page</a>
{% endif %}
{% if pageInfo.nextUrl %}
  <a href="{{ pageInfo.nextUrl }}">Next Page</a>
{% endif %}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

To display a single submission (see Submission object for more info):

{% set submissionId = craft.app.request.segment(5) %}
{% set submission = craft.freeform.submissions({id: submissionId}).one() %}

{% if submission %}
  {% set form = submission.form %}

  <h3>{{ form.name }} - {{ submission.title }}</h3>

  <table class="table table-striped">
    {% for field in submission %}
      <tr>
        <th style="width: 20%;">{{ field.label ? field.label : "no-label" }}</th>
        <td>
          {% set fieldValue = submission[field.handle].value %}
          {% if fieldValue is iterable %}
            <ul>
              {% for value in fieldValue %}
                <li>{{ value }}</li>
              {% endfor %}
            </ul>
          {% else %}
            {{ fieldValue }}
          {% endif %}
        </td>
      </tr>
    {% endfor %}
  </table>

{% else %}

  <div class="alert alert-danger">
    <p class="lead">
      Sorry, no submission was found.
    </p>
  </div>

{% endif %}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

The following is an example that shows how to render uploaded Assets in your form submissions:

{% set formHandle = 'yourFormHandle' %}
{% set submissions = craft.freeform.submissions({
  form: formHandle,
}) %}

<h3>Submissions for {{ form.name }}</h3>

{% if submissions is empty %}
  <div>There are no submissions</div>
{% else %}
  <table class="table">
    <thead>
      <tr>
        <th>#</th>
        <th>Title</th>
        {% for field in (submissions|first) %}
          <th>{{ field.label }}</th>
        {% endfor %}
      </tr>
    </thead>
    <tbody>
    {% for submission in submissions %}
      <tr>
        <td>{{ submission.id }}</td>
        <td>
          <a href="{{ siteUrl }}freeform_demo/bootstrap/{{ form.handle }}/submissions/{{ submission.id }}">
            {{ submission.title }}
          </a>
        </td>
        {% for field in submission %}
          <td>
            {% if field.type == "file" %}
              {% set assetId = submission[field.handle] %}
              {% set asset = craft.assets.id(assetId).one() %}
              {% if asset %}
                {% if asset.kind == "image" %}
                  <img src="{{ asset.url }}" />
                {% else %}
                  <a href="{{ asset.url }}">{{ asset.filename }}</a>
                {% endif %}
              {% endif %}
            {% else %}
              {{ submission[field.handle] }}
            {% endif %}
          </td>
        {% endfor %}
      </tr>
    {% endfor %}
    </tbody>
  </table>
{% endif %}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51

Searching Example

Only select submissions that have Bill as the first name and has their favorite food end with pie.




 
 
 
 








{% set submissions = craft.freeform.submissions({
  orderBy: "firstName ASC, lastName DESC",
  status: ["pending", "closed"],
  fieldSearch: {
    firstName: "Bill",
    favoriteFood: "*pie",
  }
}) %}

{% for submission in submissions %}
  <div>
    <div>{{ submission.title }} - {{ submission.form.name }}</div>
  </div>
{% endfor %}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
Last Updated: 1/15/2020, 4:39:52 PM