Form Queries

You can fetch forms in your templates or PHP code using form queries.

{# Create a new form query #}
{% set myQuery = craft.formie.forms() %}
// Create a new form query
$myQuery = \verbb\formie\elements\Form::find();

Once you’ve created a form query, you can set parameters on it to narrow down the results, and then execute it by calling .all(). An array of Form objects will be returned.

See Introduction to Element Queries in the Craft docs to learn about how element queries work.

Example #

We can display a form for a given handle by doing the following:

  1. Create an form query with craft.formie.forms().
  2. Set the handle parameter on it.
  3. Fetch a single form with .one() and output.
{# Create a form query with the 'handle' parameter #}
{% set formQuery = craft.formie.forms()
    .handle('contactForm') %}

{# Fetch the Form #}
{% set form = formQuery.one() %}

{# Display their contents #}
<p>{{ form.title }}</p>

Parameters #

Form queries support the following parameters:

ParamDescription
asArrayCauses the query to return matching forms as arrays of data, rather than Form objects.
dateCreatedNarrows the query results based on the forms’ creation dates.
dateUpdatedNarrows the query results based on the forms’ last-updated dates.
fixedOrderCauses the query results to be returned in the order specified by id.
idNarrows the query results based on the forms’ IDs.
inReverseCauses the query results to be returned in reverse order.
limitDetermines the number of forms that should be returned.
offsetDetermines how many forms should be skipped in the results.
orderByDetermines the order that the forms should be returned in. (If empty, defaults to postDate DESC.)
relatedToNarrows the query results to only forms that are related to certain other elements.
templateNarrows the query results based on the forms’ template.
templateIdNarrows the query results based on the forms’ template, per their IDs.
titleNarrows the query results based on the forms’ titles.
uidNarrows the query results based on the forms’ UIDs.

asArray #

Causes the query to return matching forms as arrays of data, rather than Form objects.

{# Fetch forms as arrays #}
{% set forms = craft.formie.forms()
    .asArray()
    .all() %}
// Fetch forms as arrays
$forms = \verbb\formie\elements\Form::find()
    ->asArray()
    ->all();

dateCreated #

Narrows the query results based on the forms’ creation dates.

Possible values include:

ValueFetches forms…
'>= 2018-04-01'that were created on or after 2018-04-01.
'< 2018-05-01'that were created before 2018-05-01
['and', '>= 2018-04-04', '< 2018-05-01']that were created between 2018-04-01 and 2018-05-01.
{# Fetch forms created last month #}
{% set start = date('first day of last month') | atom %}
{% set end = date('first day of this month') | atom %}

{% set forms = craft.formie.forms()
    .dateCreated(['and', ">= #{start}", "< #{end}"])
    .all() %}
// Fetch forms created last month
$start = new \DateTime('first day of next month')->format(\DateTime::ATOM);
$end = new \DateTime('first day of this month')->format(\DateTime::ATOM);

$forms = \verbb\formie\elements\Form::find()
    ->dateCreated(['and', ">= {$start}", "< {$end}"])
    ->all();

dateUpdated #

Narrows the query results based on the forms’ last-updated dates.

Possible values include:

ValueFetches forms…
'>= 2018-04-01'that were updated on or after 2018-04-01.
'< 2018-05-01'that were updated before 2018-05-01
['and', '>= 2018-04-04', '< 2018-05-01']that were updated between 2018-04-01 and 2018-05-01.
{# Fetch forms updated in the last week #}
{% set lastWeek = date('1 week ago')|atom %}

{% set forms = craft.formie.forms()
    .dateUpdated(">= #{lastWeek}")
    .all() %}
// Fetch forms updated in the last week
$lastWeek = new \DateTime('1 week ago')->format(\DateTime::ATOM);

$forms = \verbb\formie\elements\Form::find()
    ->dateUpdated(">= {$lastWeek}")
    ->all();

fixedOrder #

Causes the query results to be returned in the order specified by id.

{# Fetch forms in a specific order #}
{% set forms = craft.formie.forms()
    .id([1, 2, 3, 4, 5])
    .fixedOrder()
    .all() %}
// Fetch forms in a specific order
$forms = \verbb\formie\elements\Form::find()
    ->id([1, 2, 3, 4, 5])
    ->fixedOrder()
    ->all();

id #

Narrows the query results based on the forms’ IDs.

Possible values include:

ValueFetches forms…
1with an ID of 1.
'not 1'not with an ID of 1.
[1, 2]with an ID of 1 or 2.
['not', 1, 2]not with an ID of 1 or 2.
{# Fetch the form by its ID #}
{% set form = craft.formie.forms()
    .id(1)
    .one() %}
// Fetch the form by its ID
$form = \verbb\formie\elements\Form::find()
    ->id(1)
    ->one();

This can be combined with fixedOrder if you want the results to be returned in a specific order.

inReverse #

Causes the query results to be returned in reverse order.

{# Fetch forms in reverse #}
{% set forms = craft.formie.forms()
    .inReverse()
    .all() %}
// Fetch forms in reverse
$forms = \verbb\formie\elements\Form::find()
    ->inReverse()
    ->all();

limit #

Determines the number of forms that should be returned.

{# Fetch up to 10 forms  #}
{% set forms = craft.formie.forms()
    .limit(10)
    .all() %}
// Fetch up to 10 forms
$forms = \verbb\formie\elements\Form::find()
    ->limit(10)
    ->all();

offset #

Determines how many forms should be skipped in the results.

{# Fetch all forms except for the first 3 #}
{% set forms = craft.formie.forms()
    .offset(3)
    .all() %}
// Fetch all forms except for the first 3
$forms = \verbb\formie\elements\Form::find()
    ->offset(3)
    ->all();

orderBy #

Determines the order that the forms should be returned in.

{# Fetch all forms in order of date created #}
{% set forms = craft.formie.forms()
    .orderBy('elements.dateCreated asc')
    .all() %}
// Fetch all forms in order of date created
$forms = \verbb\formie\elements\Form::find()
    ->orderBy('elements.dateCreated asc')
    ->all();

relatedTo #

Narrows the query results to only forms that are related to certain other elements.

See Relations for a full explanation of how to work with this parameter.

{# Fetch all forms that are related to myCategory #}
{% set forms = craft.formie.forms()
    .relatedTo(myCategory)
    .all() %}
// Fetch all forms that are related to $myCategory
$forms = \verbb\formie\elements\Form::find()
    ->relatedTo($myCategory)
    ->all();

title #

Narrows the query results based on the forms’ titles.

Possible values include:

ValueFetches forms…
'Foo'with a title of Foo.
'Foo*'with a title that begins with Foo.
'*Foo'with a title that ends with Foo.
'*Foo*'with a title that contains Foo.
'not *Foo*'with a title that doesn’t contain Foo.
['*Foo*', '*Bar*'with a title that contains Foo or Bar.
['not', '*Foo*', '*Bar*']with a title that doesn’t contain Foo or Bar.
{# Fetch forms with a title that contains "Foo" #}
{% set forms = craft.formie.forms()
    .title('*Foo*')
    .all() %}
// Fetch forms with a title that contains "Foo"
$forms = \verbb\formie\elements\Form::find()
    ->title('*Foo*')
    ->all();

template #

Narrows the query results based on the forms’ templates.

Possible values include:

ValueFetches forms…
'foo'of a template with a handle of foo.
'not foo'not of a template with a handle of foo.
['foo', 'bar']of a template with a handle of foo or bar.
['not', 'foo', 'bar']not of a template with a handle of foo or bar.
an FormTemplate objectof a template represented by the object.
{# Fetch forms with a Foo form template #}
{% set forms = craft.formie.forms()
    .template('foo')
    .all() %}
// Fetch forms with a Foo form template
$forms = \verbb\formie\elements\Form::find()
    ->template('foo')
    ->all();

templateId #

Narrows the query results based on the forms’ templates, per the templates’ IDs.

Possible values include:

ValueFetches forms…
1of a template with an ID of 1.
'not 1'not of a template with an ID of 1.
[1, 2]of a template with an ID of 1 or 2.
['not', 1, 2]not of a template with an ID of 1 or 2.
{# Fetch forms of the form template with an ID of 1 #}
{% set forms = craft.formie.forms()
    .templateId(1)
    .all() %}
// Fetch forms of the form template with an ID of 1
$forms = \verbb\formie\elements\Form::find()
    ->templateId(1)
    ->all();

uid #

Narrows the query results based on the forms’ UIDs.

{# Fetch the form by its UID #}
{% set form = craft.formie.forms()
    .uid('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx')
    .one() %}
// Fetch the form by its UID
$form = \verbb\formie\elements\Form::find()
    ->uid('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx')
    ->one();

Get started with Formie

Available for Craft 3. Get it from the plugin store.