logo-antonella-framework-blancologo-antonella-framework-blanco
  • Documentación
  • Soporte
  • Repositorio
  • Videotutoriales
  • Idioma: Español
    • Español Español
    • English English
logo-antonella-framework-blanco
logo-antonella-framework-blanco
Ver. 1.0 | Ver 1.1  | Ver. 1.2 | Ver. 1.5 | Ver 1.6 | Ver. 1.7
Prólogo
Primeros Pasos
Configuración
Lo Básico
Dos vías de trabajo
Consola
Packages
Blade

Prólogo

Notas de la Versión

Antonella Framework ha sido creado para poder hacer plugin en equipo o individual de forma limpia y ordenada. Usando el sistema de clases, con estructura PSR-4 hace que podamos preocuparnos por el funcionamiento del plugin y realizar la continuación de la misma con una curva de aprendizaje corta.

Versión 1.5

¡Damos la Bienvenida a Blade!. El editor de plantillas usado en Laravel se une como módulo para Antonella Framework.

Nuevos comandos para Antonella Console.

Creación de nuevas carpetas para las vistas y la caché

Automatización del namespace al momento de la instalación

La instalación de Antonella cambia de clonar al repositorio a usar este comando

composer create-project --prefer-dist cehojac/antonella-framework-for-wp:dev-master my-awesome-plugin

Sistema de ayuda en Antonella console.

php antonella help

Nuevo canal de Youtube para enseñar el funcionamiento del Framework 

Versión 1.2

Creación de Widgets con la consola antonella a través del comando php antonella widget

Ajustes de mejora de rendimiento en el sistema

Versión 1.1

Mejora en la creación de Post Types (desde la sección de config).

Correcciones de algunas funciones en la creación de post Types hederadas de la versión 1.0

Versión 1.0

Sale la versión el cual se espera un feedback por parte de los usuarios. 

Se agrega el sistema PSR-4.

Se agrega la primera versión del archivo Config.php con las variables necesarias para un plugin

Es posible incluir paquetes de terceros agregándolo en el archivo composer.json

Se agrega clases definidas para el control de POST y GET

Clases para la creación de post-type de forma fácil

Agregado para insertar contenido en el escritorio de administración de WordPress

Agregado control de usuarios con Clase User

Agregado Control de instalación y desinstalación del plugin de forma fácil

 

Se invita a los programadores a mejorar este plugin y poder crear comunidad a base de ello.

Primeros Pasos

Instalación

Requerimientos Mínimos

Antonella Framework necesita los siguientes elementos

GIT

Composer

PHP 5.6 o superior

En el Caso de Linux tienes que instalar el complemento PHP-ZIP

Instalación de Antonella Framework

Puedes instalarlo desde git (Debes instalarlo en una carpeta vacía)

 composer create-project --prefer-dist cehojac/antonella-framework-for-wp:dev-master tu-nombre-de-plugin 

colocando donde dice «tu-nombre-de-plugin» por el nombre del plugin que vas a crear.

Luego

 cd tu-nombre-de-plugin

Estructura

El sistema de carpetas se mostrará de la siguiente manera:

Los archivos del Framework se encuentran en la Carpeta SRC.

Los archivos de la vista Blade se encuentran en resources -> views-> template

 

El Namespace

Al momento de instalar el proyecto Antonnella creara un «namespace» aleatorio. Puedes cambiarlo en la consola

php antonella namespace TUNAMESPACE

donde en el lugar «TUNAMESPACE» debes colocar el nuevo nombre para el namespace

Si deseas generar otro namespace aleatorio solo debes poner en la consola

php antonella namespace

y automáticamente generará otro

Para llamar a las funciones dentro de los archivos controladores puedes hacerlo de la siguiente manera

$tu_variable= __NAMESPACE__.\TuClase::TuFuncion;

Esta función puede ser reutilizado por otros plugins o addons.

Configuración

Configuración

Para asignar el nombre del plugin sólo será nesesario modificar el archivo antonella-framework.php en la seccion Plugin name.

El archivo config.php contienen un sistema de arrays para configurar tu plugin de una manera fácil.

Variable Options

Esta variable permite introducir las variables que deseas insertar en wordpress

Ejemplo:

/*
* Plugins option
* storage in database the option value
* Array ('option_name'=>'default value')
* @example ["example_data" => 'foo',] * @return void
*/
public $plugin_options=[
"version"=>"1.0",
"valor1" => "algun valor",
];

