ACF

An Advanced Custom Fields helper for WordPlate.

If you're working with multiple developers on a WordPress application with custom fields it can be hard to keep track of changes made in custom fields. This package will help you register advanced custom fields with PHP without caring about field keys. All fields will have their own helper function that automagically create unique field keys based on their parent field group. All fields exists within the theme and can be added to version control.

Installation

Require this package, with Composer, in the root directory of your project.

$ composer require wordplate/acf

Download the Advanced Custom Fields Pro plugin and put it in either the plugins or mu-plugins directory. Visit the WordPress dashboard and activate the plugin. Please note that this package supports ACF version 5.6 or later.

ACF Pro

If you want to install ACF Pro with Composer you may use the repositories feature. Add the snippet below to your composer.json file. Replace your-acf-key with your ACF Pro key and run composer install. Composer should now install the plugin to the plugins directory.

"repositories": [
    {
        "type": "package",
        "package": {
            "name": "wpackagist-plugin/advanced-custom-fields-pro",
            "type": "wordpress-plugin",
            "version": "5.6.10",
            "dist": {
                "url": "https://connect.advancedcustomfields.com/index.php?v=5.6.10&p=pro&a=download&k=your-acf-key",
                "type": "zip"
            }
        }
    }
]

Usage

Use the acf_field_group() helper function to register a new field group in ACF. It uses the acf_add_local_field_group() function behind the scenes. The difference is that it appends the key value to all fields. Below you'll find an example of a field group.

$fields = [
    acf_image(['name' => 'image', 'label' => 'Image']),
    acf_text(['name' => 'title', 'label' => 'Title']),
];

$location = [
    [
        acf_location('post_type', 'page')
    ],
];

acf_field_group([
    'title' => 'About',
    'fields' => $fields,
    'style' => 'seamless',
    'location' => $location,
]);

Visit the official documentation to read more about the field group settings.

Fields

All fields accepts an array of settings. All field settings arrays must have the keys label and name. Below the example you'll find a list of available field functions.

acf_text([
    'name' => 'unique-field-name',
    'label' => 'Field Label',
    'instructions' => 'Add the text value',
    'required' => true,
]);

Settings

Below you'll find a list of settings and their descriptions you can add to your fields. Please note that the type and key values will be automagically added by this package. Please don't add these values manually, they will be overwritten. Visit the official documentation to read more about the field settings.

Name	Description
`label`	This is the label which appears on the edit page when entering a value.
`name`	This is the name used to save and load data from the database. This name must be a single word, no spaces, underscores and dashes allowed.
`instructions`	This text appears on the edit page when entering a value.
`required`	Required fields will cause validation to run when saving a post. When attempting to save an empty value to a required field, an error message will display.
`conditional_logic`	Once enabled, more settings will appear to customize the logic which determines if the current field should be visible or not. Groups of conditional logic can be created to allow for multiple and/or statements. The available toggle fields are limited to those which are of the type select, checkbox, true/false, radio.
`wrapper`	The array of attributes given to the field element such as width, class and id.
`prepend`	The prepend value adds a visual text element before the input.
`append`	The append value adds a visual text element before the input.
`default_value`	The default value if no value has yet been saved.
`placeholder`	The placeholder appears within input when no value exists.

Basic Fields

Email - The email field creates a simple email input.

acf_email([
    'name' => 'email',
    'label' => 'Email',
    'instructions' => 'Add the employees email address.',
    'required' => true,
]);

Number - The number field creates a simple number input.

acf_number([
    'name' => 'age',
    'label' => 'Age',
    'instructions' => 'Add the employees age.',
    'required' => true,
    'min' => 18,
    'max' => 65,
]);

Password - The password field creates a simple password input.

acf_password([
    'name' => 'password',
    'label' => 'Password',
    'instructions' => 'Add the employees secret pwned password.',
    'required' => true,
]);

Range - The range field provides an interactive experience for selecting a numerical value.

acf_range([
    'name' => 'rate',
    'label' => 'Rate',
    'instructions' => 'Add the employees completion rate.',
    'required' => true,
    'min' => 0,
    'max' => 100,
]);

Text - The text field creates a simple text input.

acf_text([
    'name' => 'name',
    'label' => 'Name',
    'instructions' => 'Add the employees name.',
    'required' => true,
]);

Textarea - The textarea field creates a simple textarea.

