Playa Documentation

Working with Fields

A Playa field lets an editor select other entries and save relationships to them. The entry containing the field is the parent; the selected entries are its children. See Playa Terminology for the other relationship directions.

Creating a Playa field

  1. Install Playa, then open Fields in the ExpressionEngine control panel.
  2. Click New Field.
  3. Choose Playa for Type. Enter a name for editors and a Short Name for templates, such as related_articles.
  4. Configure the Playa options described below, then click Save.
  5. Open the intended channel's settings under Channels. Add the field to that channel's Fields, or add it to a field group assigned to the channel. Save the channel settings.
  6. Create or edit an entry in that channel and select the entries you want to relate.

These labels follow ExpressionEngine 7. The Create/Edit Field documentation explains the standard field settings, including required fields and instructions for editors.

Existing relationship data

Do not simply change an existing Relationship field's type to Playa. A field-type change is not a relationship migration and can lose the existing relationships. Plan and test a migration on a backed-up copy of the site before changing an existing field.

Playa field options

Allow multiple selections?: Choose Yes for Playa's two-pane selection interface, or No for a single-selection dropdown.
Show expired entries? and Show future entries?: Control whether entries outside their publication dates appear in the editor's choices.
Only show editable entries?: Limit the choices to entries the current editor is allowed to edit.
Channels, Categories, Author primary roles, Authors, and Statuses: Set the initial filters for the available entries. For example, select an Articles channel if editors should begin by choosing articles. Multi-site installations also have a Sites setting.
Limit entries to: Choose All, or limit the initial results to the newest or oldest entries.
Order entries by: Order the available choices by entry title or entry date, in ascending or descending order.

These options configure the editor's field. Template parameters independently control which saved relationships appear on the front end. For example, showing expired entries in the field does not automatically enable show_expired="yes" in a template.

Selecting and ordering entries

In the two-pane interface, select an entry from the available choices and use the selection arrow, double-click it, or drag it into the selected pane. Use the filters when shown to find an entry. Remove an item with the reverse selection arrow or by moving it back to the available choices.

Drag selected entries to change their saved order, then save the parent entry. The primary field tag pair and children module tag use the saved relationship order unless you supply an orderby parameter.

In the single-selection dropdown, choose the entry you want to relate and save the parent entry.

Displaying the saved relationships

Use the field's short name inside a Channel Entries loop. For a field named related_articles:

{exp:channel:entries channel="news" limit="1"}
    <h1>{title}</h1>
    {related_articles}
        <p><a href="/articles/{url_title}">{title}</a></p>
    {/related_articles}
{/exp:channel:entries}

Replace the channel and URL path with your site's values. Read Field Tags for lists, counts, ID output, filtering, and empty-result handling. Use Module Tags to query parents, siblings, or co-parents, and Channel Form for front-end editing.

Support

Having problems setting up and/or using Playa? Support is offered from 10am to 4pm EST weekdays. Send us an email at help@eeharbor.com and we will respond as quickly as we can.