### Configure Composer Installer Paths Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/plugin-quickstart.md If your composer.json is not in the WordPress root, specify the installation path for WordPress plugins. Replace YOUR_DESIRED_LOCATION with the correct path. ```json { "extra": { "installer-paths": { "YOUR_DESIRED_LOCATION/vendor/{$vendor}/{$name}/": ["type:wordpress-plugin"] } } } ``` -------------------------------- ### Create Image Field Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/fields/usage.md Example of creating an image field with a specific name and label. ```php Field::make( 'image', 'crb_customer_photo', 'Photo' ) ``` -------------------------------- ### Show Post Meta Container on Static Home Page Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/containers/conditional-display.md This example shows how to display a post meta container specifically on the site's static home page. ```php Container::make( 'post_meta', 'Custom Data' ) ->where( 'post_id', '=', get_option( 'page_on_front' ) ) ->add_fields( array( ... ) ); ``` -------------------------------- ### Example HTML Output with Custom Colors Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/containers/nav-menu-item.md This HTML demonstrates how menu items with custom colors applied via Carbon Fields might be rendered in the frontend. ```html
``` -------------------------------- ### Basic Radio Field Setup Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/fields/radio.md This snippet demonstrates the basic creation of a radio field with numerical options. Use this for simple selections where numerical values are appropriate. ```php Field::make( 'radio', 'crb_radio', __( 'Choose Option' ) ) ->set_options( array( '1' => 1, '2' => 2, '3' => 3, '4' => 4, '5' => 5, ) ) ``` -------------------------------- ### Add Custom Installer Paths to Composer.json Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/advanced-topics/bedrock-support.md Configure `composer.json` to specify the installation directory for Carbon Fields assets when using `mnsami/composer-custom-directory-installer`. Replace `YOUR_DESIRED_PUBLIC_LOCATION` with the actual path in your project. ```json { "extra": { "installer-paths": { "YOUR_DESIRED_PUBLIC_LOCATION/vendor/{$vendor}/{$name}": ["htmlburger/carbon-fields"] } } } ``` -------------------------------- ### Create Sidebar Field Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/fields/usage.md Example of creating a sidebar field where the title is automatically set. ```php // Here the title is automatically set to "Custom Sidebar" Field::make( 'sidebar', 'crb_custom_sidebar' ) ``` -------------------------------- ### Basic Radio Image Field Setup Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/fields/radio-image.md Defines a Radio Image field with a title and sets image URLs as options. Use this when you want visual selection options for your users. ```php Field::make( 'radio_image', 'crb_background_image', __( 'Choose Background Image' ) ) ->set_options( array( 'mountain' => 'https://source.unsplash.com/X1UTzW8e7Q4/800x600', 'temple' => 'https://source.unsplash.com/ioJVccFmWxE/800x600', 'road' => 'https://source.unsplash.com/5c8fczgvar0/800x600', ) ) ``` -------------------------------- ### Install Carbon Fields with Composer Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/quickstart.md Use Composer to add Carbon Fields to your project's dependencies. This command should be run from your theme's directory. ```bash composer require htmlburger/carbon-fields ``` -------------------------------- ### Getting a Field's Value Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/advanced-topics/javascript-api.md Demonstrates how to retrieve the current value of a specific field using its name. ```APIDOC ## Getting a Field's Value ### Description Retrieves the current value of a specified field. ### Method `api.getFieldValue(fieldName)` ### Parameters * **fieldName** (string) - The name of the field whose value you want to retrieve. ### Returns * (any) - The current value of the field. ### Example ```js $(document).on('carbonFields.apiLoaded', function(e, api) { var value = api.getFieldValue( 'crb_text' ); }); ``` ``` -------------------------------- ### Add Custom Classes to a Field Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/fields/usage.md Example of adding custom CSS classes to a field using `set_classes()`. ```php Field::make(...)->set_classes( 'my-custom-class' ) ``` -------------------------------- ### Create a Gravity Form Field Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/fields/gravity-form.md Use this snippet to create a basic Gravity Form field. Ensure the Gravity Forms plugin is installed and activated. ```php Field::make( 'gravity_form', 'crb_gravity_form', __( 'Select a Form' ) ) ``` -------------------------------- ### Get API Object Instance Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/advanced-topics/javascript-api.md Listen for the 'carbonFields.apiLoaded' event to obtain the API object. This event fires when the Carbon Fields API is ready for use. ```javascript $(document).on('carbonFields.apiLoaded', function(e, api) { // your api actions here }); ``` -------------------------------- ### Create Multiselect Field Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/fields/multiselect.md Basic creation of a multiselect field with a label. This is the starting point for configuring the field. ```php Field::make( 'multiselect', 'crb_available_colors', __( 'Available Colors' ) ) ``` -------------------------------- ### Basic Textarea Field Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/fields/textarea.md Creates a basic textarea field for phone numbers. This is the foundational setup for a textarea input. ```php Field::make( 'textarea', 'crb_phone_numbers', __( 'Phone Numbers' ) ) ``` -------------------------------- ### Text Field with Placeholder Attribute Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/fields/text.md Configures a text field to display a placeholder. Use this to guide user input, like specifying a format. ```php Field::make( 'text', 'crb_phone_number', __( 'Phone Number' ) ) ->set_attribute( 'placeholder', '(***) ***-****' ) ``` -------------------------------- ### Setup Custom Labels for Complex Field Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/fields/complex.md Configures custom plural and singular names for a complex field, useful for clarifying the nature of the repeatable groups. ```php use Carbon_Fields\Field; use Carbon_Fields\Field\Complex_Field; $employees_labels = array( 'plural_name' => 'Employees', 'singular_name' => 'Employee', ); Field::make( 'complex', 'crb_employee_data' ) ->setup_labels( $employees_labels ) ->add_fields( array( Field::make( 'text', 'name')->set_help_text('Name of employee' ), Field::make( 'text', 'position')->set_help_text('Position title' ), Field::make( 'image', 'image' ), Field::make( 'rich_text', 'description' ), ) ) ``` -------------------------------- ### Use Custom Condition in Container Definition Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/extending/container-conditions.md Define a container and use the `where` method with your custom condition's key and operator. This example demonstrates a condition that will always return true. ```php Container::make( 'theme_options', __( 'Foobar Container' ) ) ->where( 'foobar', '=', 'foobar' ); // this will always return true // ->where( 'foobar', '=', 'lorem' ); // this will always return false ``` -------------------------------- ### Getting the API Object Instance Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/advanced-topics/javascript-api.md This snippet shows how to access the Carbon Fields API object once it's loaded. The `api` object is available within the `carbonFields.apiLoaded` event. ```APIDOC ## Getting the API Object Instance ### Description This event is fired when the Carbon Fields API is ready to be used. The `api` object is passed as an argument, allowing you to interact with fields. ### Usage Listen for the `carbonFields.apiLoaded` event on the document. ### Event `carbonFields.apiLoaded` ### Parameters * **e** (object) - The event object. * **api** (object) - The Carbon Fields API object. ``` -------------------------------- ### Define Post Meta Container and Text Field Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/guide/using-field-values.md Create a post meta container with a text field for 'Venue' that applies only to 'post' post types. This setup allows authors to input location-specific data for posts. ```php use Carbon_Fields\Field; use Carbon_Fields\Container; add_action( 'carbon_fields_register_fields', 'crb_attach_post_meta' ); function crb_attach_post_meta() { Container::make( 'post_meta', __( 'Post Options' ) ) ->where( 'post_type', '=', 'post' ) ->add_fields( array( Field::make( 'text', 'crb_venue', 'Venue' ), ) ); } ``` -------------------------------- ### Field Creation with Method Chaining Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/fields/usage.md Demonstrates creating a select field and chaining methods to add options and set help text. ```php // Method chaining Field::make( 'select', 'crb_color' ) ->add_options( array('red', 'blue', 'green') ) ->set_help_text( 'Pick a color' ) ``` -------------------------------- ### Textarea Field with Placeholder Attribute Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/fields/textarea.md Adds a placeholder attribute to the textarea field to guide user input. This is useful for providing examples or hints. ```php Field::make( 'textarea', 'crb_phone_numbers', __( 'Phone Numbers' ) ) ->set_attribute( 'placeholder', '(***) ***-****, ...' ) ``` -------------------------------- ### Get WPML Language Suffix Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/advanced-topics/wpml-support.md Helper function to get the language suffix for WPML. Returns an empty string if WPML is not defined. ```php function crb_get_i18n_suffix() { $suffix = ''; if ( ! defined( 'ICL_LANGUAGE_CODE' ) ) { return $suffix; } $suffix = '_' . ICL_LANGUAGE_CODE; return $suffix; } ``` -------------------------------- ### Create Multiple Theme Options Pages Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/containers/theme-options.md Demonstrates creating multiple theme option pages, including nesting them under existing admin menus or other theme option pages. Use `set_page_parent()` to define the parent. ```php use Carbon_Fields\Container; use Carbon_Fields\Field; // Default options page $basic_options_container = Container::make( 'theme_options', __( 'Basic Options' ) ) ->add_fields( array( Field::make( 'header_scripts', 'crb_header_script', __( 'Header Script' ) ), Field::make( 'footer_scripts', 'crb_footer_script', __( 'Footer Script' ) ), ) ); // Add second options page under 'Basic Options' Container::make( 'theme_options', __( 'Social Links' ) ) ->set_page_parent( $basic_options_container ) // reference to a top level container ->add_fields( array( Field::make( 'text', 'crb_facebook_link', __( 'Facebook Link' ) ), Field::make( 'text', 'crb_twitter_link', __( 'Twitter Link' ) ), ) ); // Add third options page under "Appearance" Container::make( 'theme_options', __( 'Customize Background' ) ) ->set_page_parent( 'themes.php' ) // identificator of the "Appearance" admin section ->add_fields( array( Field::make( 'color', 'crb_background_color', __( 'Background Color' ) ), Field::make( 'image', 'crb_background_image', __( 'Background Image' ) ), ) ); ``` -------------------------------- ### Create a Basic Theme Options Container Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/containers/theme-options.md Use this to create a single theme options page with basic fields. By default, only users with `manage_options` capability can access it. ```php use Carbon_Fields\Container; use Carbon_Fields\Field; Container::make( 'theme_options', __( 'Theme Options' ) ) ->add_fields( array( Field::make( 'text', 'crb_facebook_url', __( 'Facebook URL' ) ), Field::make( 'textarea', 'crb_footer_text', __( 'Footer Text' ) ) ) ); ``` -------------------------------- ### Complex Field Data Structure Example Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/fields/complex.md Complex field values are retrieved as multi-dimensional arrays. This example illustrates the expected format for a complex field containing slides and fragments. ```php array ( 0 => array ( 'photo' => 'http://example.com/lorem.jpg', 'people_on_photo' => array ( 0 => array ( 'name' => 'John', ), 1 => array ( 'name' => 'Karen', ) ) ), 1 => array ( 'photo' => 'http://example.com/ipsum.jpg', 'people_on_photo' => array ( 0 => array ( 'name' => 'Paul', ), 1 => array ( 'name' => 'Kasper', ), 2 => array ( 'name' => 'Julie', ), ) ), ) ``` -------------------------------- ### Create a User Meta Container Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/containers/user-meta.md Defines a new user meta container named 'Address' with text fields for city/post code and street name. Ensure Carbon Fields is loaded. ```php use Carbon_Fields\Container; use Carbon_Fields\Field; Container::make( 'user_meta', 'Address' ) ->add_fields( array( Field::make( 'text', 'crb_city_and_post', 'City and post code' ), Field::make( 'text', 'crb_street', 'Street Name' ), ) ); ``` -------------------------------- ### Show Post Meta Container on All Pages Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/containers/conditional-display.md This snippet demonstrates how to create a post meta container that is visible on all pages. ```php Container::make( 'post_meta', 'Custom Data' ) ->where( 'post_type', '=', 'page' ) ->add_fields( array( ... ) ); ``` -------------------------------- ### Include Autoload Script Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/extending/creating-custom-field.md Include the vendor/autoload.php file within your after_setup_theme function. This ensures that your custom field's dependencies are loaded correctly. ```php add_action( 'after_setup_theme', function() { // Include the Carbon Fields autoloader // Include your custom field autoloader require_once get_template_directory() . '/vendor/autoload.php'; }); ``` -------------------------------- ### Basic Association Field Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/fields/association.md Defines a basic association field. This is the starting point for creating an association field. ```php Field::make( 'association', 'crb_association', __( 'Association' ) ) ``` -------------------------------- ### Create a Set Field with Options Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/fields/set.md This snippet demonstrates how to create a basic 'set' field with predefined options. The options are provided as an associative array. ```php Field::make( 'set', 'crb_set', __( 'Choose Options' ) ) ->set_options( array( '1' => 1, '2' => 2, '3' => 3, '4' => 4, '5' => 5, ) ) ``` -------------------------------- ### Create a Basic Select Field Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/fields/select.md This snippet demonstrates how to create a basic select field with hardcoded options. ```php Field::make( 'select', 'crb_select', __( 'Choose Options' ) ) ->set_options( array( '1' => 1, '2' => 2, '3' => 3, '4' => 4, '5' => 5, ) ) ``` -------------------------------- ### Initialize Carbon Fields in functions.php Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/quickstart.md Add this PHP code to your theme's functions.php file to register Carbon Fields and define theme options. Ensure the autoloader is required and Carbon Fields is booted. ```php use Carbon_Fields\Container; use Carbon_Fields\Field; add_action( 'carbon_fields_register_fields', 'crb_attach_theme_options' ); function crb_attach_theme_options() { Container::make( 'theme_options', __( 'Theme Options' ) ) ->add_fields( array( Field::make( 'text', 'crb_text', 'Text Field' ), ) ); } add_action( 'after_setup_theme', 'crb_load' ); function crb_load() { require_once( 'vendor/autoload.php' ); \Carbon_Fields\Carbon_Fields::boot(); } ``` -------------------------------- ### Get Field Value Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/advanced-topics/javascript-api.md Use the `getFieldValue` method to retrieve the current value of a specific field. This is useful for reading user input or pre-populated data. ```javascript $(document).on('carbonFields.apiLoaded', function(e, api) { // Get the current value in the 'crb_text' field var value = api.getFieldValue( 'crb_text' ); }); ``` -------------------------------- ### Hook for Widget Initialization Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/containers/widgets.md This code snippet should be added to your theme's functions.php file to ensure your custom widgets are properly initialized. ```php add_action( 'widgets_init', 'load_widgets' ); ``` -------------------------------- ### Register and Render a Gutenberg Block Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/containers/gutenberg-blocks.md Use `Block::make()` to register a new Gutenberg block and `add_fields()` to define its fields. The `set_render_callback()` method specifies the HTML output for the block, receiving block data, attributes, and inner block content as arguments. ```php add_fields( array( Field::make( 'text', 'heading', __( 'Block Heading' ) ), Field::make( 'image', 'image', __( 'Block Image' ) ), Field::make( 'rich_text', 'content', __( 'Block Content' ) ), ) ) ->set_render_callback( function ( $fields, $attributes, $inner_blocks ) { ?>

