Introduction

This is the documentation for Papi 2.x

Papi has a different approach on how to work with fields and page types in WordPress. The idea is coming from how Page Type Builder in EPiServer works and has been loved by the developers.

So we though why don’t use the same approach in WordPress? Papi is running in production and has been easy to work with when it came to add new fields. Papi don’t have any admin user interface where you should add fields, we use classes in PHP, where one class represents one page type and in your class you add all fields you need. It’s that easy!

Papi does not save the property type value in the database, only the value of the property is saved since the type value exists in the page type file.

Papi is completely open-source. If you want to help with its development you can submit your suggestions or improvements on in the Github repository.

Requirements

WordPress >= 4.0
PHP >= 5.4.7

Installation

If you’re using Composer to manage WordPress, add Papi to your project’s dependencies. Run:

composer require wp-papi/papi

Or manually add it to your composer.json:

{
  "require": {
    "php": ">=5.4.7",
    "wordpress": "~4.2",
    "wp-papi/papi": "~2.0"
  }
}

Upgrade guide

Upgrade to 2.x from 1.x

Change wp-papi/papi version to ~2.0 in your composer.json file and run composer update.

API

papi_fields is deprecated and replaced with papi_get_slugs.

API Field

papi_field is deprecated and replaced with papi_get_field because the name can be confusing when papi_update_field and papi_delete_field exists.

It will still work to use papi_field but you will get a deprecated warning.

API Page

current_page is deprecated. You can use papi_get_page with no argument to get the same result.

It will still work to use current_page but you will get a deprecated warning.

Properties

In 2.0.0 placeholder setting replaced blank_text and include_blank.

Relationship property

In 2.0.0 choose_max was renamed to limit.

Settings filters

Show standard page type for post type

The filter papi/settings/standard_page_type_{$post_type} was renamed to papi/settings/show_standard_page_type_{$post_type}.

Page Type Directory

Papi does require a directory in your theme, plugin or somewhere in your WordPress site where your page types exists. You can add multiplied directories.

<?php

/**
 * Register page types directory with Papi.
 */

add_filter( 'papi/settings/directories', function () {
  return __DIR__ . '/includes/page-types';
} );

Actions

Delete value

action papi/delete_value/{$property_type}

<?php

/**
 * Example of `papi/delete_value/{$property_type}` action.
 */

add_action( 'papi/delete_value/string', function ( $slug, $post_id ) {
  // do something when string property is deleted
}, 10, 2 );

Description

With this action you can do something when a property is deleted with papi_delete_field or papi_delete_option. The $post_id will be zero when you is deleting a option value.

Include plugins or properties

action papi/include

<?php

/**
 * Example of `papi/include` action that will include a custom property.
 */

add_action( 'papi/include', function () {
  require_once 'class-papi-property-kvack.php';
} );

Description

With this action you can include plugins or properties build for Papi. Third party properties should use this action when they load there custom property in the plugin.

API

papi_get_page_type_key

<?php

/**
 * Example output from `papi_get_page_type` function.
 */

string '_papi_page_type'

Description

This function will return the key that Papi uses as key in postmeta for the page type id.

papi_get_slugs

<?php

/**
 * Example output from `papi_get_slugs` function.
 */

[
  'Content' => [
    'top_module',
    'feature_module',
    'show_feature_module'
  ]
]

Description

This function will return a array with meta box title as keys and array of all Papi field slugs in that meta box.

Parameters

Parameter	Default	Required	Description
$post_id	null	no	The post id will be added automatic if you are one a post, page or custom post type page. When fetching values from another post this argument will be required

papi_property

<?php

/**
 * Example of `papi_property` function.
 */

// my-page-type.php
$this->box( 'My meta box', [
  papi_property( 'properties/my-image.php', [
    'slug' => 'my_meta_box_image'
  ] )
] );

// properties/my-image.php
return papi_property( [
  'type'  => 'image',
  'title' => 'Image',
  'slug'  => 'custom_image_slug'
] );

Description

This argument is only used when you load a template file, the array will be used to override property options from the template file.

This function will be the same as $this->property method on a page type.

When using a shared property file or another file that the property are stored in you can used it as a template file.

This is great to use when you will share properties over many page types and it will be less code to write.

Parameters

Parameter	Default	Required	Description
$file_or_options		yes	File path or a array containing property options
$values	array	no	The values to override the template values with

papi_tab

<?php

/**
 * Example of `papi_tab` function.
 */

// my-page-type.php
$this->box( 'My meta box', [
  $this->tab( 'tabs/image-tab.php', [
    'title' => 'Background'
  ] )
] );

// tabs/image.php
return papi_tabs( [
  'title' => 'Images',
  'slug'  => 'custom_image_slug'
], [
  papi_property( 'properties/my-image.php' ),
  papi_property( [
    'type'  => 'string',
    'title' => 'Name',
    'slug'  => 'name'
  ] )
] );

Description

This argument is only used when you load a template file, the array will be used to override tab options from the template file.

This function will be the same as $this->tab method on a page type.

When using a shared tab file or another file that the tab are stored in you can used it as a template file.

This is great to use when you will share tabs over many page types and it will be less code to write.

Parameters

Parameter	Default	Required	Description
$file_or_options		yes	Title, file path or a array containing tab options
$properties	array	no	The values to override the template values with or properties

papi_template

<?php

/**
 * Example of `papi_template` function.
 */

// my-page-type.php
$this->box( 'My meta box', [
  papi_property( [
    'type'     => 'dropdown',
    'title'    => 'Dropdown',
    'slug'     => 'my_dropdown',
    'settings' => papi_template( 'settings/dropdown.php' )
  ] )
] );

// settings/dropdown.php
return [
  'items' => [
    'White' => '#ffffff',
    'Black' => '#000000'
  ]
];

Description

papi_property function uses this function load template file. This function can be used to load template files that returns arrays. It can be handy when you will have to repeater or dropdown values in another file.

Parameters

Parameter	Default	Required	Description
$file_or_options		yes	File path to template file
$properties	array	no	The values to override the template values with

API Field

papi_delete_field

<?php

/**
 * Example of `papi_delete_field` function.
 */

$success = papi_delete_field( 456, 'twitter_url' );

Description

With this function you can delete property value from the database. It will return false if can’t update or find the property in a page type.

Parameters

Parameter	Default	Required
$post_id	null	no
$slug		yes

papi_get_field

<?php

/**
 * Example of `papi_get_field` function.
 */

echo papi_get_field( 'twitter_url' );

// with default value
echo papi_get_field( 'twitter_url', 'http://twitter.com/frozzare' );

Description

The post id will be added automatic if you are one a post, page or custom post type page.

When fetching values from another post this argument will be required.

You can also use the_papi_field to display it without echo

Parameters

Parameter	Default	Required	Description
$post_id	null	no	The post id will be added automatic if you are one a post, page or custom post type page. When fetching values from another post this argument will be required
$slug		yes	The property slug to fetch value from
$default	null	no	When a default value is passed as argument it will use that value as return value and echo it if the property value is empty or don’t exists

papi_update_field

<?php

/**
 * Example of `papi_update_field` function.
 */

