v1.2.0

BREAKING(blocks): `generate()` has been deprecated. Block options are now set using class variables.
refactor(composer): Most functionality has been moved to a separate parent class.
feat(widgets): Added ACF sidebar widget functionality. Batteries included.
feat(options): Added the ability to easily create option pages.
feat(console): Added commands / stubs for `acf:widget` and `acf:options`
chore(console): Clean up existing stubs.
chore(docs): Write actual documentation.
chore(composer): Add suggestion for `log1x/modern-acf-options`

.editorconfig

@@ -14,5 +14,11 @@ trim_trailing_whitespace = false
 [*.php]
 indent_size = 4
 
+[src/Console/stubs/*.stub]
+indent_size = 4
+
+[src/Console/stubs/views/*.stub]
+indent_size = 2
+
 [*.blade.php]
 indent_size = 2

LICENSE.md

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2019 Brandon Nifong
+Copyright (c) 2020 Brandon Nifong
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -4,34 +4,129 @@
 ![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 and Blocks using [ACF Builder](https://github.com/stoutlogic/acf-builder) alongside [Sage 10](https://github.com/roots/sage).
+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).
 
 ## Requirements
 
 - [Sage](https://github.com/roots/sage) >= 10.0
 - [ACF](https://www.advancedcustomfields.com/) >= 5.8.0
+- [PHP](https://secure.php.net/manual/en/install.php) >= 7.2
+- [Composer](https://getcomposer.org/download/)
 
 ## Installation
 
+Install via Composer:
+
 ```bash
 $ composer require log1x/acf-composer
 ```
 
 ## Usage
 
-### Publish Config
+### Basic Usage
+
+Start by publishing the `config/acf.php` configuration file using Acorn:
 
 ```bash
 $ wp acorn vendor:publish --provider="Log1x\AcfComposer\Providers\AcfComposerServiceProvider"
 ```
 
-Initialize fields, blocks, and default field type values in `config/acf.php`.
+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.
+
+To create your first field, start by running the following command from your theme directory:
+
+```bash
+$ 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).
+
+### Generating a Block
+
+Generating a Block is generally the same as generating a field as seen above.
+
+Start by creating the Block field using Acorn:
+
+```bash
+$ wp acorn acf:block Example
+```
+
+Optionally, you may pass `--full` to the command above to generate a stub that contains additional configuration examples.
+
+```bash
+$ wp acorn acf:block Example --full
+```
+
+Once finished, similarily to Fields, simply add the new block, `App\Blocks\Example::class` to `config/acf.php`.
 
-### Create a Block or Field
+When running the ACF 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.
+
+### Generating a Widget
+
+Creating a sidebar widget using ACF Composer is extremely easy. Widgets are automatically loaded and rendered with Blade. Batteries included.
+
+Start by creating a Widget using Acorn:
 
 ```bash
-$ wp acorn acf:block MyBlock
-$ wp acorn acf:field MyField
+$ 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`.
+
+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.
+
+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`
+
+### Field Defaults
+
+One of my personal favorite features of ACF Composer is thet ability to set field defaults.
+
+Taking a look at `config/acf.php`, you will see a few pre-configured defaults:
+
+```php
+'defaults' => [
+    'trueFalse' => ['ui' => 1],
+    'select' => ['ui' => 1],
+],
+```
+
+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:
+
+```php
+'defaults' => [
+    'fieldGroup' => ['instruction_placement' => 'acfe_instructions_tooltip'],
+    'repeater' => ['layout' => 'block', 'acfe_repeater_stylised_button' => 1],
+    'postObject' => ['ui' => 1, 'return_format' => 'object'],
+    'accordion' => ['multi_expand' => 1],
+    'group' => ['layout' => 'table', 'acfe_group_modal' => 1],
+    'tab' => ['placement' => 'left'],
+],
 ```
 
 ## Bug Reports

composer.json

@@ -1,7 +1,7 @@
 {
   "name": "log1x/acf-composer",
   "type": "package",
-  "description": "ACF Composer assists you with creating Fields and Blocks with ACF Builder and Roots Sage",
+  "description": "Create fields, blocks, and more using ACF Builder and Roots Sage",
   "license": "MIT",
   "authors": [
     {
@@ -22,7 +22,8 @@
   },
   "suggest": {
     "stoutlogic/acf-builder": "Provides an essential fluid interface for creating ACF fields.",
-    "log1x/sage-directives": "Provides Sage-specific Blade directives for use with WordPress and ACF within your views."
+    "log1x/sage-directives": "Provides Sage-specific Blade directives for use with WordPress and ACF within your views.",
+    "log1x/modern-acf-options": "Gives ACF option pages a much needed design overhaul."
   },
   "extra": {
     "acorn": {

config/acf.php

@@ -30,6 +30,20 @@
         // 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