Relationship Field

The Relationship field is used to store related items on various objects in WordPress.

Drop Down input
Radio Buttons input
Autocomplete input
Multiple Select input
Checkboxes input
List View input

The Relationship field can store relationships to one or more related items. It offers many different types of input options as well as the ability to provide a custom list of choices or choose an existing WordPress object to pull data from.

Quick Start

  1. Fill out the Basic Field Settings (Label, Description, and Field Name)
  2. Select Field Type: Relationship.
  3. Click Save New Field (or Save Field if you’re updating an existing field) to save your field configuration.

Settings

  • Selection Type
    This determines which Input Types can be used. The available options are:
    • Single Select
      • Input Type
        These input types are available for Single Select. Available options are:
        • Drop Down
        • Radio Buttons
        • Autocomplete
        • List View (with reordering)
    • Multiple Select
      • Input Type
        These input types are available for Multiple Select. Available options are:
        • Checkboxes
        • Multi Select (basic selection)
        • Autocomplete
        • List View (with reordering)
      • Display Format
        These formats are available for Multiple Select. Available options are:
        • Item 1, Item 2, and Item 3
        • Item 1, Item 2 and Item 3
        • Custom separator (without “and”)
          • Display Format Separator
            Used as separator for front-end display. This also turns off the “and” portion of the formatting. Default is “, “
      • Selection Limit
        You can choose how many selections to allow for Multiple Select. Default is “0” for no limit, but you can enter 1 or more to limit the number of items that can be selected.
  • Allow Add New
    Allow new related records to be created in a modal window within the same form screen. This helps speed up content entry and is available for any input type. It is compatible with relationships with Post Types, Taxonomies, Users, or Advanced Content Types.
  • For Autocomplete fields
    • Taggable
      When using Autocomplete input type and Allow Add New is disabled, you can allow new values to be entered directly into the Autocomplete field for supported objects. It is compatible with relationships with Post Types, Taxonomies, Users, or Advanced Content Types.
  • For List View fields
    • Show Icons
      This will show the Featured Image (if related to a post type) or the content type Icon. This is useful for content entry because it helps to differentiate between different related items.
    • Show Edit Links
      Allow related records to be edited in a modal window within the same form screen. This helps speed up content updates. It is compatible with relationships with Post Types, Taxonomies, Users, or Advanced Content Types.
    • Show View Links
      Allow related records to be viewed in a new window. This helps to preview related content more easily. It is compatible with relationships with Post Types, Taxonomies, Users, or Advanced Content Types.
  • For Drop Down fields
    • Default Select Text
      This is the text used for the default “no selection” dropdown item. If left empty, it will default to “– Select One –“.
  • For Relationships to Tables (when the Advanced Relationships Component is enabled)
    • Table ID Column
      This is the ID column name used to keep track of the relationship.
    • Table Index Column
      This is the index column name used to show the label of the related row.
  • For Relationships to Post Types
    • Limit list by Post Status
      You can choose to limit Posts available for selection by one or more specific post status
  • For Relationships to Users
    • Limit list by Role(s)
      You can choose to limit Users available for selection by specific role(s).
  • Display Field in Selection List
    This is the name of a field on the related object to reference, example: {@post_title}. The default will be the index field detected on the related object (Post Title, Term Name, User Display Name, etc).
  • Customized WHERE
    This allows you to further restrict the related items available for selection with a custom MySQL WHERE clause. See examples in find() ‘where’ parameter.
  • Customized ORDER BY
    This allows you to further change the order of the related items available for selection with a custom MySQL ORDER BY clause. See examples in find() ‘where’ parameter.
  • Customized GROUP BY
    This allows you to further change the related items available for selection with a custom MySQL GROUP BY clause. See examples in find() ‘where’ parameter.

How to Display

When displaying relationships, it will always display the label/title of the related item. When using multiple select, Pods will automatically output the list in a readable format using the Oxford Comma like: Option One, Option Two, and Option Three.

By default, Pods will not link to the related object URLs when displaying. If you want to do this, you can look at field() or using [each].

You can also traverse into any related item’s data by following field() traversal notation.

Display with a Shortcode

[pods field="my_relationship_field"]

Display with PHP: pods_field_display()

<?php
echo pods_field_display( 'my_relationship_field' );

Display with PHP: $pod->display()

<?php
$pod = pods();

echo $pod->display( 'my_relationship_field' );

Other Helpful Documentation on Working with Fields in Pods

Avatar Field

Extends User Profile with a Gravatar field that is managed under the Media Library as opposed to using Gravatar.com

Code (Syntax Highlighting) Field

The Code (Syntax Highlighting) field is used for multiple line code content.

Color Picker Field

The Color Picker field is useful in situations where a color needs to be able to be chosen and customized.

Conditional Logic for Fields

Conditional Logic for Fields will allow you to show or hide a field based on the value of another field.

Currency Field

The Currency field is used to store numeric, integer, and float currency amounts.

Date / Time Field

The Date / Time field is used to store a date and time value with an easy to use date / time input.

Date Field

The Date field is used to store a date value with an easy to use date input.

Email Field

The Email field allows you to store email addresses with additional validation checks.

File / Image / Video Field

The File / Image / Video field is used to store a relationship to Media attachment(s).

Heading Field

The Heading field is not a normal input field, it will output Heading text between your normal form fields to help organize the form.

HTML Content Field

The HTML Content field is not a normal input field, it will output as HTML itself between your normal form fields to help organize the form.

oEmbed Field

The oEmbed field is used to store a single URL that will use the oEmbed protocol to display remote content.

Password Field

The Password field is used to store single-line text with a basic password input form field.

Phone Field

The Phone field is used for telephone numbers in various formats.

Plain Number Field

The Plain Number field is used to store numeric, integer, and float values.

Plain Paragraph Text Field

The Plain Paragraph Text field is used for multiple line text values.

Plain Text Field

The Plain Text field is used for Simple Plain Text Values like a first name, last name, alphanumeric ID or value.

Settings: Advanced

Provides access to the Advanced field options when editing a field.

Settings: Field Details

Basic Field Settings (Label, Name, Description and Field Type) that apply to all Fields created in Pods.

Settings: Reserved List of Names

There are certain names you cannot use for Pod, Group, or Field names in Pods because they are reserved in WordPress or Pods for other uses.

Simple Repeatable Fields

Simple Repeatable Fields will allow you to repeat many different types of fields.

Time Field

The Time field is used to store a date value with an easy to use time input.

Website Field

The Website field is used to store a URL or Website Address or Link to a Website.

WYSIWYG (Visual Editor) Field

The WYSIWYG (Visual Editor) field is used for multiple line HTML content.

Yes / No Field

The Yes / No field offers customizable labels and display options for checkbox, radio buttons, or a drop-down input.