$success = papi_update_field( 456, 'twitter_url', 'http://twitter.com/frozzare' );

Description

With this function you can update property value from the database. It will return false if can’t update or find the property in a page type.

Parameters

Parameter	Default	Required
$post_id	null	no
$slug		yes

the_papi_field

<?php

/**
 * Example of `the_papi_field` function.
 */

the_papi_field( 'twitter_url' )

// with post id
the_papi_field( 1, 'twitter_url' )

// with default value
the_papi_field( 1, 'twitter_url', 'http://twitter.com/frozzare' );

Description

This function will echo the value of a property using the property slug.

You can also use papi_field to fetch the value into a variable.

Parameters

Parameter	Default	Required	Description
$post_id	null	no	The post id will be added automatic if you are one a post, page or custom post type page. When fetching values from another post this argument will be required
$slug		yes	The property slug to fetch value from
$default	null	no	When a default value is passed as argument it will use that value as return value and echo it if the property value is empty or don’t exists

API Page

papi_get_page

<?php

/**
 * Example of `papi_get_page` function.
 */

echo papi_get_page()->twitter_url;

// with post id
echo papi_get_page( 2 )->twitter_url;

Description

When given a post id it will fetch the Papi page for that post id instead.

The papi page function will do the same as current page function if no post id is used as a argument.

Parameters

Parameter	Default	Required	Description
$post_id	null	no	The post id will be added automatic if you are one a post, page or custom post type page. When fetching values from another post this argument will be required

papi_get_page_type_id

<?php

/**
 * Example of `papi_get_page_type_id` function.
 */

echo papi_get_page_type_id();
// "article-page-type"

// with post id
echo papi_get_page_type_id( 2 );
// "activity-page-type"

Description

When given a post id it will fetch the Papi page for that post id instead.

Parameters

Parameter	Default	Required	Description
$post_id	null	no	The post id will be added automatic if you are one a post, page or custom post type page. When fetching values from another post this argument will be required

papi_get_page_type_name

<?php

/**
 * Example of `papi_get_page_type_name` function.
 */
echo papi_get_page_type_name();
// => "Article Page"

// with post id
echo papi_get_page_type_name( 2 );
// => "Video Page"

Description

Get the page type name. Useful when you will print out the name of the page type in your theme.

You can also use the_papi_page_type_name to display it without echo

Parameters

Parameter	Default	Required	Description
$post_id	null	no	The post id will be added automatic if you are one a post, page or custom post type page. When fetching values from another post this argument will be required

the_papi_page_type_name

<?php

/**
 * Example of `the_papi_page_type_name` function.
 */

the_papi_page_type_name();
// => "Article Page"

// with post id
the_papi_page_type_name( 2 );
// => "Video Page"

Description

Print the page type name. Useful when you will print out the name of the page type in your theme.

You can also use papi_page_type_name to fetch the name into a variable.

Parameters

Parameter	Default	Required	Description
$post_id	null	no	The post id will be added automatic if you are one a post, page or custom post type page. When fetching values from another post this argument will be required

API Option

papi_delete_option

<?php

/**
 * Example of `papi_delete_option` function.
 */

$success = papi_delete_field( 'twitter_url' );

Description

With this function you can delete property value from the database. It will return false if can’t update or find the property in a option type.

Parameters

Parameter	Default	Required
$slug		yes

papi_get_option

<?php

/**
 * Example of `papi_get_option` function.
 */

echo papi_get_option( 'twitter_url' );

// with default value
echo papi_get_option( 'twitter_url', 'http://twitter.com/frozzare' );

Description

Fetch property value from option type.

You can also use the_papi_option to display it without echo

Parameters

Parameter	Default	Required	Description
$slug		yes	The property slug to fetch value from
$default	null	no	When a default value is passed as argument it will use that value as return value and echo it if the property value is empty or don’t exists

papi_update_option

<?php

/**
 * Example of `papi_update_option` function.
 */

$success = papi_update_option( 'twitter_url', 'http://twitter.com/frozzare' );

Description

With this function you can update property value from the database. It will return false if can’t update or find the property in a option type.

Parameters

Parameter	Default	Required
$slug		yes

the_papi_option

<?php

/**
 * Example of `the_papi_option` function.
 */

the_papi_option( 'twitter_url' )

// with default value
the_papi_option( 'twitter_url', 'http://twitter.com/frozzare' );

Description

This function will echo the value of a property using the property slug.

You can also use papi_option to fetch the value into a variable.

Parameters

Parameter	Default	Required	Description
$slug		yes	The property slug to fetch value from
$default	null	no	When a default value is passed as argument it will use that value as return value and echo it if the property value is empty or don’t exists

Box (meta box)

<?php

/**
 * Example of the default options.
 */

$this->box( [
  'capabilities' => [],
  'context'      => 'normal',
  'mode'         => 'standard',
  'priority'     => 'default',
  'sort_order'   => 1000,
  'title'        => ''
] );

Documentation of the box method. box is a short name for metabox in Papi.

Options

Key	Default	Description
capabilities	array	Can be a string with a role or capability or a array with many values
context	‘normal’	The same value as for context in `add_meta_box`
priority	'default’	The same value as for priority in `add_meta_box`
sort_order	1000	Numeric value, lowest value in the meta box will be at the top and the highest value at the bottom
title	empty string	The title of the meta box. This can’t be empty. When passing a string as the first argument for box method it will become `array('title' => 'the title')` automatic

In 2.0.0 the mode option was removed.

Callable method

It’s possible to use callable method as a second argument in your box method that returns a array with properties or tabs.

<?php

/**
 * Example of using the callable parameter.
 */

public function register() {
  $this->box( 'Content', [$this, 'content_box'] );
}

public function content_box() {
  return [
    papi_property( [
      'type'  => 'string',
      'title' => 'Name'
    ] ),
    papi_property( [
      'type'  => 'text',
      'title' => 'About'
    ] )
  ];
}

Import and Export

Since 2.3.0

Papi Porter is a utility class that you can use to import and export field data. You can create custom porter driver, for example a xml driver.

Import

<?php

// Get the porter class.
$porter = papi()->porter();

// Change value for slugs before driver is finished with the value.
$porter->before( 'driver:value', function ( $value, $slug ) {
  switch ($slug) {
    case 'my_string_slug':
      return 'Before';
    default:
      return $value;
  }
} );

// Change value for slugs after driver is finished with the value.
$porter->after( 'driver:value', function ( $value, $slug ) {
  switch ($slug) {
    case 'my_string_slug':
      return 'After';
    default:
      return $value;
  }
} );

// Create a new post.
$post_id = wp_insert_post( [
  'post_title' => 'Test Papi Import',
  'post_type'  => 'page'  
] );

// Import data, will return true or false.
$result = $porter->import( [
  'post_id'   => $post_id,
  'page_type' => 'article-page-type'
], [
  'my_string_slug' => 'Hello'
] );

// Done! The value of `string_test` will be `After`.

This is a simple example that will import a string value to a new post. The value can be changed before and after the porter driver does the magic with the value.

Parameters