acf_textarea([
    'name' => 'biography',
    'label' => 'Biography',
    'instructions' => 'Add the employees biography.',
    'required' => true,
    'rows' => 3,
]);

URL - The url field creates a simple url input.

acf_url([
    'name' => 'website',
    'label' => 'Website',
    'instructions' => 'Add the employees website link.',
    'required' => true,
]);

Choice Fields

Button Group - The button group field creates a list of radio buttons.

acf_button_group([
    'name' => 'color',
    'label' => 'Color',
    'instructions' => 'Select the box shadow color.',
    'required' => true,
    'choices' => [
        'cyan' => 'Cyan',
        'hotpink' => 'Hotpink',
    ],
    'default_value' => [
        'hotpink',
    ],
]);

Checkbox - The checkbox field creates a list of tick-able inputs.

acf_checkbox([
    'name' => 'color',
    'label' => 'Color',
    'instructions' => 'Select the border color.',
    'required' => true,
    'choices' => [
        'cyan' => 'Cyan',
        'hotpink' => 'Hotpink',
    ],
    'default_value' => [
        'hotpink',
    ],
]);

Radio - The radio button field creates a list of select-able inputs.

acf_radio([
    'name' => 'color',
    'label' => 'Color',
    'instructions' => 'Select the text color.',
    'required' => true,
    'choices' => [
        'cyan' => 'Cyan',
        'hotpink' => 'Hotpink',
    ],
    'default_value' => [
        'cyan',
    ],
]);

Select - The select field creates a drop down select or multiple select input.

acf_select([
    'name' => 'color',
    'label' => 'Color',
    'instructions' => 'Select the background color.',
    'required' => true,
    'choices' => [
        'cyan' => 'Cyan',
        'hotpink' => 'Hotpink',
    ],
    'default_value' => [
        'cyan',
    ],
]);

True False - The true / false field allows you to select a value that is either 1 or 0.

acf_true_false([
    'name' => 'display-social-media',
    'label' => 'Social Media',
    'instructions' => 'Select whether to display social media links or not.',
    'default_value' => false,
    'ui' => true,
]);

Content Fields

File - The file field allows a file to be uploaded and selected.

acf_file([
    'name' => 'menu',
    'label' => 'Menu',
    'instructions' => 'Add the menu <strong>pdf</strong> file.',
    'required' => true,
    'library' => 'all',
    'mime_types' => 'pdf',
    'return_format' => 'array',
]);

Gallery - The gallery field provides a simple and intuitive interface for managing

acf_gallery([
    'name' => 'images',
    'label' => 'Images',
    'instructions' => 'Add the gallery images.',
    'required' => true,
    'mime_types' => 'jpeg, jpg, png',
    'min_height' => 1000,
    'min_width' => 1200,
    'min' => 1,
    'max' => 6,
]);

Image - The image field allows an image to be uploaded and selected.

acf_image([
    'name' => 'background-image',
    'label' => 'Background Image',
    'instructions' => 'Add an image in at least 12000x100px and only in the formats <strong>jpg</strong>, <strong>jpeg</strong> or <strong>png</strong>.',
    'library' => 'all',
    'mime_types' => 'jpeg, jpg, png',
    'min_height' => 1000,
    'min_width' => 1200,
    'preview_size' => 'medium',
    'return_format' => 'array',
]);

Oembed - The oEmbed field allows an easy way to embed videos, images, tweets, audio, and other content.

acf_oembed([
    'name' => 'tweet',
    'label' => 'Tweet',
    'instructions' => 'Add a tweet from Twitter.',
    'required' => false,
]);

WYSIWYG - The WYSIWYG field creates a full WordPress tinyMCE content editor.

acf_wysiwyg([
    'name' => 'content',
    'label' => 'Content',
    'instructions' => 'Add the text content.',
    'required' => true,
    'media_upload' => false,
    'tabs' => 'visual',
    'toolbar' => 'simple',
]);

jQuery Fields

Color Picker - The color picker field allows a color to be selected via a JavaScript popup.

acf_color_picker([
    'name' => 'text-color',
    'label' => 'Text Color',
    'instructions' => 'Add the text color.',
    'default_value' => '#4a9cff',
]);

Date Picker - The date picker field creates a jQuery date selection popup.

acf_date_picker([
    'name' => 'birthday',
    'label' => 'Birthday',
    'instructions' => 'Add the employee\'s birthday.',
    'required' => true,
    'display_format' => 'd/m/Y',
	'return_format' => 'd/m/Y',
]);

