moxie-leean / wp-widgets
Control the WP widgets whilst using WP in as a headless CMS.
Requires
- php: >=5.4
- moxie-leean/wp-acf: 0.*.*
Requires (Dev)
README
Control the WP widgets whilst using WP in as a headless CMS. Now widgets will output JSON data via an API rather than
Getting Started
The easiest way to install this package is by using composer from your terminal:
composer require moxie-leean/wp-widgets
Or by adding the following lines on your composer.json file
"require": {
"moxie-leean/wp-widgets": "dev-master"
}
This will download the files from the packagist site and set you up with the latest version located on master branch of the repository.
After that you can include the autoload.php file in order to
be able to autoload the class during the object creation.
include '/vendor/autoload.php';
Usage
You first need to register the widgets you want to use using the `Register::init()` function. This function takes the following parameter:
[
'leean' => [],
'custom' => [],
]
Where 'leean' is the list of pre-defined widgets you want to use, and 'custom' is a list of any custom widgets you want to add for this project. For example:
\Leean\Widgets\Register::init([
'leean' => [
'LeeanPreview',
'LeeanMenu,
],
'custom' => [
'MyProject\Widgets\MyCustomWidget'
],
]);
Note that Leean widgets can be registered with their short class name, whereas custom widgets need a fully qualified namespace.
All custom widget objects must extend the `\Leean\Widgets\Models\AbstractWidget` class. See below.
You can register widget areas using the usual WordPress function:
register_sidebar( array(
'id' => 'my-sidebar',
'name' => 'Name',
'description' => 'My new sidebar',
) );
Creating Custom Widgets
All custom widgets must extend the `\Leean\Widgets\Models\AbstractWidgetclass. The simplest widget you can create just needs to implement the__construct()` function, eg:
use Leean\Widgets\Models\AbstractWidget;
class MyWidget extends AbstractWidget
{
public function __construct() {
parent::__construct( 'My Widget', 'Displays something really cool.' );
}
}
By default it will use the widget's class name as the widget slug, converting it into dash format (e.g. MyWidget becomes my-widget). If you want to override the slug you can pass it as a third argument into the `parent::__construct()` function.
In addition there are a couple of other functions which you may want to use:
Post Registration
The post registration function runs just after the widget is registered. You can use this to register ACF fields, e.g.:
public static function post_registration() {
if ( function_exists( 'acf_add_local_field_group' ) ) :
acf_add_local_field_group( array(
...
}
#### Get Data
This function returns the widget's data for use in an API. By default it will return the widget's title and all ACF fields. You can override it like this:
public function get_data() {
$data = parent::get_data();
return array_merge( ['more_data' => 'something'], $data );
}
#### Widget
By default the widget will output an error message if you try to use it in a normal WordPress theme. If, however, you want to allow it to be used as a normal widget too, you can override the ```widget```function:
public function widget( $args, $instance ) {
?>
<h3><?php echo esc_html( $instance['title'] ? $instance['title'] : '' ) ?></h3>
<?php
}