Parameter	Default	Required	Description
$options		yes	Array, post or post id (that has a page type id in postmeta table).
$fields	array	no	If true only the value will be return for fields and not all options.

Drivers

<?php

/**
 * Example of adding a driver.
 */

$porter->driver( new Papi_Porter_Driver_Example );

/**
 * Example of change driver.
 */

$porter->driver( 'example' );

/**
 * Example of driver class.
 */
class Papi_Porter_Driver_Example extends Papi_Porter_Driver {

    /**
     * The driver name.
     *
     * @var string
     */
    protected $name = 'example';

    /**
     * Alias for driver name.
     *
     * @var string
     */
    protected $alias = 'alias';

    /**
     * Get value that should be saved.
     *
     * @param  array $options
     *
     * @return mixed
     */
    public function get_value( array $options = [] ) {
        // Do some magic with the value.
        return $options['value'];
    }
}

Papi has a core driver that is default. A driver can have a alias and the core driver alias is papi.

To change driver that the import method uses you can do it with use_driver or driver method that takes the name or alias as argument.

To add a custom driver that the import method can use you can add add_driver or driver method that takes the driver instance as argument.

Export

<?php

// Get the porter class.
$porter = papi()->porter();

// Export fields.
$fields  = $porter->export( 7 );

// Example output.
[
 'Content' => [
   'my_string_slug' => [
     'after_html'   => '',
     'before_html'  => '',
     'capabilities' => [],
     'description'  => '',
     'disabled'     => false,
     'lang'         => false,
     'raw'          => false,
     'required'     => false,
     'rules'        => [],
     'settings'     => [],
     'sidebar'      => true,
     'slug'         => 'papi_top_module',
     'sort_order'   => 100,
     'title'        => 'Name',
     'type'         => 'string',
     'value'        => 'After'
   ]
 ]
]

The export method will return array with box title as key and array of properties with all options and the value as box value.

Parameters

Parameter	Default	Required	Description
$post_id		yes
$only_values	false	no	If true only the value will be return for fields and not all options.

Option type

<?php

/**
 * Example of a option type with no properties.
 */

class Header_Option_Type extends Papi_Option_Type {

  /**
   * The option type meta options.
   *
   * @return array
   */

  public function meta() {
    return [
      'menu' => 'options-general.php',
      'name' => 'Header'
    ];
  }

}

Option type class extends the page type class so you can create options pages with Papi! Option types will not be showed on Papi’s tool page since they don’t belong to a post type.

Differents between option type and a page type

Does not save the option type id in the database since options don’t have a post id. So you can’t have different option types that has the same property slug.
The page_type method is named option_type.

meta method

The option_type is a required method of the option type class. It should return an array containing the required keys.

Since 2.4.0 the method is called meta the old option_type method will still work but is deprecated and not recommended to use.

Options	Required	Description
capability	no	The capability that are allowed to access the page. Default is `manage_options`
menu	yes	The menu to register the sub menu page on
name	yes	The name of the option type

Papi does only register submenu pages, so if you want a custom admin page you have to add it yourself.

Namespaces

<?php

namespace Foo\Bar;

/**
 * Example of a option type with namespace.
 */

class Test_Option_Type extends \Papi_Option_Type {}

Papi has no problem to work with option types that have namespaces.

Page type

<?php

/**
 * Example of a page type with no properties.
 */

class Video_Page_Type extends Papi_Page_Type {

  /**
   * The page type meta options.
   *
   * @return array
   */

  public function meta() {
    return [
      'name'        => 'Video page',
      'description' => 'A page where you can embed videos',
      'template'    => 'pages/video-page.php'
    ];
  }

}

meta method

The meta is a required method of the page type class. It should return an array containing the required keys.

Since 2.4.0 the method is called meta the old page_type method will still work but is deprecated and not recommended to use.

Options	Required	Description
name	yes	The name of the page type
child_types	no	Array of page type that will be available when `parent_post` query string exists. The array values should be the page type id. Since 2.3.0
description	no	The description of the page type
fill_labels	no	When this is true it will add the page type name to `add_new_item`, `edit_item` and `view_item` label. Both in WordPress admin and the admin bar on the front. You can override this with the `labels` array.
labels	no	With this you can handle the `labels` object that exists on a post type. So this means that you can change “Add New Page” for every page type and have something like `Add New Startpage`. Just create a array with the `labels` keys and values on your page type meta array
post_type	no	Array of post types that the page type should be registered on. Default is `page`
sort_order	no	The sort order number of the page type
standard_type	no	True or false if standard page type should be displayed on `Add New Page` when `parent_post` query string exists or when you want to hide standard page when a post type only has one page type, like `only_page_type` filter. Since 2.3.0
template	no	The template file to render. This can be both dot templates `pages.article` or `pages/article.php`. Extension is not required. Dot templates and extension requirement does only exists in 2.3.0 and above.
thumbnail	no	The thumbnail image that should appear on the add new page

/**
 * Example of template structure.
 */

themes/
  my-theme/
    pages/
      about-page.php
      contact-page.php
      video-page.php

When you using template key you can get a better structure of all pages type you are using and which template file it used.

When creating a new page you will get a new view before you get the edit view for your page where you should choose which page type to use. This will happen for all post types that uses page types.

box method

This method is used to register all properties, tabs and remove meta boxes as described above.

The box method can has callable method as the second argument that returns a array with properties or tabs.

display method

<?php

/**
 * Example of `display` method.
 */

public function display( $post_type ) {
  if ( $post_type === 'post' ) {
    return true;
  }

  return false;
}

This method is use to tell if the page type should be display or not on Add New Page page.

The method will take a $post_type argument. This is useful when the page type is register one more then one post type.

Returning anything else then true will hide the page type.

Default value is true.

remove method

<?php

/**
 * Example of `register` method.
 */

public function register() {
  // A single metabox
  $this->remove( 'comments' );

  // Multiple metaboxes
  $this->remove( ['comments', 'editor'] );
}

It’s easy to remove metaboxes with the remove method. You can remove both post type support and meta boxes with remove.

Check out remove_post_type_support for right post type support or remove_meta_box for meta box slugs.

Namespaces

<?php

namespace Foo\Bar;

/**
 * Example of a page type with namespace.
 */

class Test_Page_Type extends \Papi_Page_Type {}

Papi has no problem to work with page types that have namespaces.

Properties

<?php

/**
 * Example of the default options.
 */

papi_property( [
  'after_class'  => '',
  'after_html'   => '',
  'before_class' => '',
  'before_html'  => '',
  'capabilities' => [],
  'default'      => '',
  'description'  => '',
  'disabled'     => false,
  'lang'         => false,
  'overwrite'    => false,
  'raw'          => false,
  'required'     => false,
  'rules'        => [],
  'settings'     => [],
  'sidebar'      => true,
  'slug'         => '',
  'sort_order'   => 100,
  'title'        => '',
  'type'         => 'string',
  'value'        => ''
] )

Papi has many different core properties (a field is a property in the page type) to start with and you can easy create your own using our Yeoman generator. The are several keys that all properties have.

The property type is loaded from the page type file instead of saving it in the database.