Date Time Picker - The date time picker field creates a jQuery date & time selection popup.

acf_date_time_picker([
    'name' => 'date',
    'label' => 'Event date',
    'instructions' => 'Add the event\'s start date and time.',
    'required' => true,
    'display_format' => 'd-m-Y H:i',
	'return_format' => 'd-m-Y H:i',
]);

Google Map - The Google Map field creates an interactive map with the ability to place a marker.

acf_google_map([
    'name' => 'address',
    'label' => 'Address',
    'instructions' => 'Add the Google Map address.',
    'required' => true,
]);

Time Picker - The time picker field creates a jQuery time selection popup.

acf_time_picker([
    'name' => 'start_time',
    'label' => 'Start Time',
    'instructions' => 'Add the start time.',
    'required' => true,
    'display_format' => 'H:i',
    'return_format' => 'H:i',
]);

Layout Fields

Accordion - The accordion field is used to organize fields into collapsible panels.
Clone - The clone field allows you to select and display existing fields.
Flexible Content - The flexible content field acts as a blank canvas to which you can add an unlimited number of layouts with full control over the order.

acf_flexible_content([
  'name' => 'page_components',
  'label' => 'Components',
  'button_label' => 'Add a component',
  'layouts' => [] // Array of acf_layout (read the Layout part in Helpers)
]);

Group - The group allows you to create a group of sub fields.
Message - The message fields allows you to display a text message.
Repeater - The repeater field allows you to create a set of sub fields which can be repeated again and again whilst editing content!

acf_repeater([
    'name' => 'employees',
    'label' => 'Employees',
    'instructions' => 'Add the employees.',
    'required' => true,
    'min' => 2,
    'layout' => 'block', // block, row or table
    'sub_fields' => [
        acf_text([
            'name' => 'name',
            'label' => 'Name',
            'instructions' => 'Add the employee name.',
        ]),
    ],
]);

Tab - The tab field is used to group together fields into tabbed sections.

Relational Fields

Link - The link field provides a simple way to select or define a link (url, title, target).
Page Link - The page link field allows the selection of 1 or more posts, pages or custom post types.
Post Object - The post object field creates a select field where the choices are your pages + posts + custom post types.
Relationship - The relationship field creates a very attractive version of the post object field.

acf_relationship([
    'name' => 'contacts',
    'label' => 'Contacts',
    'instructions' => 'Add the contacts.',
    'post_type' => ['contact'],
    'required' => true,
    'filters' => '', // Ugly hack to hide filters and search.
    'max' => 6,
    'min' => 3,
]);

Taxonomy - The taxonomy field allows the selection of 1 or more taxonomy terms.
User - The user field creates a select field for all your users.

Helpers

This package provides helper functions for conditional logic, layout, location and options pages to help you write less code.

Conditional Logic

The conditional function help you write conditional logic without knowing the fields key value.

acf_select([
    'name' => 'type',
    'label' => 'Type',
    'choices' => [
        'document' => 'Document',
        'link' => 'Link to resource',
    ],
]),
acf_file([
    'name' => 'file',
    'label' => 'Document',
    'conditional_logic' => [
        [
            acf_conditional('type', 'document')
        ],
    ],
]),
acf_url([
    'name' => 'url',
    'label' => 'Link',
    'conditional_logic' => [
        [
            acf_conditional('type', 'link')
        ],
    ],
]),

Layout

The layout function help you write flexible content layouts without knowing the fields key value.

acf_layout([
    'label' => 'Layout',
    'name' => 'layout',
    'sub_fields' => [ ... ]
]);

Instead of using get_row_layout and compare it against a string you may use the is_layout function.

if (is_layout('text')) {
    // Load the layout row template view.
}

Location

The location function help you write custom location rules without the name, operator and value keys.

acf_location('post_type', 'post');

acf_location('post_type', '!=', 'post');

Theming

This package provides two helpers to make theming with custom fields much cleaner.

Field

Instead of fetching data with get_field and get_sub_field you can use the field helper function. It works as the get_field function except that if checks if the given field name is a sub field first.

echo field('title');

Note: This will not work if nested fields in a field group share the same name.

Option

Instead of passing the option key to the get_field function we can now use the new option function. It will automagically use the get_field function with the option key.

echo option('github-url');

Resources

Below you'll find a list of articles which can help you getting started and advance your custom fields knowledge.

marlburrow / acf Goto Github PK

acf's Introduction

ACF