ACF Composer

Field partials are reusable field groups that can be injected into other field groups.

1. Generate a partial: wp acorn acf:partial {Name}. This creates a class extending Partial in src/Fields/Partials/.
2. Implementation: Unlike standard fields, a Partial class should not call ->build() in its fields() method; it should return the FieldsBuilder instance itself.
3. Usage: In a parent Field class, use the ->addPartial() method and pass the partial's class constant.

// In a Field class
public function fields()
{
    $fields = Builder::make('example');

    $fields
        ->addPartial(ListItems::class);

    return $fields->build();
}

Install ACF Composer via Composer to use it within your Sage theme.

Requirements:

• Sage >= 10.0
• Acorn >= 3.0
• ACF Pro >= 5.8.0

$ composer require log1x/acf-composer

Generate an ACF Options page using wp acorn acf:options {Name}. This creates a class in src/Options/ extending Options (aliased as Field in the stub).

All fields defined in the generated class will have their location automatically set to this options page. Use the --full flag to generate a stub with more configuration examples.

$ wp acorn acf:options ExampleOptions
# Or with full configuration examples
$ wp acorn acf:options Options --full

You can customize the stubs generated by ACF Composer by publishing the stubs directory using Acorn. Running the publish command generates all available stubs by default.

Note that stub files are optional: if a specific stub file is missing from the stubs/acf-composer directory, ACF Composer will fall back to the default stub provided by the package.

wp acorn acf:stubs

Generate a block class using wp acorn acf:block {Name}. This creates a class in src/Blocks/ extending Block and a corresponding Blade view in resources/views/blocks/.

Key Features:

• Data passing: Use the with() method to pass data to the Blade view.
• Localization: Use the --localize flag during generation to prepare name and description for translation.
• Block Preview: To create a custom preview for the editor, create a Blade file in the same directory prefixed with preview- (e.g., preview-example.blade.php).

$ wp acorn acf:block ExampleBlock
# Or with localization
$ wp acorn acf:block Example --localize

Generate a sidebar widget using wp acorn acf:widget {Name}. This creates a class in src/Widgets/ extending Widget and a Blade view in resources/views/widgets/.

Widgets are automatically registered with WP_Widget and rendered using Blade. To access field data, use get_field('field_name', $this->widget->id) within your class methods.

$ wp acorn acf:widget ExampleWidget

Use the acf:field command to generate a new field group class. This creates a file in src/Fields/{Name}.php extending the Field class.

Inside the generated class, you define your fields within the fields() method using the Builder class. You must call ->build() at the end of your builder chain to return the array.

$ wp acorn acf:field ExampleField

After installation, publish the config/acf.php configuration file using the Acorn CLI to customize global settings like default field types.

$ wp acorn vendor:publish --tag="acf-composer"

To improve performance, you can cache registered blocks to block.json files and field groups to a JSON manifest. This is recommended during deployment.

• Cache: wp acorn acf:cache (use --status to check current status).
• Clear Cache: wp acorn acf:clear.

Note: Changes to blocks or fields will not appear until the cache is cleared or re-cached.

$ wp acorn acf:cache [--status]
$ wp acorn acf:clear

ACF Composer allows you to define global defaults for specific field types in your config/acf.php file. This prevents the need to repeatedly define the same settings (like 'ui' => 1) for every field instance. Any global default can be overridden by explicitly setting a different value on an individual field.

Example configuration in config/acf.php:

'defaults' => [
    'trueFalse' => ['ui' => 1],
    'select' => ['ui' => 1],
],

AcfComposer follows a lifecycle that ensures all components are correctly instantiated and hooked into WordPress/ACF:

1. Registration: Classes are added via register(). The system distinguishes between standard Composer classes, Widget classes (handled as legacy widgets), and Partial classes (which are excluded from standard composer registration).
2. Booting: When boot() is called, the package:
   • Registers the default application path.
   • Handles Block and Widget registration.
   • Hooks into acf/init to process all registered composers.
3. Composer Processing: During the acf/init hook, composers are processed. If a composer extends Options, it may be deferred if it has a parent defined. The system also validates that every field group has a unique key to prevent DuplicateKeyException.

When running acf:block, you will be prompted to provide the following configuration via interactive prompts:

1. Block Description: Enter a text description for the block.
2. Block Category: Select a category from the available WordPress block categories.
3. Supported Post Types: Select one or more public post types that the block should support. Leave empty to support all post types.
4. Block Features (Supports): Select which block features to enable. Available options include:
   • align
   • align_text
   • align_content
   • full_height
   • anchor
   • mode
   • multiple
   • jsx
   • color (options: background, text, gradients)
   • spacing (options: padding, margin)