Key	Default	Description
after_class	string	Add custom css class to after div. Since 2.4.0
after_html	string	Output html after property html. Can be a html string or a callable function. Will be wrapped in a div with class `papi-after-html` and a data attribute with the property type. Since 2.3.0
after_class	string	Add custom css class to before div. Since 2.4.0
before_html	string	Output html before property html. Can be a html string or a callable function. Will be wrapped in a div with class `papi-before-html` and a data attribute with the property type. Since 2.3.0
capabilities	array	Can be a string with a role or capability or a array with many values
default	empty string	The default value that should be used when value is empty.
description	empty string	The introduction text that will appear below the title text of the property. You could write your help text here. With `\n` you can create new lines in the description
disabled	false	Disable the property, won’t show in WordPress admin
display	true	When using this key you can hide the property being displayed, it will have the class `papi-hide`. Since 2.4.0
lang	false	When using this key you can specify which language will show the property
overwrite	false	When property is used on post page you can overwrite post object properties with property value when `overwrite` is true.
raw	false	This will render the property without a table, good to use when creating a custom property that uses other
post_type	empty string	The post type that the property will be rendered for. Default is empty string that will be assigned the current post_type. Since 2.4.2

Note: be sure to have different slug for each properties on a page type, the same slug will not work great and you will lose data if you are using same slug for multiple properties.

Bool

type bool

<?php

/**
 * Example of bool.
 */

papi_property( [
  'title'    => 'True or false?',
  'slug'     => 'my_true_or_false_slug',
  'type'     => 'bool'
] )

/**
 * Example output.
 */

boolean true

Description

The property output a single checkbox, when clicked the output value will be true otherwise false.

Settings

No settings exists.

Checkbox

type checkbox

<?php

/**
 * Example of checkbox.
 */

papi_property( [
  'title'    => 'Categories',
  'slug'     => 'my_categories_slug',
  'type'     => 'checkbox',
  'settings' => [
    'items' => [
      'White' => '#ffffff',
      'Black' => '#000000'
    ]
  ]
] )

/**
 * Example output.
 */

array
(
  [0] => '#ffffff'
)

Description

With this property you can add multiple checkboxes. The key is the value that the user will se in the WordPress admin and the value is the value saved in the database.

Settings

Key	Default	Description
items	array	Array with checkboxes, value or key/value
selected	array	The seleceted key or array of keys

Color

type color

<?php

/**
 * Example of color.
 */

papi_property( [
  'title'    => 'Color',
  'slug'     => 'my_color_slug',
  'type'     => 'color'
] )

/**
 * Example output.
 */

string '#ffffff'

Description

The property output the WordPress color picker.

Settings

Key	Default	Description
show_input	true	Show the text input
palettes	array	Array with hex colors

Datetime

type datetime

<?php

/**
 * Example of datetime.
 */

papi_property( [
  'title'    => 'Datetime',
  'slug'     => 'my_datetime_slug',
  'type'     => 'datetime'
] )

/**
 * Example output.
 */

string '2014-11-21'

Description

The date property has a picker build in using Pikaday with time support.

Settings

Key	Default	Description
format	YYYY-MM-DD hh:mm:ss	Show the text input
show_seconds	false	Array with hex colors
show_time	true	Array with hex colors
use_24_hours	false	Array with hex colors

Divider

type divider

<?php

/**
 * Example of divider.
 */

papi_property( [
  'title'       => 'Divider',
  'type'        => 'divider',
  'description' => 'Non volutpat ultricies bibendum odio luctus.'
] )

/**
 * Example output.
 */

string '#ffffff'

Description

This property don’t output any form or something like that. It outputs a h3 tag with the title inside and the description below.

Settings

No settings exists.

type dropdown

<?php

/**
 * Example of select.
 */

papi_property( [
  'title'    => 'Dropdown',
  'slug'     => 'my_dropdown_slug',
  'type'     => 'dropdown',
  'settings' => [
    'items' => [
      'White' => '#ffffff',
      'Black' => '#000000'
    ]
  ]
] )

/**
 * Example output.
 */

string '#ffffff'

Description

With this property you can add a dropdown. The key is the value that the user will se in the WordPress admin and the value is the value saved in the database.

Settings

Key	Default	Description
items	array	Array with options, value or key/value
placeholder	empty string	Placeholder text that’s displayed when no option is slected.
selected	empty string	The select item that will be selected from start. The value should match a key of your items
select2	true	If true Select2 will be used, if false the native browser dropdown will be used. (since 2.2.0)

Editor

type editor

<?php

/**
 * Example of Property Editor.
 */

papi_property( [
  'title' => 'Editor',
  'slug'  => 'my_editor_slug',
  'type'  => 'editor'
] )

/**
 * Example output.
 */

// String of text.

Description

The WordPress editor.

Settings

No settings exists.

File

type file since 2.2.0

<?php

/**
 * Example of file.
 */

papi_property( [
  'title' => 'File',
  'slug'  => 'my_file_slug',
  'type'  => 'file'
] )

/**
 * Example output.
 */

stdClass Object
(
      [file] => '2014/09/text.txt'
      [alt] => ''
      [caption] => 'Caption text'
      [description] => 'Description text'
      [id] => 6
      [is_image] => false
      [title] => 'Title text'
      [url] => 'http://site.com/wp-content/uploads/2014/09/test.txt'
)

Description

With this property you can add a file from the WordPress media library. If the multiple setting is set to true the output will be a array with objects instead of just one object.

File example

Settings

Key	Default	Description
multiple	false	If true you can add multiple files

Flexible

type flexible

<?php

/**
 * Example of Flexible.
 */

papi_property( [
  'title'    => 'Flexible',
  'slug'     => 'my_flexible_slug',
  'type'     => 'flexible',
  'settings' => [
    'items' => [
      [
        'title' => 'Posts',
        'items' => [
          papi_property( [
            'type'  => 'string',
            'title' => 'Title',
            'slug'  => 'my_string_slug'
          ] ),
          papi_property( [
            'type'  => 'post',
            'title' => 'Post',
            'slug'  => 'my_post_slug'
          ] )
        ]
      ],
      [
        'title' => 'Image',
        'items' => [
          papi_property( [
            'type'  => 'string',
            'title' => 'Title',
            'slug'  => 'my_title_slug'
          ] ),
          papi_property( [
            'type'  => 'image',
            'title' => 'Image',
            'slug'  => 'my_image_slug'
          ] )
        ]
      ]
    ]
  ]
] )

/**
 * Example output.
 */

array
(
  [0] => array
  (
    [my_string_slug] => 'Test 1'
    [my_post_slug] => 'WP_Post object',
    [_layout] => 'posts'
  )

  [1] => array
  (
    [my_title_slug] => 'Test 2'
    [my_image_slug] => 'Image object',
    [_layout] => 'image'
  )
)

Description

The flexible property can create a repeater with different layouts that contains sub fields. That’s the big different from a repeater property. You can’t have a flexible or repeater in a flexible.

Flexible example

Settings

Key	Default	Description
add_new_label	‘Add new row’	Add new label text. Since 2.4.2
closed_rows	false	When this is true the existing rows will be closed when the page is loaded.
items	array	Array of key/value. See `Items key/value` section.
layout	'table’	Choose between `table` or `row`.
limit	-1 (no limit)	Prevent how many post references that can be added.

