Skip to content

Commit

Permalink
v1.2.1
Browse files Browse the repository at this point in the history 
feat(autoload): Fields, blocks, and widgets classes are now autoloaded and no longer need added to the config.
refactor(options): Refactor options page implementation into its own class with more obvious documented properties.
enhance(stubs): Use camelCase for keys on generated stubs
fix(block): Change properties to public
fix(widget): Change properties to public
chore(docs): Improve documentation
chore(docblocks): Improve docblocks
  • Loading branch information
@Log1x
Log1x authored Mar 13, 2020
1 parent 4218fdb commit aa40d9e
Show file tree
Hide file tree
Showing 16 changed files with 342 additions and 255 deletions.
72 changes: 49 additions & 23 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,16 @@
![CircleCI](https://img.shields.io/circleci/build/gh/Log1x/acf-composer.svg?style=flat-square)
![Packagist](https://img.shields.io/packagist/dt/log1x/acf-composer.svg?style=flat-square)

ACF Composer assists you with ~~creating~~ **composing** Fields, Blocks, Widgets, and Options pages using [ACF Builder](https://github.com/stoutlogic/acf-builder) alongside [Sage 10](https://github.com/roots/sage).
ACF Composer is the ultimate tool for creating fields, blocks, widgets, and option pages using ACF, [ACF Builder](https://github.com/stoutlogic/acf-builder) alongside [Sage 10](https://github.com/roots/sage).

## Features

- Encourages clean structuring for creating fields with Sage 10 and ACF.
- Instantly generate working fields, blocks, widgets, and option pages. Batteries included.
- Blocks and widgets are fully rendered using Blade with a native Sage 10 feel for passing view data.
- 🔥 Automatically hooks widgets with `WP_Widget` making them instantly ready to use.
- 🔥 Automatically sets field location on blocks, widgets, and option pages.
- 🔥 Globally set default field type and field group settings. No more repeating `['ui' => 1]` on every select field.

## Requirements

Expand All @@ -23,16 +32,14 @@ $ composer require log1x/acf-composer

## Usage

### Basic Usage
### Getting Started

Start by publishing the `config/acf.php` configuration file using Acorn:

```bash
$ wp acorn vendor:publish --provider="Log1x\AcfComposer\Providers\AcfComposerServiceProvider"
```

Looking at the config file, you will see documented keys for configuration. When creating a field group, simply add each class to their respective type.

### Generating a Field

Generating fields with ACF Composer is done using Acorn.
Expand All @@ -45,17 +52,15 @@ $ wp acorn acf:field Example

This will create `src/Fields/Example.php` which is where you will create and manage your field group.

Once finished, follow up by uncommenting `App\Fields\Example::class` in `acf.php`.

Taking a glance at the generated `Example.php` stub, you will notice that it has a simple list configured.

Proceed by checking the `Add Post` for the field to ensure things are working as intended– and then [get to work](https://github.com/Log1x/acf-builder-cheatsheet).
Proceed by checking the `Add Post` for the field to ensure things are working as intended – and then [get to work](https://github.com/Log1x/acf-builder-cheatsheet).

### Generating a Block

Generating a Block is generally the same as generating a field as seen above.
Generating a block is generally the same as generating a field as seen above.

Start by creating the Block field using Acorn:
Start by creating the block field using Acorn:

```bash
$ wp acorn acf:block Example
Expand All @@ -67,43 +72,49 @@ Optionally, you may pass `--full` to the command above to generate a stub that c
$ wp acorn acf:block Example --full
```

Once finished, similarily to Fields, simply add the new block, `App\Blocks\Example::class` to `config/acf.php`.

When running the ACF Block generator, one difference to a generic field is an accompanied View is generated in the `resources/views/blocks` directory.
When running the block generator, one difference to a generic field is an accompanied `View` is generated in the `resources/views/blocks` directory.

Like the Field generator, the example block contains a simple list repeater and is working out of the box.
Like the field generator, the example block contains a simple list repeater and is working out of the box.

### Generating a Widget

Creating a sidebar widget using ACF Composer is extremely easy. Widgets are automatically loaded and rendered with Blade. Batteries included.
Creating a sidebar widget using ACF Composer is extremely easy. Widgets are automatically loaded and rendered with Blade, as well as registered with `WP_Widget` which is usually rather annoying.

Start by creating a Widget using Acorn:
Start by creating a widget using Acorn:

```bash
$ wp acorn acf:widget Example
```

Once finished, simply add `App\Widgets\Example::class` to the `widgets` key in `config/acf.php`

Similar to Blocks, Widgets are also accompanied by a view generated in `resources/views/widgets`.
Similar to blocks, widgets are also accompanied by a view generated in `resources/views/widgets`.

Out of the box, the Example widget is ready to go and should appear in the backend.

### Generating an Options Page

When creating a field, you have the option of populating the `$options` variable automatically generating an Options page as well as setting the field group location.
Creating an options page is similar to creating a regular field group in additional to a few configuration options available to customize the page (most of which, are optional.)

Start by creating an option page using Acorn:

```bash
$ wp acorn acf:options Options
```

Outside of the `$options` variable being set in the options stub, it is effectively a Field. That being said, `App\Fields\Options::class` should be registered in the `fields` array in `config/acf.php`
Optionally, you may pass `--full` to the command above to generate a stub that contains additional configuration examples.

```bash
$ wp acorn acf:options Options --full
```

### Field Defaults
Once finished, you should see an Options page appear in the backend.

One of my personal favorite features of ACF Composer is thet ability to set field defaults.
All fields registered will have their location automatically set to this page.

## Default Field Settings

One of my personal favorite features of ACF Composer is the ability to set field type as well as field group defaults. Any globally set default can of course be over-ridden by simply setting it on the individual field.

### Global

Taking a look at `config/acf.php`, you will see a few pre-configured defaults:

Expand All @@ -116,7 +127,22 @@ Taking a look at `config/acf.php`, you will see a few pre-configured defaults:

When setting `trueFalse` and `select` to have their `ui` set to `1` by default, it is no longer necessary to repeatedly set `'ui' => 1` on your fields. This takes effect globally and can be overridden by simply setting a different value on a field.

Here are a few others that I personally use:
### Field Group

It is also possible to define defaults on individual field groups. This is done by simply defining `$defaults` in your field class.

```php
/**
* Default field type settings.
*
* @return array
*/
protected $defaults = ['ui' => 0];
```

### My Defaults

Here are a couple defaults I personally use. Any prefixed with `acfe_` are related to [ACF Extended](https://www.acf-extended.com/).

```php
'defaults' => [
Expand Down
46 changes: 2 additions & 44 deletions config/acf.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,48 +2,6 @@

return [

/*
|--------------------------------------------------------------------------
| Standard Fields
|--------------------------------------------------------------------------
|
| The fields listed here will be automatically loaded on the
| request to your application.
|
*/

'fields' => [
// App\Fields\Example::class,
],

/*
|--------------------------------------------------------------------------
| Gutenberg Blocks
|--------------------------------------------------------------------------
|
| The Gutenberg blocks listed here will be automatically loaded on the
| request to your application.
|
*/

'blocks' => [
// App\Blocks\Example::class,
],

/*
|--------------------------------------------------------------------------
| Sidebar Widgets
|--------------------------------------------------------------------------
|
| The widgets listed here will be automatically loaded on the
| request to your application.
|
*/

'widgets' => [
// App\Widgets\Example::class,
],

/*
|--------------------------------------------------------------------------
| Default Field Type Settings
Expand All @@ -53,8 +11,8 @@
| is then merged with your field groups when they are composed.
|
| This allows you to avoid the repetitive process of setting common field
| configuration such as `ui` on every `trueFalse` field or
| `instruction_placement` on every `fieldGroup`.
| configuration such as `ui` on every `trueFalse` field or your
| preferred `instruction_placement` on every `fieldGroup`.
|
*/

Expand Down
68 changes: 36 additions & 32 deletions src/Block.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,8 @@

namespace Log1x\AcfComposer;

use Illuminate\Support\Str;
use Illuminate\Support\Arr;
use Illuminate\Support\Str;

abstract class Block extends Composer
{
Expand All @@ -12,112 +12,112 @@ abstract class Block extends Composer
*
* @var array
*/
protected $block;
public $block;

/**
* The block content.
*
* @var string
*/
protected $content;
public $content;

/**
* The block preview status.
*
* @var bool
*/
protected $preview;
public $preview;

/**
* The current post ID.
*
* @param int
*/
protected $post;
public $post;

/**
* The block prefix.
*
* @var string
*/
protected $prefix = 'acf/';
public $prefix = 'acf/';

/**
* The block namespace.
*
* @var string
*/
protected $namespace;
public $namespace;

/**
* The display name of the block.
*
* @var string
*/
protected $name = '';
public $name = '';

/**
* The slug of the block.
*
* @var string
*/
protected $slug = '';
public $slug = '';

/**
* The description of the block.
*
* @var string
*/
protected $description = '';
public $description = '';

/**
* The category this block belongs to.
*
* @var string
*/
protected $category = '';
public $category = '';

/**
* The icon of this block.
*
* @var string|array
*/
protected $icon = '';
public $icon = '';

/**
* An array of keywords the block will be found under.
*
* @var array
*/
protected $keywords = [];
public $keywords = [];

/**
* An array of post types the block will be available to.
*
* @var array
*/
protected $post_types = ['post', 'page'];
public $post_types = ['post', 'page'];

/**
* The default display mode of the block that is shown to the user.
*
* @var string
*/
protected $mode = 'preview';
public $mode = 'preview';

/**
* The block alignment class.
*
* @var string
*/
protected $align = '';
public $align = '';

/**
* Features supported by the block.
*
* @var array
*/
protected $supports = [];
public $supports = [];

/**
* Compose and register the defined field groups with ACF.
Expand All @@ -131,11 +131,30 @@ public function compose($callback = null)
return;
}

if (! empty($this->name) && empty($this->slug)) {
$this->slug = Str::slug($this->name);
}

if (empty($this->namespace)) {
$this->namespace = Str::start($this->slug, $this->prefix);
}

parent::compose(function () {
acf_register_block([
'name' => $this->slug,
'title' => $this->name,
'description' => $this->description,
'category' => $this->category,
'icon' => $this->icon,
'keywords' => $this->keywords,
'post_types' => $this->post_types,
'mode' => $this->mode,
'align' => $this->align,
'supports' => $this->supports,
'enqueue_assets' => [$this,'assets'],
'render_callback' => [$this, 'render']
]);

if (! Arr::has($this->fields, 'location.0.0')) {
Arr::set($this->fields, 'location.0.0', [
'param' => 'block',
Expand All @@ -144,21 +163,6 @@ public function compose($callback = null)
]);
}
});

acf_register_block([
'name' => $this->slug,
'title' => $this->name,
'description' => $this->description,
'category' => $this->category,
'icon' => $this->icon,
'keywords' => $this->keywords,
'post_types' => $this->post_types,
'mode' => $this->mode,
'align' => $this->align,
'supports' => $this->supports,
'enqueue_assets' => [$this,'assets'],
'render_callback' => [$this, 'render']
]);
}

/**
Expand Down
Loading

0 comments on commit aa40d9e

Please sign in to comment.