Variable language_name

Puedes indicar una única palabra para indicar la traducción. por defecto es «antonella» pero puedes cambiarla

/**
* Language Option
* define a unique word for translate call
*/
public $language_name='antonella';

Variable plugin_prefix

indica una única palabra para identificar el plugin. por defecto es «ch_nella» pero puedes cambiarse.

/**
* Plugin text prefix
* define a unique word for this plugin
*/
public $plugin_prefix='ch_nella';

Variable data_post

Con esto puedes controlar la llegada de las url tipo post. puedes indicar que si dentro de un post esta una variable que te interesa, invocar a una función que desees

/**
* POST data process
* get the post data and execute the function
* @example ['post_data'=>'CH::function'] */
public $post=["admin"=>"TuClase::tufuncion"];

 

Variable data_get

Como en el post, si hay alguna variable que venga del get que te interese puedes invocar a una función

/**
* GET data process
* get the get data and execute the function
* @example ['get_data'=>'CH::function'] */
public $get=["tu_variable_get","TuClase::TuFuncion"];

Variable add_filter

Aqui puedes agregar el filtro de WordPress que desees, pudiendo agregar la prioridad de la ejecución de la funcion y si acepta variables o no

/**
* add_filter data functions
* @input array
* @example ['body_class','CH::function',10,2] * @example ['body_class',['CH','function'],10,2] */
public $add_filter=[
["init","TuClase::TuFuncion",10,1],
["init",["TuClase","TuFuncion"],10,1],
];

Variable add_action

Igual que con filter, puedes agregar acciones de WordPress

/**
* add_action data functions
* @input array
* @example ['body_class','CH::function',10,2] * @example ['body_class',['CH','function'],10,2] */
public $add_action=[
["save_post","TuClase::TuFuncion",10,1],
["save_post",["TuClase","TuFuncion"],10,1],
];

Variable dashboard

Siguiendo la referencia para agregar apartados en el Escritorio de WordPress, se ha creado esta variable para configura llamando a la función que desees

/**
* Dashboard
* @reference: https://codex.wordpress.org/Function_Reference/wp_add_dashboard_widget
*/
public $dashboard=[
[
'slug'=>'tu_slug',
'name'=>'Dato que aparece en el escritorio de WP',
'function'=>'TuClase::TuFuncion',
'callback'=>'',
'args'=>'',
] ];

Variable plugin_menu

Aqui se configura el menu del plugin, es posible agregarlo como parte principal en el Menú del escritorio de WordPress o puedes que sea una subsección. depende de tu elección.

Configuración por defecto

 

La configuración del menú va de la siguiente manera:

«path» del tipo array . si Deseas que vaya como menú principal debes indicar que es «Page»

"path"=> ["page"],

en caso que quieres se que sea una sub-pagina de algún apartado sería asi

"path"=> ["subpage","tools.php"],

en caso quieres que sea una opción de los ajustes de WordPress

"path"=>["option"],

«name» Es el nombre que se podrá como titulo del menu
«slug» es el identificador único de esta sección
«function» la función que deseas invocar cuando se accede a esta parte de menú

Puedes crear sub páginas dentro de la página principal