Items key/value

Key	Default	Description
items	array	The array of properties, the same key/values as `$this->property` method or `papi_property` function has. You can’t use repeater or flexible inside a flexible.
slug	string	The slug of the flexible layout. This is not required. If you don’t have a slug value it will be generated from the title.
title	string	The title of the flexible layout.

Filters

<?php

/**
 * Example of `papi/property/flexible/exclude` filter.
 */

add_filter( 'papi/property/flexible/exclude', function ( $exclude ) {
  return array_merge( $exclude, [
    'string'
  ] );
} );

Filter	Description
papi/property/flexible/exclude	Prevent properties from render and working in flexible

Gallery

type gallery

<?php

/**
 * Example of gallery.
 */

papi_property( [
  'title' => 'Gallery',
  'slug'  => 'my_gallery_slug',
  'type'  => 'gallery'
] )

/**
 * Example output.
 */

array(
  stdClass Object
  (
      [width] => 800
      [height] => 600
      [file] => '2014/09/cube.jpg'
      [sizes] => array
        (
          [thumbnail] => array
          (
            [file] => 'cube-150x150.jpg'
            [width] => 150
            [height] => 150
            [mime-type] => 'image/jpeg'
          )

          [medium] => array
          (
            [file] => 'cube-300x225.jpg'
            [width] => 300
            [height] => 225
            [mime-type] => 'image/jpeg'
          )

      )

      [image_meta] => array
        (
          [aperture] => 0
          [credit] =>
          [camera] =>
          [caption] =>
          [created_timestamp] => 0
          [copyright] =>
          [focal_length] => 0
          [iso] => 0
          [shutter_speed] => 0
          [title] =>
          [orientation] => 1
        )
      [alt] => 'Alt text'
      [caption] => 'Caption text'
      [description] => 'Description text'
      [id] => 6
      [is_image] => 1
      [title] => 'Title text'
      [url] => 'http://site.com/wp-content/uploads/2014/09/cube.jpg'
  )
)

Description

With this property you can add a multiple image from the WordPress media library.

Settings

No settings exists.

Hidden

type hidden

<?php

/**
 * Example of hidden.
 */

papi_property( [
  'slug'  => 'my_hidden_slug',
  'type'  => 'hidden',
  'value' => 'hidden value'
] )

/**
 * Example output.
 * The reference property does not save any values.
 */

Description

Hidden input field.

Settings

No settings exists.

Html

type html

<?php

/**
 * Example of html.
 */

papi_property( [
  'title'    => 'Information',
  'type'     => 'html',
  'settings' => [
    'html' => '<p>Hello, world</p>'
  ]
] )

/**
 * Example output.
 * The html property does not save any values.
 */

Description

The property output custom html row on the page type in WordPress admin.

Settings

Key	Default	Description
html	empty string	String with html or a callable function or method.

Image

type image

<?php

/**
 * Example of image.
 */

papi_property( [
  'title' => 'Image',
  'slug'  => 'my_image_slug',
  'type'  => 'image'
] )

/**
 * Example output.
 */

stdClass Object
(
      [width] => 800
      [height] => 600
      [file] => '2014/09/cube.jpg'
      [sizes] => array
        (
          [thumbnail] => array
          (
            [file] => 'cube-150x150.jpg'
            [width] => 150
            [height] => 150
            [mime-type] => 'image/jpeg'
          )

          [medium] => array
          (
            [file] => 'cube-300x225.jpg'
            [width] => 300
            [height] => 225
            [mime-type] => 'image/jpeg'
          )

      )

      [image_meta] => array
        (
          [aperture] => 0
          [credit] =>
          [camera] =>
          [caption] =>
          [created_timestamp] => 0
          [copyright] =>
          [focal_length] => 0
          [iso] => 0
          [shutter_speed] => 0
          [title] =>
          [orientation] => 1
        )
      [alt] => 'Alt text'
      [caption] => 'Caption text'
      [description] => 'Description text'
      [id] => 6
      [is_image] => true
      [title] => 'Title text'
      [url] => 'http://site.com/wp-content/uploads/2014/09/cube.jpg'
)

Description

With this property you can add a image from the WordPress media library.

Image example

Settings

No settings exists.

Link

type link

<?php

/**
 * Example of link.
 */

papi_property( [
  'title' => 'Link',
  'type'  => 'link'
] )

/**
 * Example output.
 */

object(stdClass)#4533 (3) {
  ["post_id"]=>
  int 0
  ["url"]=>
  string(12) "http://wordpress.org"
  ["title"]=>
  string(2) "DN"
  ["target"]=>
  string(0) ""
}

Description

Create a link using the editors link modal window.

Since 2.4.0 it will add post_id if it’s a internal link to output object.

Settings

No settings exists.

Number

type number

<?php

/**
 * Example of number.
 */

papi_property( [
  'title' => 'Number',
  'slug'  => 'my_number_slug',
  'type'  => 'number'
] )

/**
 * Example output.
 */

int 10

Description

The number property is the HTML5 number input field. No custom validation exists only the browsers validation will kick in. The value is saved as a string and the output is a string.

Settings

No settings exists.

Post

type post

<?php

/**
 * Example of post.
 */

papi_property( [
  'title'    => 'Post',
  'slug'     => 'my_post_slug',
  'type'     => 'post'
] )

/**
 * Example output.
 */

WP_Post Object
(
  [ID] => 203
  [post_author] => 1
  [post_date] => 2014-11-18 22:07:38
  [post_date_gmt] => 2014-11-18 22:07:38
  [post_content] =>
  [post_title] => 'The post title'
  [post_excerpt] =>
  [post_status] => publish
  [comment_status] => closed
  [ping_status] => closed
  [post_password] =>
  [post_name] => 'the_post_title'
  [to_ping] =>
  [pinged] =>
  [post_modified] => 2014-11-18 22:09:05
  [post_modified_gmt] => 2014-11-18 22:09:05
  [post_content_filtered] =>
  [post_parent] => 0
  [guid] => 'http://site.com/?page_id=203'
  [menu_order] => 0
  [post_type] => 'page'
  [post_mime_type] =>
  [comment_count] => 0
  [filter] => 'raw'
)

Description

With this property you can add reference to another post. It can’t handle multiple references like relationship

Settings

Key	Default	Description
placeholder	empty string	Placeholder text that’s displayed when no option is slected.
post_type	'post’	The post type that the property will load posts from. Can only be one post type
query	array	Append a `WP_Query` on all post types. Gist reference over `WP_Query`. Note that `post_type` in query will always be removed
select2	true	If true Select2 will be used, if false the native browser dropdown will be used. (since 2.2.0)

Radio buttons

type radio

<?php

/**
 * Example of radio buttons.
 */

papi_property( [
  'title'    => 'Colors',
  'slug'     => 'my_radio_slug',
  'type'     => 'radio',
  'settings' => [
      'items' => [
        'White' => '#ffffff',
        'Black' => '#000000'
      ]
  ]
] )

/**
 * Example output.
 */

string '#ffffff'

