Return the value for a field. If you are getting a field for output in a theme, most of the time you will want to use display() instead. This function will return arrays for relationship and file fields.
Contents
Function Definition
public function field ( $name, $single = null, $raw = false )
Source File: /pods/classes/Pods.php
Since: 2.0
Parameters
PARAMETER | TYPE | DETAILS |
---|---|---|
$name | (string|array) | The field name, or an associative array of additional parameters. |
$single | (boolean) | (optional) For tableless fields, to return the whole array or the just the first item. |
$raw | (boolean) | (optional) Whether to return the raw value, or to run through the field type’s display method. |
Additional Parameter Options
NOTE: Additional parameters should only be passed into the $name
parameter of the method.
OPTION | TYPE | DEFAULT | DETAILS |
---|---|---|---|
name | (string) | $name | The field name |
single | (bool) | $single | (optional) For tableless fields, to return the whole array or the just the first item |
raw_display | (bool) | false | (optional) Set to true in certain cases as field() runs, but you can set to true to disable filters / value handling by field type |
orderby | (string) | null | (optional) For tableless fields, you can choose to return an array of items in a specific order |
params | (array) | null | (optional) For tableless fields, you can choose to override the find() (select) $params |
output | (string) | arrays | (optional) For tableless fields, changes the output returned: ids, names, objects, arrays, pods (Pods objects); Can change global default with pods_pods_field_related_output_type filter; Simple fields are forced to ‘arrays’ output |
args | (array) | array() | (optional) Official option sanctioned for hook use to pass extra data into ‘pods_pods_field’ or ‘pods_pods_field_{field_type}’ filters |
in_form | (bool) | false | (optional) For internal use. If set to true, always return a full array of data |
raw | (bool) | false | (optional) For internal use. Set to true when calling field() internally from Pods::raw() |
display | (bool) | false | (optional) For internal use. Set to true when calling field() internally from Pods::display() |
get_meta | (bool) | false | (optional) For internal use. Set to true through calls from PodsMeta::get_meta |
deprecated | (bool) | false | (optional) For internal use. Set to true through calls to Pod::get_field |
Returns
(mixed|null) Value returned depends on the field type, null if the field doesn’t exist, false if no value returned for tableless fields
Examples
Example 1
<?php // Get the book by ID. $books = pods( 'books', 123 ); $name = $books->field( 'name' ); $author_name = $books->field( 'related_author.name' ); $category_name = $books->field( 'category.name' );
Setting Additional Parameters
This example gets the first relationship value from the “lightsabers” field. You can pass other additional parameters following this same format.
<?php $pods = pods( 'jedi', 123 ); // Get the first "lightsabers" relationship field value. $args = [ 'name' => 'lightsabers', 'single' => true, ]; $lightsabers = $pods->field( $args );
Other Notes
Use of this function replaced the Pods 1.x method get_field().
Internally, this method calls things like get_post_meta(), get_term_meta(), get_user_meta(), get_comment_meta(), and get_option() to retrieve information from WordPress object meta storage.
Additional Field Notation Options
There are a number of special notation options you can use which correspond to special values related to relationships, files, post thumbnails, Pods, and Fields which allow for even more flexibility.