set_options( $options ) ### Description Set options as an associative array or a callable. The method is not intended to be called multiple times – each call will overwrite the previous options. ### Parameters #### Parameters - **options** (array|callable) - An associative array of options where keys are option values and values are display labels, or a callable that returns such an array. ### Note If you provide an indexed array with no key values, the default indexes (0, 1, 2 …) of the elements will be used. ``` -------------------------------- ### Define and Register a Custom Widget Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/containers/widgets.md This snippet shows how to create a custom widget class extending Carbon_Fields\Widget, define its fields, and render it on the front-end. It also includes the necessary function to register the widget. ```php use Carbon_Fields\Widget; use Carbon_Fields\Field; class ThemeWidgetExample extends Widget { // Register widget function. Must have the same name as the class function __construct() { $this->setup( 'theme_widget_example', 'Theme Widget - Example', 'Displays a block with title/text', array( Field::make( 'text', 'title', 'Title' )->set_default_value( 'Hello World!') , Field::make( 'textarea', 'content', 'Content' )->set_default_value( 'Lorem Ipsum dolor sit amet' ) ) ); } // Called when rendering the widget in the front-end function front_end( $args, $instance ) { echo $args['before_title'] . $instance['title'] . $args['after_title']; echo '

' . $instance['content'] . '

'; } } function load_widgets() { register_widget( 'ThemeWidgetExample' ); } ``` -------------------------------- ### Create a Sidebar Field Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/fields/sidebar.md Use this to create a new sidebar field in your Carbon Fields setup. This field allows users to select or manage sidebars. ```php Field::make( 'sidebar', 'crb_custom_sidebar', __( 'Select a Sidebar' ) ) ``` -------------------------------- ### Create a Basic Time Field Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/fields/time.md This snippet demonstrates how to create a basic time field using the `Field::make()` method. ```php Field::make( 'time', 'opens_at', __( 'Opening time' ) ) ``` -------------------------------- ### Get WPML Theme Option Value Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/advanced-topics/wpml-support.md Retrieves a theme option value, appending the WPML language suffix to the option name. Requires the 'crb_get_i18n_suffix' function. ```php function crb_get_i18n_theme_option( $option_name ) { $suffix = crb_get_i18n_suffix(); return carbon_get_theme_option( $option_name . $suffix ); } ``` -------------------------------- ### Nested Logic for Conditional Display Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/containers/conditional-display.md Demonstrates how to implement complex, nested display logic using callable functions within `where()` and `or_where()` methods. ```php Container::make( 'post_meta', 'Custom Data' ) ->where( function( $lvl1_condition ) { $lvl1_condition->where( $condition, $comparison_operator, $value ); $lvl1_condition->where( function( $lvl2_condition ) { ... // can be nested infinitely } ); ... } ); ``` -------------------------------- ### Install Carbon Fields Plugin with Composer Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/plugin-quickstart.md Use Composer to add the Carbon Fields plugin package to your WordPress project. This is the recommended method for managing dependencies. ```cli composer require htmlburger/carbon-fields-plugin ``` -------------------------------- ### Setting a Color Palette Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/fields/color.md Configure the color picker with a predefined palette of colors. ```APIDOC ## `set_palette( $palette = array() )` ### Description Sets the color picker's palette of predefined colors. The `$palette` must be an array of hexadecimal colors. ### Method Signature ```php ->set_palette( array( '#FF0000', '#00FF00', '#0000FF' ) ) ``` ### Example ```php Field::make( 'color', 'crb_background', 'Background' ) ->set_palette( array( '#FF0000', '#00FF00', '#0000FF' ) ); ``` ``` -------------------------------- ### Set Allowed Media Types Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/fields/media-gallery.md Configure the media gallery to accept specific file types like images and videos. Accepts a string or an array of mime types. ```php Field::make( 'media_gallery', 'crb_media_gallery', __( 'Media Gallery' ) ) ->set_type( array( 'image', 'video' ) ) ``` -------------------------------- ### Create Basic HTML Field Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/fields/html.md Use this snippet to create a simple HTML field that displays a description. The `set_html` method accepts a string containing the HTML markup. ```php Field::make( 'html', 'crb_html', __( 'Section Description' ) ) ->set_html( sprintf( '