Description

With this property you can create a list of radio buttons. The key is the value that the user will se in the WordPress admin and the value is the value saved in the database.

Settings

Key	Default	Description
items	array	Array with radio buttons, value or key/value
selected	empty string	The radio button that will be selected from start. The value should match a key of your items

Reference

type reference

<?php

/**
 * Example of reference.
 */

papi_property( [
  'title'    => 'References',
  'type'     => 'reference',
  'settings' => [
    'slug'      => 'top_module',
    'page_type' => 'start-page-type'
  ]
] )

/**
 * Example output.
 * The reference property does not save any values.
 */

Description

When using Post or Relationship property to load modules or something like that. You may what to check which pages are loading the module. This is where the reference property comes in hand, it will show which pages that has a reference to the module.

Reference example

Settings

Key	Default	Description
slug	array	String or array of slugs to look for references
page_type	empty string	String or array of page types (the file name of the page type) to check

Relationship

type relationship

<?php

/**
 * Example of relationship.
 */

papi_property( [
  'title'    => 'Relationship',
  'slug'     => 'my_relationship_slug',
  'type'     => 'relationship',
  'settings' => [
    'limit'     => 3,
    'post_type' => ['post', 'page', 'my-custom-post-type']
  ]
] )

/**
 * Example output.
 */

array
(
  [0] => WP_Post Object
  (
    [ID] => 203
    [post_author] => 1
    [post_date] => 2014-11-18 22:07:38
    [post_date_gmt] => 2014-11-18 22:07:38
    [post_content] =>
    [post_title] => 'The post title'
    [post_excerpt] =>
    [post_status] => 'publish'
    [comment_status] => 'closed'
    [ping_status] => 'closed'
    [post_password] =>
    [post_name] => 'the_post_title'
    [to_ping] =>
    [pinged] =>
    [post_modified] => 2014-11-18 22:09:05
    [post_modified_gmt] => 2014-11-18 22:09:05
    [post_content_filtered] =>
    [post_parent] => 0
    [guid] => 'http://site.com/?page_id=203'
    [menu_order] => 0
    [post_type] => 'page'
    [post_mime_type] =>
    [comment_count] => 0
    [filter] => 'raw'
  )
)

Description

With this property you can link posts, pages or custom post types together. With the post_type setting you can diced witch post types to use, default is page.

Relationship example

Settings

Key	Default	Description
items	array	Array of items that should be listed in the relationship. You can use this to have your own data in the relationship property. Each item in the array is required to have `id` and `title` values. All sort options that begins with `Post` will be hidden. Since 2.4.0
limit	-1 (no limit)	Prevent how many post references that can be added.
only_once	false	When this is true you can only select a relationship once. Since 2.4.0
post_type	'page’	Change which post types it loads post objects from
query	array	Append a `WP_Query` on all post types. Gist reference over `WP_Query`. Note that `post_type` in query will always be removed
show_sort_by	true	Show the sort by dropdown or not.

Items data

<?php

/**
 * Example of custom data in relationship.
 */

$categories = array_map( function ( $cat ) {
  return [
    'id'    => (int) $cat->term_id,
    'title' => $cat->name
  ];
}, get_categories() );

papi_property( [
  'title'    => 'Categories'
  'type'     => 'relationship',
  'settings' => [
    'items' => $categories
  ]
] )

Filters

<?php

/**
 * Example of `papi/property/relationship/sort_options` filter.
 */

add_filter( 'papi/property/relationship/sort_options', function ( $not_allowed ) {
  return array_merge( $not_allowed, [
    'Name (alphabetically)' => function ( $a, $b ) {
      // Backwards compatibility with both `post_title` and `title`.
            return strcmp(
                strtolower( isset( $a->post_title ) ? $a->post_title : $a->title ),
                strtolower( isset( $b->post_title ) ? $b->post_title : $b->title )
            );
    }
  ] );
} );

Filter	Description
papi/property/relationship/sort_options	Add more sort options to property relationship. The array key is the name and the value that is saved as the sort order identification

Repeater

type repeater

<?php

/**
 * Example of repeater.
 */

papi_property( [
  'title'    => 'Repeater',
  'slug'     => 'my_repeater_slug',
  'type'     => 'repeater',
  'settings' => [
    'items' => [
      papi_property( [
        'type'  => 'string',
        'title' => 'Title',
        'slug'  => 'my_string_slug'
      ] ),
      papi_property( [
        'type'     => 'dropdown',
        'title'    => 'Color',
        'slug'     => 'my_dropdown_slug',
        'settings' => [
          'items' => [
            'White' => '#ffffff',
            'Black' => '#000000'
          ]
        ]
      ] )
    ]
  ]
] )

/**
 * Example output.
 */

array
(
  [0] => array
  (
    [my_string_slug] => 'Test 1'
    [my_dropdown_slug] => '#ffffff'
  )

  [1] => array
  (
    [my_string_slug] => 'Test 2'
    [my_dropdown_slug] => '#000000'
  )
)

Description

The repeater property can create a repeater of sub fields which can be repeated again and again. You can’t have a flexible or repeater in a repeater.

Repeater example

Settings

Key	Default	Description
add_new_label	'Add new row’	Add new label text. Since 2.4.2
closed_rows	false	When this is true the existing rows will be closed when the page is loaded.
items	array	The array of properties, the same key/values as `$this->property` method or `papi_property` function has. You can’t use repeater or flexible inside a repeater.
layout	'table’	Choose between `table` or `row`.
limit	-1 (no limit)	Prevent how many post references that can be added.

Filters

<?php

/**
 * Example of `papi/property/repeater/exclude` filter.
 */

add_filter( 'papi/property/repeater/exclude', function ( $exclude ) {
  return array_merge( $exclude, [
    'string'
  ] );
} );

Filter	Description
papi/property/repeater/exclude	Prevent properties from render and working in repeater

String

type string

<?php

/**
 * Example of string.
 */

papi_property( [
  'title' => 'Name',
  'slug'  => 'my_name_slug',
  'type'  => 'string'
  'settings' => [
    'allow_html' => true
  ]
] )

/**
 * Example output.
 */

string 'Fredrik'

Description

The string property is just a text input field. The value is saved as a string and the output is a string.

Settings

Key	Default	Description
allow_html	false	Allow HTML in text input field

Term

type object

<?php

/**
 * Example of term.
 */

papi_property( [
  'title'    => 'Term',
  'slug'     => 'my_term_slug',
  'type'     => 'term',
  'settings  => [
    'taxonomy' => 'my_taxonomy'
  ]
] )

/**
 * Example output.
 */

stdClass Object
(
    [term_id] => '123'
    [name] => 'The term'
    [slug] => 'the_term'
    [term_group] => '0'
    [term_order] => '0'
    [term_taxonomy_id] => '321'
    [taxonomy] => 'my_taxonomy'
    [description] => ''
    [parent] => '0'
    [count] => '0'
    [object_id] => ''
)

Description

With this property you can add reference to a term in a taxonomy. It can’t handle multiple terms or taxonomies.

Settings

