View the Demo
View the Demo

Plain Text Fields

Plain text fields give you either a normal text input or a multi-line textarea, where plain text can be entered. How that text is used is entirely up to you!

Settings

Plain text fields have the following settings:

  • UI Mode — How the field should be presented in the control panel. (Defaults to “Normal”, can be “Enlarged”.)
  • Placeholder Text — The field’s placeholder text, to be displayed if the field has no value yet.
  • Field Limit — The maximum number of characters or bytes the field is allowed to have. (Accepts a number and a unit, which defaults to “Characters” with another option for “Bytes”.)
  • Use a monospaced font — Whether field input’s text will use a monospaced font.
  • Allow line breaks — Whether to allow line breaks in this field.
    • Initial Rows — For multi-line inputs, choose how many lines of text fit in the field, initially. This setting does not affect how many lines of text can be stored.

The Field

Plain text fields will either show a normal text input element or a multi-line textarea, depending on whether Allow line breaks was checked. To give editors more space, increase the number of Initial Rows.

Development

Accessing a plain text field in your templates will return the value that was entered in the field. Suppose our field was named “Summary” and had a handle of summary:

{{ entry.summary }}

Testing for a Value

An empty text field is a “falsey” value, so you can use it in a conditional:

{% if entry.summary %}
  <h3>Summary</h3>
  <p>{{ entry.summary }}</p>
{% endif %}

Keep in mind that whitespace characters count the same as any other character—use the trim filter to remove spaces and newlines from the beginning and end:

{% if entry.summary|trim %}
  {# Ok, there really is content in here! #}
  <h3>Summary</h3>
  <p>{{ entry.summary }}</p>
{% endif %}

Processing Text

Craft’s Twig environment has a ton of useful text processing features.

Markdown

Parse a field’s value as Markdown with the markdown or md filter:

{% if entry.summary %}
  <h3>Summary</h3>
  {{ entry.summary|md }}
{% endif %}

Note that we’re not manually wrapping the output in <p></p> tags! Markdown takes care of this for us, unless you pass the inlineOnly argument:

Reference Tags

To include dynamic information in a Plain Text field, you can copy reference tags from other elements, then use the parseRefs filter to render their values:

I can’t live without {globalset:snippets:primaryProductName}!

{{ entry.testimonial|parseRefs }}

I can’t live without Butter™!

Querying

Plain text field values are stored as strings, and therefore support a variety of convenient query features via craft5:craft\helpers\Db::parseParam().

Exact Matches

Open-ended inputs aren’t ideal for storing enum-style data (leave that to a dropdown field), but you can still query based on the exact text content of a field:

{% set reds = craft.entries()
  .section('swatches')
  .colorGroupCode('RED')
  .all() %}

Multiple Values

Match against a list using comma-separated values or an array:

{# Separate values with commas... #}
{% set sunrisePalette = craft.entries()
  .section('swatches')
  .colorGroupCode('PINK, RED, YELLOW, ORANGE')
  .all() %}

{# ...or use an array: #}
{% set sunrisePalette = craft.entries()
  .section('swatches')
  .colorGroupCode(['PINK', 'RED', 'YELLOW', 'ORANGE'])
  .all() %}

These examples are ultimately assembled into a NOT IN (...) SQL clause.

Negation

Exclude elements with a specific field value by preceding a value with not:

{% set notCool = craft.entries()
  .section('swatches')
  .colorGroupCode('not BLUE')
  .all() %}

Multiple values can be excluded by preceding each term in a comma-separated list by a not ('not BLUE, not GREEN'), or by using not as the first item in an array (['not', 'BLUE', 'GREEN']).

The grouping of terms is important when combining ranges and negation! not RED, YELLOW means “Swatches with a color other than RED, or swatches with a color of YELLOW.” On the other hand, ['not', 'RED', 'YELLOW'] means “Swatches with a color other than RED or YELLOW.” The former would exclude “red” swatches, but allow “yellow;” the latter would exclude both colors.

Partial Matches

You can query using partial matches by including an asterisk (*) at the beginning and/or end of a value:

{# All “pastel” families: #}
{% set pastels = craft.entries()
  .section('swatches')
  .colorGroupCode('PASTEL-*')
  .all() %}

{# All “glossy” group variations: #}
{% set glosses = craft.entries()
  .section('swatches')
  .colorGroupCode('*-GLOSS')
  .all() %}

Combined with the above, a param like 'not *-MATTE' is also valid. Queries that use asterisks are generally compiled into LIKE statements compatible with the database driver.

Empty Values

The special tokens :empty: and :notempty: can be used to find elements with a plain text field that is empty or populated, respectively. Both tokens are compiled into query conditions that compare against null and empty string ('') values.

Literal Symbols

To use asterisks or commas in a query param, pass your value through the literal Twig filter.

Case-Sensitivity

Query values are case-sensitive, by default. To make a query case-insensitive, use a hash with value and caseInsensitive keys:

{% set reds = craft.entries()
  .section('swatches')
  .colorGroupCode({
    value: 'red',
    caseInsensitive: true,
  })
  .all() %}