$1

', __( 'Here, you can add some useful description for the fields below / above this text.' ) ) ) ``` -------------------------------- ### Set Frontend and Editor Stylesheet Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/containers/gutenberg-blocks.md Use `set_style()` to load a custom stylesheet for the block that applies to both the frontend and the editor. The stylesheet must be registered first. ```php wp_register_style( 'crb-my-shiny-gutenberg-block-stylesheet', get_stylesheet_directory_uri() . '/css/gutenberg/my-shiny-gutenberg-block.css' ); Block::make( __( 'My Shiny Gutenberg Block' ) ) ->add_fields( array( Field::make( 'text', 'heading', __( 'Block Heading' ) ), Field::make( 'image', 'image', __( 'Block Image' ) ), Field::make( 'rich_text', 'content', __( 'Block Content' ) ), ) ) ->set_style( 'crb-my-shiny-gutenberg-block-stylesheet' ) ->set_render_callback( function () { // .. } ); ``` -------------------------------- ### Use Callable for Dynamic Select Options Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/fields/select.md This snippet demonstrates using a callable function to fetch select options, which is recommended for performance-intensive option retrieval. ```php function my_computation_heavy_getter_function() { $results = $wpdb->get_results(); // fetching from the database, for example $results_dictionary = results_to_dictionary( $results ); // pseudocode for transforming database results to key=>value dictionary return $results_dictionary; } // ... Field::make( 'select', 'crb_select_field' ) ->add_options( 'my_computation_heavy_getter_function' ) ``` -------------------------------- ### Adding Options to Multiselect Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/fields/multiselect.md Demonstrates how to add options to a multiselect field using the `add_options` method. Options can be added multiple times and will be appended. ```APIDOC ## $multiselect_field->add_options( $options ) ### Description Add an associative array with options or a callable. The method can be called multiple times, in which case the options between the calls will be appended (instead of overwritten). ### Parameters #### Parameters - **options** (array|callable) - An associative array of options where keys are option values and values are display labels, or a callable that returns such an array. ### Example ```php Field::make( 'multiselect', 'crb_available_colors', __( 'Available Colors' ) ) ->add_options( array( 'red' => 'Red', 'green' => 'Green', 'blue' => 'Blue', ) ) ``` ``` -------------------------------- ### Customize Gravity Form Field Options Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/fields/gravity-form.md Use the `carbon_fields_gravity_form_options` filter to modify the default options for the Gravity Form field. This example changes the text for the 'No Form' option. ```php add_filter( 'carbon_fields_gravity_form_options', 'crb_my_gravity_form_options' ); function crb_my_gravity_form_options( $options ) { // change the default "No Form" text $options[0] = __( 'Do not show any form' ); return $options; } ``` -------------------------------- ### Set Block Keywords Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/containers/gutenberg-blocks.md Use `set_keywords()` to define up to three keywords that help users discover the block when searching. Keywords should be translatable. ```php Block::make( __( 'My Shiny Gutenberg Block' ) ) ->add_fields( array( Field::make( 'text', 'heading', __( 'Block Heading' ) ), Field::make( 'image', 'image', __( 'Block Image' ) ), Field::make( 'rich_text', 'content', __( 'Block Content' ) ), ) ) ->set_keywords( [ __( 'block' ), __( 'image' ), __( 'content' ) ] ) ->set_render_callback( function () { // .. } ); ``` -------------------------------- ### Register Nav Menu Item Fields Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/containers/nav-menu-item.md Use `Container::make('nav_menu_item', ...)` to create a new Nav Menu Item container and `add_fields()` to define the custom fields. ```php use Carbon_Fields\Container; use Carbon_Fields\Field; Container::make( 'nav_menu_item', __( 'Menu Settings' ) ) ->add_fields( array( Field::make( 'color', 'crb_color', __( 'Color' ) ), )); ``` -------------------------------- ### Hook into Post Meta Save Event Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/containers/post-meta.md Perform actions after post meta is saved using the `carbon_fields_post_meta_container_saved` hook. This example checks the post type and updates a timestamp meta field. ```php add_action( 'carbon_fields_post_meta_container_saved', 'crb_after_save_event' ); function crb_after_save_event( $post_id ) { if ( get_post_type( $post_id ) !== 'crb_event' ) { return false; } $event_date = carbon_get_post_meta( $post_id, 'crb_event_date' ); if ( $event_date ) { $timestamp = strtotime( $event_date ); update_post_meta( $post_id, '_crb_event_timestamp', $timestamp ); } } ``` -------------------------------- ### Define Serialized Theme Options Datastore Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/advanced-topics/serialized-datastore.md Extend the `Datastore` class to implement custom logic for saving field values as a serialized array. This class requires `load`, `save`, and `delete` methods. ```php get_base_name(); return $key; } /** * Save a single key-value pair to the database with autoload * * @param string $key * @param string $value * @param bool $autoload */ protected function save_key_value_pair_with_autoload( $key, $value, $autoload ) { $notoptions = wp_cache_get( 'notoptions', 'options' ); $notoptions[ $key ] = ''; wp_cache_set( 'notoptions', $notoptions, 'options' ); $autoload = $autoload ? 'yes' : 'no'; if ( ! add_option( $key, $value, null, $autoload ) ) { update_option( $key, $value, $autoload ); } } /** * Load the field value(s) * * @param Field $field The field to load value(s) in. * @return array */ public function load( Field $field ) { $key = $this->get_key_for_field( $field ); $value = get_option( $key, null ); return $value; } /** * Save the field value(s) * * @param Field $field The field to save. */ public function save( Field $field ) { if ( ! empty( $field->get_hierarchy() ) ) { return; // only applicable to root fields } $key = $this->get_key_for_field( $field ); $value = $field->get_full_value(); if ( is_a( $field, '\Carbon_Fields\Field\Complex_Field' ) ) { $value = $field->get_value_tree(); } $this->save_key_value_pair_with_autoload( $key, $value, $field->get_autoload() ); } /** * Delete the field value(s) * * @param Field $field The field to delete. */ public function delete( Field $field ) { if ( ! empty( $field->get_hierarchy() ) ) { return; // only applicable to root fields } $key = $this->get_key_for_field( $field ); delete_option( $key ); } } ``` -------------------------------- ### Set Default Value for a Field Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/fields/usage.md Shows how to assign a default value to a field using `set_default_value()`. ```php Field::make(...)->set_default_value( $default_value ) ``` -------------------------------- ### Retrieve Map Field Data Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/fields/map.md Get all location data for a map field as an array, including value, lat, lng, address, and zoom. This is typically used after saving the field's data. ```php /* Get the location data */ carbon_get_post_meta( $id, $name ); // array( 'value' => '40.74866,-73.97982', lat' => 40.74866, 'lng' => -73.97982, 'address' => '45 Park Avenue, New York, NY 10016', 'zoom' => 8) ``` -------------------------------- ### Complex Nested Conditions for User Role and Post Type Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/containers/conditional-display.md This example shows a nested conditional display logic: visible for administrators on any post type, OR for editors specifically on 'page' post types. ```php Container::make( 'post_meta', 'Custom Data' ) ->where( 'current_user_role', '=', 'administrator' ) ->or_where( function( $condition ) { $condition->where( 'current_user_role', '=', 'editor' ); $condition->where( 'post_type', '=', 'page' ); } ); ``` -------------------------------- ### Basic oEmbed Field Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/fields/oembed.md This snippet shows how to create a basic oEmbed field. It requires the `Field::make` function and specifies the field type as 'oembed'. ```php Field::make( 'oembed', 'crb_oembed', __( 'oEmbed' ) ) ``` -------------------------------- ### Create a Post Meta Container Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/containers/usage.md This snippet demonstrates how to create a new post meta container for pages and add various fields to it. It uses the `Container::make()` method with a `post_meta` type and a title, then specifies the target post type using `where()` and adds fields using `add_fields()`. ```php use Carbon_Fields\Container; use Carbon_Fields\Field; Container::make( 'post_meta', 'Custom Data' ) ->where( 'post_type', '=', 'page' ) ->add_fields( array( Field::make( 'map', 'crb_location' ) ->set_position( 37.423156, -122.084917, 14 ), Field::make( 'sidebar', 'crb_custom_sidebar' ), Field::make( 'image', 'crb_photo' ), )); ``` -------------------------------- ### Register Carbon Fields Theme Options (Composer) Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/plugin-quickstart.md Add this PHP code to your functions.php file to register Carbon Fields and attach theme options. This snippet includes the necessary autoloader for Composer installations. ```php use Carbon_Fields\Container; use Carbon_Fields\Field; add_action( 'carbon_fields_register_fields', 'crb_attach_theme_options' ); function crb_attach_theme_options() { Container::make( 'theme_options', __( 'Theme Options' ) ) ->add_fields( array( Field::make( 'text', 'crb_text', 'Text Field' ), ) ); } add_action( 'after_setup_theme', 'crb_load' ); function crb_load() { require_once( 'vendor/autoload.php' ); \Carbon_Fields\Carbon_Fields::boot(); } ``` -------------------------------- ### Register Carbon Fields Theme Options (Manual Zip) Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/plugin-quickstart.md Add this PHP code to your functions.php file to register Carbon Fields and attach theme options. This version is for manual zip installations and does not require Composer. ```php use Carbon_Fields\Container; use Carbon_Fields\Field; add_action( 'carbon_fields_register_fields', 'crb_attach_theme_options' ); function crb_attach_theme_options() { Container::make( 'theme_options', __( 'Theme Options' ) ) ->add_fields( array( Field::make( 'text', 'crb_text', 'Text Field' ), ) ); } ``` -------------------------------- ### Time Field Basic Usage Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/fields/time.md Demonstrates the basic creation of a Time field. ```APIDOC ## Time Field ### Description Renders a time picker field. ### Code Example ```php Field::make( 'time', 'opens_at', __( 'Opening time' ) ) ``` ``` -------------------------------- ### Define Nested Complex Fields for Slider Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/fields/complex.md Use the `complex` field type to create nested structures. This example defines a slider with multiple slides, each containing an image and a set of text fragments with positioning options. ```php Container::make( 'post_meta', 'Slider Data' ) ->where( 'post_type', '=', 'post' ) ->add_fields( array( Field::make( 'complex', 'crb_slides' ) ->add_fields( array( Field::make( 'image', 'image' ), Field::make( 'complex', 'slide_fragments' ) ->add_fields( array( Field::make( 'text', 'fragment_text' ), Field::make( 'select', 'fragment_position' ) ->add_options( array( 'Top Left', 'Top Right', 'Bottom Left', 'Bottom Right' ) ), )) )). )); ``` -------------------------------- ### Creating Tabs with Fields Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/containers/tabs.md Use `add_tab()` on a container to group fields. Each tab can contain multiple fields defined within an array. ```php use Carbon_Fields\Container; use Carbon_Fields\Field; Container::make( 'post_meta', __( 'User Settings' ) ) ->where( 'post_type', '=', 'page' ) ->add_tab( __( 'Profile' ), array( Field::make( 'text', 'crb_first_name', __( 'First Name' ) ), Field::make( 'text', 'crb_last_name', __( 'Last Name' ) ), Field::make( 'text', 'crb_position', __( 'Position' ) ), ) ) ->add_tab( __( 'Notification' ), array( Field::make( 'text', 'crb_email', __( 'Notification Email' ) ), Field::make( 'text', 'crb_phone', __( 'Phone Number' ) ), ) ); ``` -------------------------------- ### Custom Menu Walker for Nav Menu Item Data Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/containers/nav-menu-item.md Extend `Walker_Nav_Menu` to access and utilize custom meta data like colors within the menu output. This example shows how to apply a custom color to links based on `carbon_get_nav_menu_item_meta()`. ```php /** * Location: * wp-includes/nav-menu-template.php * source: Walker_Nav_Menu */ class Crb_Main_Menu_Walker extends Walker_Nav_Menu { public function start_el( &$output, $item, $depth = 0, $args = array(), $id = 0 ) { $indent = ( $depth ) ? str_repeat( "\t", $depth ) : ''; $classes = empty( $item->classes ) ? array() : (array) $item->classes; $classes[] = 'menu-item-' . $item->ID; $class_names = join( ' ', apply_filters( 'nav_menu_css_class', array_filter( $classes ), $item, $args, $depth ) ); $class_names = $class_names ? ' class="' . esc_attr( $class_names ) . '"' : ''; $id = apply_filters( 'nav_menu_item_id', 'menu-item-'. $item->ID, $item, $args, $depth ); $id = $id ? ' id="' . esc_attr( $id ) . '"' : ''; $output .= $indent . ''; $atts = array(); $atts['title'] = ! empty( $item->attr_title ) ? $item->attr_title : ''; $atts['target'] = ! empty( $item->target ) ? $item->target : ''; $atts['rel'] = ! empty( $item->xfn ) ? $item->xfn : ''; $atts['href'] = ! empty( $item->url ) ? $item->url : ''; // Adding a custom color to the links $crb_color = carbon_get_nav_menu_item_meta( $item->ID, 'crb_color' ); $atts['style'] = ! empty( $crb_color ) ? 'color: ' . $crb_color . '; ' : ''; // --- END --- "Adding a custom color to the links" $atts = apply_filters( 'nav_menu_link_attributes', $atts, $item, $args, $depth ); $attributes = ''; foreach ( $atts as $attr => $value ) { if ( ! empty( $value ) ) { $value = ( 'href' === $attr ) ? esc_url( $value ) : esc_attr( $value ); $attributes .= ' ' . $attr . '="' . $value . '"'; } } $item_output = $args->before; $item_output .= ''; $item_output .= $args->link_before . apply_filters( 'the_title', $item->title, $item->ID ) . $args->link_after; $item_output .= ''; $item_output .= $args->after; $output .= apply_filters( 'walker_nav_menu_start_el', $item_output, $item, $depth, $args ); } } // Walker_Nav_Menu ``` -------------------------------- ### Conditional Logic Dependent on Parent Fields Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/fields/conditional-logic.md This example demonstrates how to make a 'Price' text field within a nested 'complex' field visible only if a parent 'checkbox' field ('In Production') is checked. It uses `parent.parent.` to reference a field two levels up. ```php Field::make( 'checkbox', 'crb_in_production', 'In Production' ), Field::make( 'complex', 'crb_makes', 'Makes' ) ->add_fields( array( Field::make( 'complex', 'models', 'Models' ) ->add_fields( array( Field::make( 'text', 'name', 'Name' ), Field::make( 'text', 'price', 'Price' ) ->set_conditional_logic( array( array( 'field' => 'parent.parent.crb_in_production', 'value' => true, ) ) ) ) ) ) ) ``` -------------------------------- ### Set Block Description Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/containers/gutenberg-blocks.md Use `set_description()` to add a short text describing the block, which appears in the Block inspector sidebar. ```php Block::make( __( 'My Shiny Gutenberg Block' ) ) ->add_fields( array( Field::make( 'text', 'heading', __( 'Block Heading' ) ), Field::make( 'image', 'image', __( 'Block Image' ) ), Field::make( 'rich_text', 'content', __( 'Block Content' ) ), ) ) ->set_description( __( 'A simple block consisting of a heading, an image and a text content.' ) ) ->set_render_callback( function () { // .. } ); ``` -------------------------------- ### Add Help Text to a Field Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/fields/usage.md Demonstrates adding help text to a field using `set_help_text( $text )`. ```php Field::make(...)->set_help_text( $text ) ``` -------------------------------- ### Create a Network Container Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/containers/network.md Use this snippet to define a new network container with fields. This container will only be visible in the network admin area. ```php use Carbon_Fields\Container; use Carbon_Fields\Field; Container::make( 'network', 'crb_network_container', 'Network Settings' ) ->add_fields( array( Field::make( 'text', 'crb_title' ) , Field::make( 'checkbox', 'crb_disable_feature' ) ) ); ``` -------------------------------- ### Date Time Field Initialization Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/fields/date-time.md This snippet shows the basic initialization of a Date Time field. ```APIDOC ## Date Time Field Renders a time and date picker field. ### Code Example ```php Field::make( 'date_time', 'eta', __( 'Estimated time of arrival' ) ) ``` ``` -------------------------------- ### Basic Date Field Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/fields/date.md Renders a basic date picker field. ```php Field::make( 'date', 'crb_event_start_date', __( 'Event Start Date' ) ) ``` -------------------------------- ### Mark Field as Required Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/fields/usage.md Illustrates how to mark a field as required using `set_required( true )`. ```php Field::make(...)->set_required( true ) ``` -------------------------------- ### Setting Picker Options Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/fields/date-time.md Customize the appearance and behavior of the date and time picker using Flatpickr options. ```APIDOC ## `set_picker_options( $options )` Set an associative array with your preferred [options](https://chmln.github.io/flatpickr/options/). ``` -------------------------------- ### Create a Term Meta Container Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/containers/term-meta.md Defines a new term meta container for categories, adding color and image fields. Ensure Carbon Fields and its dependencies are loaded. ```php use Carbon_Fields\Container; use Carbon_Fields\Field; Container::make( 'term_meta', __( 'Category Properties' ) ) ->where( 'term_taxonomy', '=', 'category' ) ->add_fields( array( Field::make( 'color', 'crb_title_color', __( 'Title Color' ) ), Field::make( 'image', 'crb_thumb', __( 'Thumbnail' ) ), ) ); ``` -------------------------------- ### Create a Map Field Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/fields/map.md This snippet shows how to create a basic map field in Carbon Fields. ```php Field::make( 'map', 'crb_map', __( 'Map' ) ) ``` -------------------------------- ### Configure Composer Autoloading Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/extending/field-in-a-theme.md Add this to your theme's composer.json to ensure your custom fields are autoloaded. Adjust the namespace and path to match your field's directory. ```json "autoload": { "files": [ "./includes/my-field/field.php" ], "psr-4": { "Carbon_Field_YOURFIELDNAME\": "./includes/my-field/core/" } } ``` -------------------------------- ### Configure Widget Control Options Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/containers/widgets.md Set custom control options for your widget, such as width, by defining the `$form_options` property within your widget class. ```php protected $form_options = array( 'width' => 500 ); ``` -------------------------------- ### Basic Date Time Field Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/fields/date-time.md Renders a basic date and time picker field with a label. ```php Field::make( 'date_time', 'eta', __( 'Estimated time of arrival' ) ) ``` -------------------------------- ### Define Theme Options Container and Rich Text Field Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/guide/using-field-values.md Define a theme options container and add a rich text field for copyright information. This code should be placed at the top of your `functions.php` file. ```php use Carbon_Fields\Field; use Carbon_Fields\Container; add_action( 'carbon_fields_register_fields', 'crb_attach_theme_options' ); function crb_attach_theme_options() { Container::make( 'theme_options', __( 'Theme Options' ) ) ->add_fields( array( Field::make( 'rich_text', 'crb_footer_copyright', 'Copyright' ), ) ); }a ``` -------------------------------- ### Add Options to a Select Field Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/fields/select.md This snippet shows how to add options to a select field using the `add_options` method. ```php Field::make( 'select', 'crb_content_align', __( 'Text alignment' ) ) ->add_options( array( 'left' => __( 'Left' ), 'center' => __( 'Center' ), 'right' => __( 'Right' ), ) ) ``` -------------------------------- ### Basic Media Gallery Field Source: https://github.com/htmlburger/carbon-fields-docs/blob/3.x/src/learn/fields/media-gallery.md This is the basic structure for creating a media gallery field. ```php Field::make( 'media_gallery', 'crb_media_gallery', __( 'Media Gallery' ) ) ```