Key	Default	Description
placeholder	null	Placeholder text that’s displayed when no option is slected.
taxonomy	'post’	The taxonomy that the property will load terms from. Can only be one taxonomy.
select2	true	If true Select2 will be used, if false the native browser dropdown will be used.
query	array	Add `get_terms` arguments.

Text

type text

<?php

/**
 * Example of text.
 */

papi_property( [
  'title' => 'Text',
  'slug'  => 'my_text_slug',
  'type'  => 'text',
  'settings' => [
    'allow_html' => true
  ]
] )

/**
 * Example output.
 */

string 'Fredrik'

Description

This property will output the textarea tag and the output will be a string with all text from the textarea.

Settings

Key	Default	Description
allow_html	false	Allow HTML in textarea

Url

type url

<?php

/**
 * Example of url.
 */

papi_property( [
  'title'    => 'Url with button',
  'slug'     => 'my_url_slug',
  'type'     => 'url',
  'settings' => [
    'mediauploader' => true
  ]
] )

/**
 * Example output.
 */

string 'http://site.com/wp-content/uploads/2014/11/image.png'

Description

This property will output the textarea tag and the output will be a string with all text from the textarea.

Url example

Settings

Key	Default	Description
mediauploader	false	When this is `true` a button will show next to the input field where you can open the WordPress media library

User

type user since 2.2.0

<?php

/**
 * Example of user.
 */

papi_property( [
  'title'    => 'User',
  'slug'     => 'my_user_slug',
  'type'     => 'user'
] )

/**
 * Example output.
 */

object( WP_User )//327 (7) {
  ["data"]=>
  object( stdClass )//323 (10) {
    ["ID"]=>
    string( 1 ) "1"
    ["user_login"]=>
    string( 5 ) "admin"
    ["user_pass"]=>
    string( 34 ) ""
    ["user_nicename"]=>
    string( 5 ) "admin"
    ["user_email"]=>
    string( 24 ) "admin@wordpress.local"
    ["user_url"]=>
    string( 0 ) ""
    ["user_registered"]=>
    string( 19 ) "2015-04-19 12:27:23"
    ["user_activation_key"]=>
    string( 0 ) ""
    ["user_status"]=>
    string( 1 ) "0"
    ["display_name"]=>
    string( 14 ) "Admin Test"
  }
  ["ID"]=>
  int( 1 )
  ["caps"]=>
  array( 1 ) {
    ["administrator"]=>
    bool( true )
  }
  ["cap_key"]=>
  string( 15 ) "wp_capabilities"
  ["roles"]=>
  array( 1 ) {
    [0]=>
    string( 13 ) "administrator"
  }
  ["allcaps"]=>
  array( 64 ) {}
  ["filter"]=>
  NULL
}

Description

With this property you can add reference to a user.

Settings

Key	Default	Description
select2	true	If true Select2 will be used, if false the native browser dropdown will be used. (since 2.2.0)

Property filters

Format Value

filter papi/format_value/{$property_type}

<?php

/**
 * Example of `papi/format_value/{$property_type}` filter.
 */

add_filter( 'papi/format_value/string', function ( $value, $slug, $post_id ) {
  // do some magic with the value and return it.
  return $value;
}, 10, 3 );

Description

Format the value of the property before it’s returned to the theme.

Load Value

filter papi/load_value/{$property_type}

<?php

/**
 * Example of `papi/load_value/{$property_type}` filter.
 */

add_filter( 'papi/load_value/string', function ( $value, $slug, $post_id ) {
  // do some magic with the value and return it.
  return $value;
}, 10, 3 );

Description

This filter is applied after the value is loaded in the database.

Update Value

filter papi/update_value/{$property_type}

<?php

/**
 * Example of `papi/update_value/{$property_type}` filter.
 */

add_filter( 'papi/update_value/string', function ( $value, $slug, $post_id ) {
  // do some magic with the value and return it.
  return $value;
}, 10, 3 );

Description

This filter is applied before the value is saved in the database.

Conditional logic

Since 2.2.0 Papi has conditional logic for properties. So you can show or hide a field depending on the value of other fields.

Since 2.4.0 When a property has display => false conditional logic will not have any impact on the property.

The example on the right will hide Link field since Show field is false when you load the page. When you click the Show it will do ajax call and check if Link field should be showed or not depending on the value of Show.

<?php

$this->box( 'Content', [
  papi_property( [
    'type'  => 'bool',
    'title' => 'Show',
    'slug'  => 'show'
  ] ),
  papi_property( [
    'type'  => 'string',
    'title' => 'Link',
    'slug'  => 'link',
    'rules' => [
      [
        'operator' => '=',
        'value'    => true,
        'slug'     => 'show'
      ]
    ]
  ] )
] );

Relation

Like in WP Query you can have relation between rules. It can be OR or AND. The default value is OR. In the example on the right the relation has AND value. The relation key should exist on the top level array.

<?php

$this->box( 'Content', [
  papi_property( [
    'type'  => 'bool',
    'title' => 'Show',
    'slug'  => 'show'
  ] ),
  papi_property( [
    'type'  => 'bool',
    'title' => 'Hide',
    'slug'  => 'hide'
  ] ),
  papi_property( [
    'type'  => 'string',
    'title' => 'Link',
    'slug'  => 'link',
    'rules' => [
      'relation' => 'AND',
      [
        'operator' => '=',
        'value'    => true,
        'slug'     => 'show'
      ],
      [
        'operator' => '=',
        'value'    => false,
        'slug'     => 'hide'  
      ]
    ]
  ] )
] );

Rule

A single rule has four different keys. The rule should be a array in the top level rules array.

Key	Default	Description
operator	`=`	The operator to use. Possible values are `=`, `!=`, `>`, `>=`, `<`, `<=`, `LIKE`, `NOT LIKE`, `IN`, `NOT IN`, `BETWEEN`, `NOT BETWEEN`, `EXISTS`, `NOT EXISTS`, `EMPTY` and `NOT EMPTY`
slug	empty string	The slug of the property to read from.
source	null	The source to compare the value with instead of fetching it from field or database. Possible values are callable function (no closure), mixed values.
value	null	The value to compare to.

Operators

Operator	Example value	Description
`=`	true	Equal value
`!=`	false	Not equal value
`>`	12	Greater then a number
`>=`	13	Greater then or equal a number
`<`	14	Less then a number
`<=`	15	Less then or equal a number
`LIKE`	`hello`	Check if a string contains the value
`NOT LIKE`	`hello`	Check if a string not contains the value
`IN`	[1, 2]	In array
`NOT IN`	[3, 4]	Not in array
`BETWEEN`	[5, 6]	Between two numbers
`NOT BETWEEN`	[7, 8]	Not between two numbers
`EXISTS`		Property value should not be null or empty array (Papi does not save empty arrays)
`NOT EXISTS`		Property value should be null or empty array (Papi does not save empty arrays)
`EMPTY`		Property value should be empty. ‘0’, 0 and false are not empty.
`NOT EMPTY`		Property value should not be empty. '0’, 0 and false are not empty.

Flexible and Repeater

