ibelar / atk-wordpress

Wordpress plugin development using Agile Toolkit Framework (atk). Wordpress site demo available on www.atkwp.com
8 stars 7 forks source link
dashboard-widget widget wordpress wordpress-development wordpress-plugin

Read Me

What is it?

Atk-wordpress help build plugins for Wordpress. With this package, plugins UI elements are created using the Agile Toolkit Framework for php.

This package make it easy to implement each of Wordpress components like:

Then each component UI element, like Form, Lister, CRUD, Icon, Button, Table and more are easily add to the component, thanks to the Agile Toolkit framework for php.

Creating a Wordpress component is as simple as:

This package will take care of properly wiring the necessary Wordpress hook and action for the component to run.

Furthermore, components define will work under ajax, whether in admin or front section of Wordpress, right out-of-the-box.

Require

This package require composer in order to install all it's dependencies.

Getting started

Using the starter project

Although you can start from scratch, the easiest way would be to start using the atk-wordpress-starter.

The starter project comes with empty configuration files for each components, except one, an admin panel that display a simple message.

Note: if the starter project is use as is, it will create a new plugin name atk-wordpress-starter. Once activated, a new admin panel will be accessible via "Hello Atkwp" menu item in Wordpress admin section.

From scratch

Minimal files and folders structure are required for creating a pluging using this package. These files and folders should be located directly under the plugins folder being built.

Composer.json

The composer configuration file must require this package and autoload should match the plugin namespace.

  "require": {
    "ibelar/atk-wordpress": "^1.0"
  },
  "autoload": {
      "psr-4": {
        "atkstarter\\" : "src/"
      }
  }

plugin.php file

This is the plugin entry point in Wordpress as any other Wordpress plugin is required to have. It should contains your plugin name and description. The plugin.php file is also responsible of creating and instantiating the Plugin.php class. It will also call the Plugin::booth() method. The booth() method will load all components define in configuration file and properly hook up their Wordpress actions.

This is how it will normally look:

<?php
/*
Plugin Name: My Plugin name
Description: My plugin description.
Version: 1.0
*/

namespace my_plugin_namespace;

use atkwp\controllers\ComponentController;
use atkwp\helpers\Pathfinder;

require 'vendor/autoload.php';

if (array_search(ABSPATH . 'wp-admin/includes/plugin.php', get_included_files()) === false) {
    require_once ABSPATH . 'wp-admin/includes/plugin.php';
}

$atk_plugin_name = "myPluginName";
$atk_plugin = __NAMESPACE__."\\Plugin";

$$atk_plugin_name = new  $atk_plugin($atk_plugin_name, new Pathfinder(plugin_dir_path(__FILE__)), new ComponentController());

if (!is_null( $$atk_plugin_name)) {
    $$atk_plugin_name->boot(__FILE__);
}

Plugin.php class

The main plugin file. The Plugin class must extends the AtkWp class and implement the PluginInterface.

Minimally, it should look like this:

<?php
/**
 * The Plugin implementation.
 */

namespace my_plugin_namespace;

use atkwp\interfaces\PluginInterface;
use atkwp\AtkWp;

class Plugin extends AtkWp implements PluginInterface
{
    public function init()
    {
        // Uncommented this for database connectivity.
        //$this->setDbConnection();
    }

    public function activatePlugin()
    {
        // TODO: Implement activatePlugin() method.
    }

    public function deactivatePlugin()
    {
        // TODO: Implement deactivatePlugin() method.
    }
}

configuratons folder

This is the place where configuration files should be located. There is one configuration file for each possible component in Wordpress and one for default configuration value a plugin might needed.

Generally speaking, a component configuration required the uses of a php class implementing the component detail. The component class must extends the proper component's type class, for example a panel component class would extends the PanelComponent type class. Each component's type class, except for WidgetComponent, is an Agile Toolkit View, that will automatically output itself when need by Wordpress. Therefore, you can use a component class as you would use a regular Agile Toolkit View class. (atk4\ui)

_Note on WidgetComponent: The WidgetComponent type class is the only one not deriving from a regular atk4\ui\View class. The reason is that a Widget class in Wordpress must extends \Wp_Widget. However, when running \Wp_Widget::widget() or \WpWidget::form() method, an atk4\ui/View object is passed as an argument in order to be able to add atk UI element to the widget.

assets folder

The assest's a plugin need. It usually contains:

Sample plugin

Beside the plugin starter project, there is a more complete plugin sample (atk-wordpress-sample) available that use most of Wordpress components.

License

Copyright (c) 2017 Alain Belair. MIT Licensed,

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Agile Toolkit

To know more about the Agile Toolkit Framework