$plugin_menu=[
[
"path"=> ["page"],
"name"=>"My Custom Page",
"function"=>__NAMESPACE__."\Admin::option_page",
// "icon" => "antonella-icon.png",
"slug"=>"my-custom-page",
"subpages"=>
[
[
"name"=>"My Custom sub Page",
"slug"=>"my-top-sub-level-slug",
"function"=>__NAMESPACE__."\Admin::option_page",
] ];

El plugin tiene un ejemplo que puedes modificar a tu gusto.

Variable PostType

Aquí se configura la creación de un post Type, puedes hacer uno o varios desde este apartado.

public $post_types =[
[
'singular'=>'El nombre de tu post-type en singular como por ejemplo bicicleta',
'plural'=>'El nombre de tu post-type en plural como por ejemplo bicicletas',
'slug'=>'la url amigable que desees',
'translate'=>false,  // si quieres que se incluya una traducción de tu post type
'position'=>4, //la posicion en el menu de la administración
'taxonomy'=>['category'], //para agregar taxonomías a tu post type
'image'=>'', //icono de la imagen  -> debes guardarla en img y solo poner el nombre de la imagen con su extensión
],

Variable Widget

Para crear Widgets Sólo necesitas crear en la consola un nuevo Controlador del tipo Widget

php antonella Widget MiClaseWidget

donde MiClaseWidget es el nombre de la clase. Generará un archivo como en los controladores MiClaseWidget.php con el código necesario para empezar a programar

Luego en configuración debes agregar la clase en su sección

/**
         * Widget
         * For register a Widget please:
         * Console: php antonella Widget "NAME_OF_WIDGET"
         * @input array
         * @example public $widget = [__NAMESPACE__.'\YouClassWidget']  //only the class
         */
        public $widgets=[
// aquí van las clases de los Widgets
];

 

 

Llamando a la configuración

En caso necesites algún dato de la configuración para tus funciones puedes hacer  lo siguiente:

$config= new __NAMESPACE__\Config;

$options= $config->plugin_options;

Lo Básico

Controladores por defecto

Antonella Framework tiene por defecto controladores que ordenan las funciones que deseas crear. tiene funciones por defecto el cual puedes usar en cualquier otro apartado de los controladores.

Init.php

En la función index por defecto puedes poner lo que necesites cada vez que se ejecuta el plugin.

Los POST y los GET son controlados desde Config.php en las opciones de GET y POST

Admin\PageAdmin.php

Este archivo puedes colocar la vista de la página admin en caso necesitas crearlo.

Install.php

Install.php controlará todo lo referente a la instalación del plugin. como la creación de tablas dentro de la base de datos de WordPress. La creación de las opciones del plugin se configurar desde Config.php

Creando tablas

$options=[

[

"table"=>"tu_tabla",

"query" =>" id int(11) NOT NULL AUTO_INCREMENT, columna TEXT ",

],

];

$install= $this->table_make($options)

donde:

«table» es el nombre de la tabla

«query» son las columnas a crear siguiendo los patrones de MySQL siguiendo los patrones de column options

Puedes crear varias tablas en en array $options

la Variable $this es en caso que crees la funcion dentro del archivo Install.php, en caso contrario sería

$tables= new __NAMESPACE__.\Install;

$tables->table_make($options);

Unistall.php

Aquí puedes poner tus funciones referentes cuando el plugin es borrado de WordPress. por defecto se borran las opciones de WordPress que usa este plugin y que se encuentra en Config.php

Users.php

Aquí puedes poner las funciones referentes a las opciones de usuarios de WordPress. por defecto genera las variables del usuario activado en ese momento

$data= new __NAMESPACE__.\Users;

//puedes llamar las opciones de usuario de WP

$login_name= $data->user->user_login;

Creando tu controlador

en caso deseas crear tu propio controlador puedes hacerlo usando la consola de antonella

php antonella make TuControlador

donde «TuControlador» es el nombre de tu controlador.

Antonella consola creara un archivo en la carpeta src como TuControlador.php donde esta el código inicial para empezar

LLamando tu controlador

desde cualquier parte del plugin

$foo= new __NAMESPACE__.\TuControlador

$foo->TuFuncion(); //para llamar a una función

$foo->data; //para llamar a una variable de la clase

Creando Widgets

Antonella te ayuda a crear Widgets usando la consola

php antonella widget EjemploWidget

donde EjemploWidget es el nombre de tu Widget

Antonella creará un archivo llamado EjemploWidget.php en la carpeta src con lo necesario para crear tu widget.

Registrar mi Widget

Para ello debes ir al archivo Config.php e ir a la sección $widgets

/**
* Widget
* For register a Widget please:
* Console: php antonella Widget "NAME_OF_WIDGET"
* @input array
* @example public $widget = [__NAMESPACE__.'\YouClassWidget'] //only the class
*/
public $widgets=[__NAMESPACE__.'\EjemploWidget'];

Dos vías de trabajo

Dos vías de trabajo

Antonella Framework sigue el sistema PSR-4 para poder crear un proyecto grande en equipo pero también es posible poder generar un solo controlador que maneje lo necesario para tu plugin. Aquí explicamos las dos formas de de trabajar:

 

Usando el sistema de archivos del framework.

Cada cosa en su sitio y cada sitio en su lugar.  El sistema de archivos ubicados en la carpeta src contiene controladores para apartados específicos de un plugin estandar de WordPress. puedes crear funciones dentro de su controlador e incluirlo dentro de la configuración (src\config.php). Este sistema es recomendable para trabajos en equipos.

Podemos agregar shortcodes (shortcodes.php)

Agregar funciones al instalar y desinstalar (Install.php y Unistall.php)

Agregar funciones al iniciar el plugin (Init.php)

Agregar funciones referente a los datos del usuario registrado (Users.php)

Agregar funciones referente al PostType (PostTypes.php)

Creando Controladores propios

Si tu plugin es muy sencillo puedes usar un solo archivo creando un controlador y creando tus funciones en ese controlador

puedes crearlo desde la consola con Antonella console:

php antonella make TuControlador

Se creará un controlador con una clase con el mismo nombre de tu archivo creado (en este ejemplo TuControlador.php)

<?php
namespace CH;
class TuControlador
{
     public function__construct()
     {
     }
}

Puedes crear tus funciones en la clase y luego agregarlos en config.php

por ejemplo creas la funcion Mifuncion() dentro de tu controlador y deseas que sea una parte del init de WordPress

dentro de config.php

public $add_action=['init','CH\Tucontrolador::Mifuncion'];

 

 

Consola

Consola Antonella

Antonella Framework contiene su propia consola al mismo estilo de artisan de Symfony el cual tiene las siguientes opciones:

Crear controlador

php antonella make TuControlador

Creará automáticamente un archivo .php en la carpeta src con el nombre TuControlador.php con el código necesario para empezar a programar.

Cambiar namespace

El namespace de php es necesario para programar con el framework. por defecto es CH pero puedes cambiarlo

php antonella namespace TUNAMESPACE

Donde TUNAMESPACE es el nombre nuevo que  deseas asignar

En caso de usar Antonella framework en más de un plugin en el mismo WordPress será necesario que tengan Namespace distintos.

Puedes crear Namespaces aleatorios si no le pones un nombre

php antonella namespace

Antonella se encargará de generar uno.

Crear Widgets

php antonella widget  EjemploWidget

Genera un archivo php en la carpeta src con el nombre EjemploWidget.php con el código necesario para crear tu widget

Quitando y añadiendo Blade

Antonella Framework viene con blade instalado por defecto. Pero si no deseas usarlo y ahorrar espacio de disco en el plugin puedes quitarlo con este comando

php antonella remove blade

Así mismo si deseas agregarlo nuevamente:

php antonella add blade

Exportar tu plugin

php antonella makeup

genera un archivo .zip del plugin con los archivos necesarios para que funcione el plugin.

Ayuda

Antonella dispone de un sistema de ayuda

php antonella help

Packages

Paquetes Externos

Antonella Framework acepta paquetes de terceros ya sean hechos para WordPress o no.

Puedes encontrar una gran variedad en Packagist.org y poder invocarlos desde el archivo composer.json. Estos paquetes se guardarán en la carpeta Vendor.

Aviso: el uso se paquetes externos aumenta considerablemente el tamaño de tu plugin y si es un paquete no seguro puede llevar a huecos de seguridad en tu WordPress por lo que se recomienda usarlos sólo si es necesario y si son paquetes de confianza

Ejemplo:

Si estamos acostumbrados con el paquete Eloquent para el control de base de datos de WordPress o para invocar una base de datos externa podemos hacer lo siguiente:

buscamos en Packagits «eloquent for WordPress»

lo agregamos a nuestro composer.json


{
"require": {
"tareq1988/wp-eloquent": "dev-master"
}
}

y luego ejecutamos composer

composer update

Con esto ya podemos utilizar Eloquent para nuestro WordPress


$db = \WeDevs\ORM\Eloquent\Database::instance();

var_dump( $db->table('users')->find(1) );
var_dump( $db->select('SELECT * FROM wp_users WHERE id = ?', [1]) );
var_dump( $db->table('users')->where('user_login', 'john')->first() );

Existen muchos paquetes que nos pueden ayudar para el desarrollo de nuestro plugin. Disfruta!

 

Agregar Plugins a nuestro proyecto como módulos

Puedes hacer que cualquier plugin del repositorio de WordPress sea parte de tu plugin como un módulo

Desde https://wpackagist.org puedes obtener la linea que necesitas agregar en la parte «require» de tu archivo composer.json

Como los plugins de WordPress no cumplen con el sistema de desarrollo PSR-4 Debes agregar el archivo de inicio del plugin en la sección «autoload» de tu archivo composer.json.

 

"autoload": {
        "psr-4": {"CH\\": "src/"},
        "files":{["vendor/contact-form-7/wp-contact-form-7.php"]}
    },

en caso quieras agregar ContactForm7 como un módulo

Video explicativo: https://www.youtube.com/watch?v=qv-rHY_4zhk

 

Crear Paquetes para Antonella Framework

Es posible crear paquetes para WordPress y usarlo con AntonellaFramework.

Ejemplos:

https://github.com/ArroyoLabs/erdiko-wordpress

https://packagist.org/packages/drewjbartlett/wordpress-eloquent

Para ellos es recomendable seguir la documentación de https://packagist.org

Puedes seguir el curso de creación de paquetes para php de styde

Puedes publicar tu paquete dentro de la documentación de Antonella Framework enviando el link al email packages@antonellaframework.com

 

Blade

Sistema de Plantillas Blade

Blade es un simple pero poderoso motor de plantillas. A diferencia de otros populares motores de plantillas para PHP, Blade no limita el uso de código PHP puro en las vistas. Las vistas en Blade se compilan a código PHP y se cachean hasta que son modificadas, lo que genera un alto rendimiento de compilación. Las vistas en Blade usan la extensión .blade.php y normalmente se almacenan en el directorio resources/views.

 

Llamando a la plantilla

desde tu controlador

$query = \WPQuery();

 $blade = new Blade(plugin_dir_path( dirname(__DIR__ )).'resources/views', plugin_dir_path( dirname(__DIR__ )).'storage/cache');
        echo $blade->render('index', ['query' => $query]);

con esto estas llamando a la vista index.blade.php y enviando los valores de la variable $query

Generación de Plantillas (Layouts)

Definir una plantilla

Dos de los principales beneficios de usar Blade son la herencia de plantillas y las secciones. Primero, examinaremos un layout «master». Es recomendable definir este layout como una única vista Blade:

<!-- Guardada en resources/views/layouts/app.blade.php -->

<div class="warp">
<div>App Name - @yield('title')</div>

<div class="container">
@yield('content')
</div>

</div>

Como puedes observar, este archivo contiene una estructura HTML típica. Sin embargo, tiene 2 cosas poco comunes: @section y @yield. La directiva @section,  define un sección de contenido, mientras que la directiva @yield es utilizada para mostrar el contenido de una sección.

Una vez que se tiene definido un layout para la aplicación, se puede definir una página hija que hereda de este layout.

Usar una plantilla Hija

<!-- Stored in resources/views/child.blade.php -->

@extends('layouts.app')

@section('title', 'Page Title')

@section('content')
<p>This is my body content.</p>
@endsection

Cuando defina una vista hija, utiliza la directiva Blade @extends para especificar de qué layout debe «heredar».

Mostrar Datos en la Vista

Cuando llamas a la plantilla blade lo puedes hacer enviando valores del tipo string, array u objeto.

para mostrarlos sólo necesitas

{{ $dato }} //en caso de ser string o int

@foreach($query as $q)

{{ $q }}

@endforeach

En caso de ser un array u objeto

Definiendo condicionantes

@if (count($records) === 1)
I have one record!
@elseif (count($records) > 1)
I have multiple records!
@else
I don't have any records!
@endif

@isset($records)
// $records is defined and is not null...
@endisset

@empty($records)
// $records is "empty"...
@endempty

Switch

@switch($i)
@case(1)
First case...
@break

@case(2)
Second case...
@break

@default
Default case...
@endswitch

Comentarios

Blade también permite definir comentarios en las vistas. Sin embargo, a diferencia de los comentarios HTML, los comentarios Blade no se incluyen en el HTML final de la aplicación:

 {{-- Este es un comentario que no se mostrará en el HTML final --}} 

 

Usar PHP puro

En algunas situaciones, es útil incrustar código PHP en sus vistas. Puede usar la directiva Blade @php para ejecutar un bloque de PHP simple dentro de su plantilla:

@php
//
@endphp

Incluir SubVistas

La directiva @include le permite incluir una vista Blade desde otra vista. Todas las variables disponibles en la vista padre se pondrán usar:

 @include('shared.errors') 
 @include('view.name', ['some' => 'data']) 

 

Disfruta!

Powered by Carlos Herrera