In a flexible conditional logic will only work on the same row. The rule slug in flexible or repeater properties should be the same slug as the property and nothing more advanced like flexible or repeater slug and child property slug. So not my_repeater_slug.my_child_slug or my_repeater_slug.0.my_child_slug just my_child_slug. Papi will find right property to use.

Setting filters

Change column title for page type column.

filter papi/settings/column_title_{$post_type}

<?php

/**
 * Example of `papi/settings/column_title_{$post_type}` filter.
 */

add_filter( 'papi/settings/column_title_module', function ( $page_type ) {
 return __( 'Module Type', 'my_theme' );
} );

Change default sort order

filter papi/settings/sort_order

<?php

/**
 * Example of `papi/settings/sort_order` filter.
 */

add_filter( 'papi/settings/sort_order', function () {
  return 1;
} );

Description

Change the default sort order for page types, meta boxes, tabs and properties.

Default sort order is 1000

Change standard page description for post type

filter papi/settings/standard_page_description_{$post_type}

<?php

/**
 * Example of `papi/settings/standard_page_description_{$post_type}` filter.
 */

add_filter( 'papi/settings/standard_page_description_post', function ( $page_type ) {
  return __( 'The standard blog post', 'my_theme' );
} );

Description

This filter is used to change the standard page description for a post type.

Default value is the translation of Page with WordPress standard fields where Page will be the singular name for the post type.

Change standard page name for post type

filter papi/settings/standard_page_name_{$post_type}

<?php

/**
 * Example of `papi/settings/standard_page_description_{$post_type}` filter.
 */

add_filter( 'papi/settings/standard_page_description_post', function ( $page_type ) {
  return __( 'Blog page', 'my_theme' );
} );

Description

This filter is used to change the standard page name for a post type.

Default value is the translation of Standard Page where Page will be the singular name for the post type.

Change standard page thumbnail for post type

filter papi/settings/standard_page_thumbnail_{$post_type}

<?php

/**
 * Example of `papi/settings/standard_page_thumbnail_{$post_type}` filter.
 */

add_filter( 'papi/settings/standard_page_thumbnail_post', function () {
  return '/path/to/thumbnail.png';
} );

Description

This filter is used to change the standard page thumbnail for a post type.

Default value is the translation of empty string

Load page type from post id query string

filter papi/settings/page_type_from_post_qs

<?php

/**
 * Example of `papi/settings/page_type_from_post_qs` filter.
 */

add_filter( 'papi/settings/page_type_from_post_qs', function () {
  return 'parent_post';
} );

Description

This filter is used to load a page type from a query string that have another post id.

When using plugins as Polylang the query string from_post is used to tell which post the current post was created from.

Papi will not now which page type to load then and it should be the same as the from_post. So that’s when this filter will be useful.

This filter is not post type specific and will work on every post type.

Default value is from_post.

Only page type for post type

filter papi/settings/only_page_type_{$post_type}

<?php

/**
 * Example of `papi/settings/only_page_type_{$post_type}` filter.
 */

add_filter( 'papi/settings/only_page_type_post', function () {
  return 'post-page-type';
} );

Description

This filter is used to register all page type directories that Papi should look for page types in.

You can return a string or a array of strings.

Page type directories

filter papi/settings/directories

<?php

/**
 * Example of `papi/settings/directories` filter.
 */

add_filter( 'papi/settings/directories', function () {
  return false;
} );

Description

This filter is used to register all page type directories that Papi should look for page types in.

You can return a string or a array of strings.

Default value is empty array.

Show page type on add new page view

filter papi/settings/show_page_type_{$post_type}

<?php

/**
 * Example of `papi/settings/show_page_type_{$post_type}` filter.
 */

add_filter( 'papi/settings/show_page_type_post', function ( $page_type ) {
  if ( $page_type === 'start-page-type' ) {
      return false;
  }

  return true;
} );

Description

This filter is used to filter which page types that will be displayed or not on Add New Page page.

The function will send in the file name of post types as a argument.

Returning anything else then true will hide the page type on Add New Page page.

Default value for every page type is true

Show standard page type for post type

filter papi/settings/show_standard_page_type_{$post_type}

<?php

/**
 * Example of `papi/settings/show_standard_page_type_{$post_type}` filter.
 */

add_filter( 'papi/settings/show_standard_page_type_page', '__return_false' );

Description

This filter allows you to show (since 2.4.0 standard page is hidden by default) the standard page on the Add New Page view.

Default value for every post type is false

Show standard page type in filter

filter papi/settings/show_standard_page_type_in_filter_{$post_type}

<?php

/**
 * Example of `papi/settings/show_standard_page_type_in_filter_{$post_type}` filter.
 */

add_filter( 'papi/settings/show_standard_page_type_in_filter_page', '__return_false' );

Description

This filter allows you to show (since 2.4.0 standard page is hidden by default) the standard page in the dropdown filter on the list page.

Default value for every post type is false

Custom property

It’s easy to create your own property with Papi. You can use our Yo generator

It’s important that the class follow the property class name standard in Papi.

<?php

// Bad
class PropertyStringx extends Papi_Property {}

class Property_Stringx extends Papi_Property {}

class Papi_Property_String_x extends Papi_Property {}

// Good
// type: string
class Papi_Property_Stringx extends Papi_Property {}

// type: image_video
class Papi_Property_Image_Video extends Papi_Property {}

Example bootstrap and property class:

The html method is the important one, with out that there aren’t going to be any property output in WordPress admin.

Read more about the Papi_Property in the class documentation.

<?php

// bootstrap.php
add_action( 'papi/include', function () {
  require_once 'class-papi-property-stringx.php';
} );

// class-papi-property-stringx.php

// Exit if accessed directly
defined( 'ABSPATH' ) || exit;

/**
 * Papi - Custom property string
 */

class Papi_Property_Stringx extends Papi_Property {

  /**
   * Get default settings.
   *
   * @return array
   */

  public function get_default_settings() {
    return [
      'allow_html' => false
    ];
  }

  /**
   * Generate the HTML for the property.
   */

  public function html() {
    ?>
      <input type="text" name="<?php echo $this->html_name(); ?>" value="<?php echo $this->get_value(); ?>" />
    <?php
  }

}

Introduction

Requirements

Installation

Upgrade guide

Upgrade to 2.x from 1.x

API

API Field

API Page

Properties

Dropdown and Post property

Relationship property

Settings filters

Show standard page type for post type

Page Type Directory

Actions

Delete value

Description

Include plugins or properties

Description

API

papi_get_page_type_key

Description

papi_get_slugs

Description

Parameters

papi_property

Description

Parameters

papi_tab

Description

Parameters

papi_template

Description

Parameters

API Field

papi_delete_field

Description

Parameters

papi_get_field

Description

Parameters

papi_update_field

Description

Parameters

the_papi_field

Description

Parameters

API Page

papi_get_page

Description

Parameters

papi_get_page_type_id

Description

Parameters

papi_get_page_type_name

Description

Parameters

the_papi_page_type_name

Description

Parameters

API Option

papi_delete_option

Description

Parameters

papi_get_option

Description

Parameters

papi_update_option

Description

Parameters

the_papi_option

Description

Parameters

Box (meta box)

Options

Callable method

Import and Export

Import

Parameters

Drivers