WPTech Nantes 2014

Lors du WPTech Nantes 2014, j’ai eu la chance de pouvoir présenter un atelier consacré au plugin Piklist. Vous trouverez ci-après mes slides au format PDF ainsi qu’une archive contenant le code du plugin de démonstration que j’ai utilisé pour illustrer cet atelier.

Slides de l’atelier Piklist au format pdf

Plugin de démonstration utilisé lors de l’atelier au format zip

Si vous souhaitez tester le plugin de démonstration, n’oubliez pas de télécharger, d’installer et d’activer le plugin Piklist.

Piklist : 8- Création de widget

Interface des widgets Piklist

Piklist regroupe tous les widgets créés à l’aide de son framework dans un seul widget parent composé d’un menu déroulant qui propose l’ensemble des widgets. Pour accéder à votre widget Piklist, l’utilisateur devra donc selectionner dans un premier temps le widget parent Piklist puis votre widget via le menu déroulant.

piklist-widget

Création d’un widget

1- Structure des dossiers

Comme habituellement avec Piklist, tout commence avec la création d’une structure de dossier. Pour créer vos widgets à l’aide de Piklist, il vous faudra d’abord créer un sous-dossier nomé « widgets » dans le dossier « parts ».

...
--parts
---widgets

Pour revoir la structure des dossiers Piklist, relisez l’article intitulé « Piklist: 1- Structure des dossiers »

2- Ecriture des fichiers

Pour concevoir un widget Piklist, vous devrez créer un ou deux fichiers php :

  • widget-name-form.php: ce fichier est optionnel et servira à définir les champs de formulaire utilisés pour choisir les options et/ou saisir des contenus.
  • widget-name.php: ce fichier est requis et nous permettra de définir le widget.

widget-name-form.php

Ce fichier n’est nécessaire que si votre widget poropose des choix d’options ou des saisies de contenus. Le nom de ce fichier se terminera par « …-form.php« . La création de widgets avec Piklist est simple et se base une fois encore sur la manipulation de tableaux php. Supposons que votre widget ait besoin d’une interaction avec l’utilisateur sous la forme de trois champs textes pour saisir une explication, un prénom et un nom. Dans le fichier widget-name-form.php, nous écrirons trois tableaux php que nous passerons en argument de la fonction piklist() de la façon suivante :

piklist('field', 
array(
  'type'        => 'text',
  'field'       => 'champ_text_explication',
  'label'       => 'Title',
  'description' => 'Field Description',
  'value'       => 'Default text',
  'attributes'  => array(
                        'class' => 'text',
                        )
)
);

piklist('field', 
array(
  'type'        => 'text',
  'field'       => 'champ_text_prenom',
  'label'       => 'Title',
  'description' => 'Field Description',
  'value'       => 'Default text',
  'attributes'  => array(
                        'class' => 'text',
                        )
)
);

piklist('field', 
array(
  'type'        => 'text',
  'field'       => 'champ_text_nom',
  'label'       => 'Title',
  'description' => 'Field Description',
  'value'       => 'Default text',
  'attributes'  => array(
                        'class' => 'text',
                        )
)
);

Vous retrouvez une synthaxe similaire à celle utilisée pour déclarer des champs dans les métaboxes Piklist. Nous sommes partie d’un exemple simple (3 champs texte) mais vos widgets pourront bénéficier de tous les types de champs fournit par Piklist (input text, select, boutons radios, textarea, editeur avancée, color picker, champs groupés, répétiteur de champs …).

widget-name.php

Ce fichier, que vous nommerez de la même manière que le début du fichier widget-name-form.php, est obligatoire et doit se trouver dans votre dossier ../parts/widgets/
C’est ici que vous allez déclarer votre widget, lui donner un nom et une description grâce aux premières lignes de commentaires du fichier. Tout ce qui sera dans ce fichier sera affiché sur votre front-end (code html, valeur des champs d’options …).

/*
Title: Mon widget
Description: Widget qui en met plein la vue
*/

Ensuite, déclarez les variables classiques des widgets WordPress qui généreront les balises html correspondantes :
/*
Title: Mon widget
Description: Widget qui en met plein la vue
*/
<?php echo $before_widget; ?>

<?php echo $before_title; ?>
 
<?php echo $after_title; ?>
 
<?php echo $after_widget; ?>

Enfin disposez le contenu de vos champs (si vous en avez définis dans un fichier widget-name-form.php) là où vous voulez qu’ils s’affichent :
/*
Title: Mon widget
Description: Widget qui en met plein la vue
*/
<?php echo $before_widget; ?>
<?php echo $settings['champ_text_explication']; ?>
<?php echo $before_title; ?>
 
<?php echo $after_title; ?>
<?php echo $settings['champ_text_prenom']; ?>
<?php echo $settings['champ_text_nom']; ?>
<?php echo $after_widget; ?>

Et voila, notre widget est terminé et prêt à fonctionner. Bien que l’interface des widgets Piklist soit particulière (un Widget parent avec des widgets enfants que l’on sélectionne via un menu déroulant) elle est compatible avec l’interface wysywig du Customizer WordPress.

Piklist : 6- Création d’une page d’options

Les pages d’options servent généralement à regrouper sur une même page un ensemble de réglages permettant de paramétrer votre application web. Ces réglages sont accessibles par les utilisateurs via les différents types de champs que nous connaissons (texte, radios boutons, menu déroulant …) et qui sont regroupés dans des « sections ». Avec Piklist, vous allez pouvoir créer facilement une page d’options, y ajouter tous les types de champs proposés par Piklist et même organiser vos sections de champs en onglets. Piklist s’appuie sur l’API WordPress, la création d’une page d’option comprend donc une étape d’enregistrement puis d’ajout des sections et enfin d’ajout des champs.

Enregistrer la page d’options

Comme souvent avec Piklist, tout commence avec un tableau dans lequel seront définis les caractéristiques de la page d’options à l’aide d’un système clé/valeur. Pour que ces paramètres soient pris en compte par Piklist, il faut définir ce tableau dans une fonction qui sera appelé sur le Hook « piklist_admin_pages ».

Si vous travaillez à partir d’un thème, le code sera ajouté au fichier functions.php. Si vous développez un plugin, le code devra être ajouté dans le fichier principal.

add_filter( 'piklist_admin_pages' , 'piklist_theme_setting_pages' );
  function piklist_theme_setting_pages( $pages ) {
     $pages[] = array(
      'page_title'  => __( 'Custom Settings' , 'textdomain' ),
      'menu_title'  => __( 'Settings' , 'textdomain' ),
      'sub_menu'    => 'themes.php' // Under Appearance menu,
      'capability'  => 'manage_options',
      'menu_slug'   => 'custom_settings',
      'setting'     => 'my_theme_settings',
      'menu_icon'   => plugins_url('piklist/parts/img/piklist-icon.png'),
      'page_icon'   => plugins_url('piklist/parts/img/piklist-page-icon-32.png'),
      'single_line' => true,
      'default_tab' => 'Basic',
      'save_text'   => 'Save Demo Settings',
    );
 
    return $pages;
  }

Les noms des paramètres du tableau sont suffisament explicites pour deviner leur rôle respectif.

Création des sections

Avant de créer les sections, souvenez-vous qu’il faut respecter une structure de dossier. Vos fichiers php devront être déposés dans un dossier nommé « settings »:

...
/plugin-folder
  /parts
    /settings

Tous les champs déclarés dans un même fichier php seront regroupés dans la même section. Les attributs de cette section sont définis sous forme de commentaires en tête du fichier php.

<?php
/*
Title: My Settings Section
Setting: my_theme_settings
Tab: Advanced
Order: 20
Tab Order: 30
*/

Description des attributs

Title
Nom de la section. Apparaîtra dans une balise < h3 >
Exemple: My Settings Section

Setting
Correspond au "setting" auquel cette section appartient. C'est en fait la valeur du paramètre "setting" définie lors de l'enregistrement de la page d'options.
Exemple: my_theme_settings

Tab
Si le paramètre "Tabs" a été définie lors de l'enregistrement de la page d'option, les sections pourront être réparties en plusieurs onglets. La valeur de "Tab" correspondra alors au nom donné à l'onglet accueillant la présente section.
Exemple: Advanced

Order
Définie l'odre des sections de la page d'options.
Exemple: 1, 2, 3, etc

Tab Order
Définie l'ordre d'affichage des onglets si vous choisissez d'organiser vos sections en onglets.
Si vous avez plusieurs sections (fichiers php) qui sont assignés à un seul onglet, assurez-vous que la première section (ou toutes) aient le bon (ou le même) numéro.

L'onglet par defaut qui est enregistr
Lors de l'enregistrement de la page d'options via le filtre (hook) "piklist_admin_pages", un onglet par défaut est défini par le paramètre "default_tab". Cet onglet recevra alors automatiquement un "Tab Order: 10". En affectant un chiffre inférieur, vous pouvez placer vos onglets avant l'onglet "default_tab".
Exemple: Tab Order: 20

Ajout des champs

Il ne vous reste plus qu'à ajouter des champs dans les sections. Pour plus de détail sur la création des champs et leurs paramétrages, je vous renvoie à l'article intitulé "Piklist : 4- Champs et paramètres"

Par exemple ici, ajoutons un champ texte:

<?php
/*
Title: My Settings Section
Setting: piklist-examples
Tab: Advanced
Order: 20
Tab Order: 30
*/

piklist( 'field', array(
                'type'  => 'text',
                'field' => 'text',
                'label' => 'Text Box',
                'description' => 'Field Description',
                'help'  => 'This is help text.',
                'value' => 'Default text',
                'attributes' => array(
                   'class' => 'text',
                  )
                )
);

Afficher les valeurs des champs

Pour récupérer et afficher les valeurs des champs dans votre thème, utilisez la fonction get_option('my_theme_settings'), 'my_theme_settings' étant la valeur du paramètre 'setting' définie lors de l'enregistrement de notre page d'option.

<?php
  // Récupération des options de la section 'my_theme_settings' dans un tableau
  $theme_options = get_option('my_theme_settings');

  // Récupération de la valeur du champ 'text'
  $text_field = $theme_options['text'];
 
  // Affichage du champ 'text'
  echo 'This is a text field' . $text_field;
 
?>

Piklist : 5- Création d’un Custom Post Type

Avant-propos

La philosophie de Piklist est de fournir un framework pour WordPress sans réinventer la roue. Les développeurs de Piklist se sont donc attachés à utiliser au maximum les API de WordPress. Ainsi, pour enregistrer un Custom Post Type, Piklist utilisera l’API des Custom Post Type, idem pour les widgets, les pages d’options …
Concernant les Custom Post Type, Piklist étend la fonction register_post_type() afin de proposer de nouveaux paramètres qui activeront des fonctionnalités supplémentaires.

Enregistrer un Custom Post Type avec Piklist

L’enregistrement se fait en deux étapes:
1- Création d’une fonction avec déclaration des paramètres de votre CPT.
2- Hooker cette fonction sur le filtre piklist_post_types().

add_filter( 'piklist_post_types' , 'demo_post_type' );
function demo_post_type($post_types) {
  $post_types['demo'] = array(
    'labels'  => piklist('post_type_labels', 'Demo'),
    'public'  => true,
    'rewrite' => array(
          'slug' => 'demo',
    ),
    'supports' => array(
      'author',
      'revisions',
    ),
    'hide_meta_box' => array(
      'slug',
      'author',
      'revisions',
      'comments',
      'commentstatus',
    )
  );
 
  return $post_types;
}

Enregistrer plusieurs Custom Post Type avec Piklist

La procédure est à peu prêt la même:
1- Création d’une fonction avec déclaration des paramètres de vos CPT.
2- Hooker cette fonction sur le filtre piklist_post_types().

add_filter( 'piklist_post_types' , 'demo_post_types' );
function demo_post_types($post_types) {
  $post_types = array_merge( $post_types , array(
    'piklist_demo' => array(
        'labels'   => piklist( 'post_type_labels', 'Piklist Demo' ),
        'title'    => __( 'Enter a new Demo Title' , 'textdomain'),
        'supports' => array(
                     'title',
                     'revisions'
         ),
       'public'      => true,
       'has_archive' => true,
       'rewrite'     => array(
              'slug' => 'piklist-demo'
       ),
       'edit_columns' => array(
          'title'        => __('Demo'),
          'author'       => __('Assigned to'),
        )
     ),
    'piklist_demo_2' => array(
        'labels'   => piklist( 'post_type_labels' , 'Piklist Demos 2' ),
        'title'    => __('Enter a new Demo Title' , 'textdomain'),
        'supports' => array(
               'title',
               'revisions'
           )
        'public'      => true,
        'has_archive' => true,
        'rewrite'     => array(
            'slug' => 'piklist-demo-2'
        )
       )
  ));
 
  return $post_types;
}

La différence se situera dans la fonction de déclaration ou vous devrez déclarer les paramètres pour tous les CPT et fusionner le tout dans un tableau à l’aide de la fonction PHP array_merge().

Paramètres Piklist additionnels

Si vous avez enregistré votre CPT avec Piklist, vous pourrez non seulement utiliser les paramètres classiques de WordPress mais aussi ceux fournit par Piklist dont voici la liste:

Piklist : 4- Champs et paramètres

Liste des champs Piklist

Chaque champ Piklist est créée à l’aide d’un tableau php auquel on affecte des paramètres sous la forme classique clé/valeur. La plupart des paramètres des champs Piklist sont les mêmes pour les Posts, les Pages, les Taxonomies, les Pages d’Options, les Medias, la page Utilisateur ou les Widgets. Oui avec Piklist vous pouvez ajouter des metabox/champs personnalisés dans toutes ces parties de l’administration WordPress.

Piklist met à votre disposition les types de champs suivants que vous pouvez utiliser partout, même dans vos widgets:

  • Texte
  • Textarea
  • Editeur avec TinyMCE
  • Menu déroulant mono-selection
  • Menu déroulant multi-selection
  • Radio bouton
  • Case à cocher
  • Bouton d’upload de fichier
  • Bouton d’upload via l’interface des Medias
  • Color Picker
  • Calendrier JQuery
  • Regroupement de champs
  • Répétiteur de champs ou de groupe de champs avec re-order drag an drop
  • Affichage conditionnel de champs selon les choix de l’utilisateur
  • Champ caché
  • Champ HTML
  • Relation Post to Post

Pour le détail de l’implémentation de chaque type de champ, je vous renvoie vers la documentation de Piklist.

Quelques remarques:

Piklist propose un template d’affichage des champs par défaut qui respecte la charte graphique WordPress. Visuellement, vos customisations s’intègrent donc parfaitement à l’interface d’administration de WordPress. Cepandant Piklist vous laisse la possibilité de re-définir le style de ces templates.

Piklist propose également des hooks pour filtrer par exemple les données des pages d’options avant l’enregistrement en base de données.

La « Sanatization » et la « Validation » des données des champs sont également contrôlables par le développeur grâce à des hooks prévus à cet effet.

Liste des paramètres des champs Piklist

type

Le type de champ que vous voulez afficher
– Valeurs: tous les types de champs proposés par Piklist.

'type' => 'checkbox'

field

Le nom du champ tel qu’il sera enregistré dans la base de données
Ce nom doit être unique pour ne pas rentrer en conflit avec d’autres noms de champs. C’est ce nom que vous utiliserez pour récupérer la donnée et afficher le contenu de votre champ.

'field' => 'product_description'

label

Texte affiché pour désigner votre champ.
Cela peut être du texte standard ou localisé (recommandé pour la traduction)
– Exemple pour un text standard:

'label' =>'Product Description'

– Example pour un texte localisé (recommandé):

'label' => __('Product Description','textdomain')

description

Texte de description du champ

'description' => __('Please describe this product','textdomain')

help

Donne accès à un « tooltip » d’aide sous la forme d’une icône ‘?’ à côté du label.

'help' => __('Some help on this field.','texdomain')

scope

Détermine la façon dont les valeurs des champs sont sauvegardées
En apprendre plus ici.
Uniquement utilisé pour les champs dans les Posts, les Taxonomies et la page profil Utilisateur.
Dans la plupart des cas, vous n’avez pas à vous préocupper de cet attribut, Piklist s’en occupe.
– Valeurs possibles: post, post_meta, taxonomy, taxonomy_meta, user, user_meta
– Valeur par défaut: Piklist choisit la bonne valeur en fonction de l’emplacement du champ. Si votre champ est déclaré par exemple dans une metabox d’un Post, la valeur par défaut de « scope » sera « post_meta ».

'scope' => 'post_meta'

template

Défini le template utilisé pour afficher le champ.
Cet attribut permet de surcharger le template par défaut appliqué par Piklist.

'template' => 'post_meta_custom'

value

Permet d’attribuer une valeur par défaut au champ
Cette valeur doit correspondre avec le type de champ utilisé. Par exemple pour un champ texte, cette valeur doit être une chaîne de caractère. pour un champ « select » la valeur assignée doit être une des valeurs de la liste.

'value' => 'my default'

columns

Defini la largeur occupée par le champ grâce à un système de grille à 12 colonnes.
Lorsque cet attribut est utilisé au sein d’un « groupe de champ » la somme des colonnes de chaque champ doit être égal à 12.

'columns' => '12'

capability

Défini la visibilité du champ en fonction des droits/profil de l’utilisateur
Le champ sera non visible pour tous les autres utilisateurs. Se repporter à la page du Codex pour retrouver les droits et profils gérés par WordPress.

Cet attribut peut accepter soit un droit (User Capability) soit un profil (User Role).

Profils: SEUL les utilisateurs ayant ce profil pourront voir ce champ. Par exemple si le rôle est “contributor”, seulement les profils Contributeurs verront ce champ. Les profils Editeurs, Administrateurs … ne verront pas le champ.

'capability' => 'contributor'

Droits: Vous pouvez aussi définir un droit. Comme la plupart des droits, pour un type de profil, sont aussi valables pour les profils supérieurs, l’utilisation d’un droit pour cet attribut est un moyen de montrer le champ pour plusieurs types d’utilisateurs.

'capability' => 'manage_options'

add_more

Permet de rendre un champ ou groupe de champ « répétable »
Un bouton « + » et « – » permet de dupliquer à l’infini le champ ou groupe de champ. Une fonction de « drag and drop » permet de redéfinir l’odre des champs répétés.
– Valeurs possibles: true, false
– Valeur par défaut: false

'add_more' => false

choices

Défini une liste de choix pour les champs qui peuvent en accepter
(Exemple: radio buttons, checkboxes, etc)

'choices' => array(
  'first' => 'First Choice',
  'second' => 'Second Choice',
  'third' => 'Third Choice'
 )

list

Enveloppe les valeurs du champ dans une liste « ul » si défini à « true »
Utilisé pour les champs à selection multiple tel que les cases à cocher ou les menus déroulant (select) à choix multiples.
– Valeurs possibles: true, false
– Valeur par défaut: true

'list' => true

position

Défini la balise d’enveloppement du champ
Pour envelopper des champs dans une même table, attribuez l’attribut « position » du premier champ à « start » et « end » pour le dernier champ. Tous les champs intermédaires n’auront pas besoin de l’attribut « position ». Pour garder chaque champ dans son propre tableau, assignez l’attribut « position » avec la valeur « wrap ».

– Valeurs possibles: start, end, wrap

'position' => 'wrap'

serialize

Sauvegardez vos données dans la base de façon sérialisé.
Par défaut, les valeurs sont stockés de façon unique dans la base ainsi Piklist peut retrouver chaque valeur de champ de manière individuelle. Pour sauvegarder les valeurs dans un tableau serialisé, assignez l’attribut « serialize » à « true ». Cela fonctionne également pour tous les champs de selection multiple.
– Valeur par default: false

'serialize' => 'false'

attributes

Attributs HTML appliqués à la balise HTML du champ.
Cela peut inclure des actions JavaScript tel que « onFocus » ou « onBlur » par exemple. Les paramètres de cet attribut acceptent un tableau de paramètres additionnels:

Cet exemple montre comment les tableaux sont écrit mais ce n’est qu’un exemple. Des paramètres ne fonctionneront qu’avec un certain type de champ.

'attributes' => array(
  'title'    => 'field-demos',
  'alt'      => 'field-demos',
  'tabindex' => '1',
  'class'    => 'small-text',
  'placeholder' => 'Placeholder text',
  'cols'    => 6,
  'rows'    => 3,
  'size'    => 6,
  'step'    => 15,
  'min'     => 5,
  'onfocus' => "if(this.value == 'default_value') { this.value = ''; }"
 )

title

Assigne un titre html au champ.

alt

Assigne un « alt name » au champ.

tabindex

Assigne le « tabindex » de ce champ.

class

Assigne une classe css au champ.

cols

Assigne une largeur à un champ textarea.

rows

Assigne le nombre de colonnes d’un champ textarea.

size

Assigne le « size » d’un champ.

step

Permet à l’utilisateur de faire défiler certains champs.

min

Assigne une valeur minimum autorisée à un champ.

Piklist : 3- Création des metaboxes

Piqûre de rappel sur les metaboxes

Les metaboxes sont ces contenaires que l’on trouve généralement sous l’éditeur des « posts » de WordPress ou à droite de l’éditeur, dans la sidebare. Ces conteneurs regroupent des champs personnalisés et sont utiles pour organiser notre interface back-end en regroupant ces champs par thématique. Ces metaboxes peuvent être déplacées dans notre interface par « drag and et drop » et peuvent s’afficher à l’état plié ou déplié.

Création d’une metabox avec Piklist

Piklist permet de créer des métaboxes de façon très simple et de définir à l’aide de paramètres leurs caractéristiques (état plié/déplié, position, titre, affichage conditionnel …).

Pour créer une metabox, créez un nouveau fichier php que vous nomerez comme bon vous semble et placez le dans le dossier ../parts/meta-boxes. Tous les champs personnalisés codés dans ce fichier seront groupés dans la même metabox. La seule chose à faire pour concevoir votre metabox est d’ajouter dans ce fichier php un bloc de commentaires avec des instructions spécifiques (voir ci-après). C’est le même concept de déclaration par commentaires que pour les plugins ou les pages template de WordPress.

<?php
/*
Title: Ma Metabox
Description: Ma super metabox qui déchire
Post Type: my_post_type
Capability: manage_options
Context: normal
Priority: high
Order: 1
Status: published,prequote,repair-quote
Locked: true
New: false
Collapse: true
*/

Description des attributs

Chaque attribut doit être suivi de ':' sans espace. En revanche la valeur de l'attribut doit être précédée d'un espace. Ce sont les mêmes règles de fonctionnement que pour les commentaires de déclaration des plugins ou des pages templates de WordPress.

Title

Nom de la metabox.
Ce titre apparaîtra entouré d'une balise HTML "h3". Il est aussi possible d'ajouter d'autres balises HTML.
- Exemple: Ma Metabox
- Exemple avec HTML: Ma Metabox < span class=”alignright” >Vérifier ces champs< /span >

Description

Description de la metabox.
Cet attribut ne fait rien d'autre que d'ajouter une description pou votre metabox.

Post Type

Indique le type de post qui affichera cette metabox.
- Valeurs possibles: ‘post’, ‘page’, ‘link’, ou ‘custom_post_type’ où "custom_post_type" est le slug de votre custom post type.
- Valeur par défaut: none

Capability

Définie la visibilité de la metabox en fonction des droits attribués à l'utilisateur.
Cela ne s'applique pas comme un droit “minimum”, seuls les utilisateurs ayant ce droit pourront visualiser la metabox. N'utilisez pas cet attribut si vous souhaitez que tous les utilisateurs puissent visualiser cette metabox. (Prévu dans une futur version: possibilité de passer un tableau de plusieurs droits utilisateurs). Attention, n'utilisez pas l'attribut "Capability" et "Role" en même temps. Utilisez l'un ou l'autre ou aucun.
- Exemple: ‘manage_options’
- Valeur par défaut: Tous ce qui est définie dans "register_post_type"

Role

Définie la visibilité de la metabox en fonction du rôle attribués à l'utilisateur.
Ce n'est pas un droit “minimum”, seuls les utilisateurs ayant ce rôle pourront visualiser la metabox. (Prévu dans une futur version: possibilité de passer un tableau de plusieurs rôles utilisateurs). Attention, n'utilisez pas l'attribut "Capability" et "Role" en même temps. Utilisez l'un ou l'autre ou aucun.
- Exemple: ‘administrator’

ID

Limite la visibilité de la metabox dans une Page ou un Post.
Utiliser l'ID du Post ou de la Page dans laquelle vous voulez que votre metabox s'affiche.
- Exemple: ‘ID: 2′

Template

Limite la visibilité de la metabox pour Page Template.
Indiquer le nom du fichier de la Page Template sans l'extension “.php”. La page doit être enregistrée avec le Template selectionné.
- Exemple: ‘Template: my-template’

Context

Le context pour lequel la metabox doit s'afficher.
- Valeurs possibles: ‘normal’, ‘advanced’, or ‘side’
- Valeur par défaut: ‘advanced’

Priority

La priorité pour laquelle la metabox doit s'afficher.
- Valeurs possibles: ‘high’, ‘core’, ‘default’ or ‘low’
- Valeurs par défaut: ‘default’

Order

Ordre d'affichage de la metabox.
Permet de définir un ordre d'affichage (selon le contexte et la priorité définie) lorsque l'on travaille avec plusieurs metabox.
- Remarque: si l'attribut “lock” n'est pas défini ou défini à “false”, alors l'odre que vous aurez définie est celui par défaut. L'utilisateur peut redéfinir cette ordre en déplacant la metabox.
- Exemple: 1, 2, 3, etc
- Valeur par defaut: none

Status

Liste des status de Post qui autoriseront l'affichage de la metabox.
Ne pas mettre d'espace après la "," si vous définissez plusieurs status. N'oubliez pas que Piklist permet de définir des status de post personnalisés et que vous pouvez les utiliser ici.
- Exemple: published,prequote,repair-quote
- Valeur par défaut: all

Lock

Définie si il faut vérouiller le déplacement "drag and drop" de la metabox dans l'interface.
- Valeurs possibles: ‘true’, ‘false’
- Valeur par défaut: ‘false’

New

Définie si il faut montrer la metabox lors de la création d'un nouveau Post.
- Valeurs possibles: ‘true’, ‘false’
- Valeur par défaut: true

Collapse

Définie si la metabox sera à l'état ouvert ou fermé par défaut.
- Valeurs possibles: ‘true’,’false’
- Valeur par défaut: ‘false’

Une fois que votre metabox est définie il ne reste plus qu'à y ajouter vos champs personalisés, par exemple ici un simple champ texte:

<?php
/*
Title: Ma Metabox
Description: Ma super metabox qui déchire
Post Type: my_post_type
Capability: manage_options
Context: normal
Priority: high
Order: 1
Status: published,prequote,repair-quote
Locked: true
New: false
Collapse: true
*/

// Déclaration d'un champ texte
piklist( 'field', 
  array(
   'type'  => 'text',
   'scope' => 'post_meta',
   'field' => 'field_name',
   'label' => __('Example Field'),
   'description' => __('Field Description'),
   'attributes'  => array(
                      'class' => 'text',
                     )
   'position'   => 'wrap',
 )
);

Piklist : 2- Constantes

Piklist nous permet d’avoir le contrôle sur certains réglages directement via sa page d’options. Cependant en tant qu’administrateur nous ne souhaitons pas toujours que nos utilisateurs puissent y accéder. Piklist nous permet de désactiver cette page et de définir les réglages directement dans le fichier de configuration de WordPress « config.php » ou dans le fichier « functions.php » de notre thème. Ceci se fait à l’aide de constantes Piklist.

Désactiver la page de réglage de Piklist

Par défaut, tout le monde peut voir la page d’options de Piklist. La constante PIKLIST_SETTINGS_CAP nous permet de modifier cela. Par exemple, sur une installation multisite, si vous souhaitez que seul le super administrateur ait accès à la page d’options de Piklist, ajoutez la ligne suivante dans « config.php » ou « functions.php » :

define( 'PIKLIST_SETTINGS_CAP' , 'manage_network' );

Permettre d’affecter plusieurs rôles aux utilisateurs

Par défaut, WordPress permet d’assigner un seul rôle par utilisateur. Piklist permet d’en assigner plusieurs grâce à la constante PIKLIST_MULTIPLE_USER_ROLES :

define( 'PIKLIST_MULTIPLE_USER_ROLES' , true );

Si cette constante est définie à « true », la case à cocher de ce réglage sera grisé dans la page d’options.

Piklist: 1- Structure des dossiers

Utilisation de Piklist dans un thème

Si vous désirez utiliser le framework Piklist directement dans votre thème, vous devez respecter une structure de fichiers particulière dans le répertoire de votre thème WordPress. Il suffira ensuite de placer votre code Piklist dans des fichiers php et de placer ceux-ci dans les répertoires correspondants aux éléments que vous voulez rajouter. Vous n’aurez pas de mal à vous y retrouver, le nom des répertoires parle de lui-même.

Thème : structure de fichiers à respecter

themes
/votre-theme
  /piklist
    /parts
      /dashboard
      /help
      /media
      /meta-boxes
      /settings
      /terms
      /updates
      /users
      /widgets
      /workflows

Utilisation de Piklist via un plugin

Il est également possible d’utiliser le framework Piklist dans un plugin. Piklist est le plugin « parent » et votre plugin sera un plugin « enfant » de Piklist. Le pré-requis pour que votre plugin fonctionne est donc que le plugin « parent » Piklist soit activé. Pour gérer l’ajout de vos éléments dans l’espace d’administration à l’aide d’un plugin, votre code Piklist doit s’intégrer dans une structure de fichiers au sein du répertoire « /plugins ».

Plugin : structure de fichiers à respecter

plugins
/votre-plugin-piklist
  /parts
    /dashboard
    /help
    /media
    /meta-boxes
    /settings
    /terms
    /updates
    /users
    /widgets
    /workflows

Description des répertoires

Selon le type d’enrichissement que vous souhaiterez ajouter à votre espace d’administration, il faudra placer votre code Piklist dans le répertoire adéquate.

/dashboard : création de champs affichés dans une metabox du tableau de bord.
/help : création d’onglets/metabox d’aides.
/media : création de champs/metabox pour enrichir la page d’édition des médias.
/meta-boxes : création des metabox.
/settings : création des pages d’options.
/terms : création de champs/metabox pour enrichir la page taxonomies.
/updates : création d’une procédure de mise à jour pour les plugins enfants Piklist.
/users : création de champs/metabox pour enrichir la page profil utilisateur.
/widgets : création de widgets.
/workflows : création d’onglets.

Exemple de code Piklist

Que se soit dans un thème ou un plugin, l’utilisation de Piklist est relativement simple. Il s’agit pour l’essentiel de manipuler des commentaires et des tableaux que vous remplissez de clé/valeur représentant vos options. L’utilisation de ces tableaux ressemblent aux tableaux d’arguments que vous passez à l’objet WP_Query par exemple.

Comme un exemple vaut mieux qu’un long discours, voici comment créer une metabox contenant un champ input dans un Custom Pots Type « movie », nous utiliserons Piklist directement dans le thème :

/*
Title: Metabox
Description: Ma metabox
Post Type: movie
Capability: manage_options
Context: normal
Priority: high
Order: 1
Status: published,prequote,repair-quote
Locked: true
New: false
Collapse: false
*/
 
// Création d'un champ texte
 piklist('field', array(
   'type' 		  => 'text'
   ,'scope' 		=> 'post_meta'
   ,'field' 		=> 'field_name'
   ,'label' 		=> __('Champ texte')
   ,'description' 	=> __('Ma Description')
   ,'attributes' 	=> array(
     						'class' => 'text'
   )
   ,'position' 		=> 'wrap'
 ));

Ce code, écrit dans un fichier php, doit être déposé dans le répertoire /piklist/parts/meta-boxes. Tous les champs que vous ajouterez dans ce fichier php appartiendront à la metabox « Metabox ».

Piklist : présentation

Un plugin pour les développeurs fainéants

Piklist, une fois activé, n’affiche aucune interface graphique visible dans votre espace d’administration hormis le Custom Post Type de démonstration si vous l’avez activé dans la page d’options du plugin. L’activation pose une graine, à vous de l’arroser pour la faire grandir. Les auteurs du plugin, Steve Bruner et Kevin Miller, présentent Piklist comme étant un framework. Il serait à WordPress ce que Jquery est à JavaScript, RubyOnRails à Ruby ou Symphony à PHP. Vous pouvez retrouver leurs présentations de Piklist au WordCamp WordPress de New York sur le site WordPress TV.

En clair, tout ce que Piklist permet de faire, vous pourriez le faire avec les API WordPress. Cependant, ce que propose Piklist c’est de s’appuyer sur ces API pour effectuer une partie du travail à votre place. Piklist vous fournit une méthode plus simple, à base de tableaux php, d’options et d’organisation de fichiers pour étendre et enrichir rapidement les outils de gestion de contenu de WordPress sans que vous ayez à vous préoccuper de la partie code longue et fastidieuse.

Piklist pourrait être assimilé à des outils comme CMB, SCB, WPAlchemy, Pods ou ACF. En revanche, à la différence d’ACF, Piklist n’est pas orienté utilisateur en proposant une interface graphique pour générer les éléments dont vous avez besoin, c’est au développeur de mettre en place ces éléments à l’aide du code fournit par Piklist.

C’est donc un plugin intéressant si vous vous reconnaissez dans l’un des cas suivant :

  • Vous êtes un développeur fainéant.
  • Vous êtes soumis à des contraintes de temps.
  • Vous voulez vous consacrer davantage à la conception qu’au développement.

Ce que permet Piklist

Si il fallait résumer en quelques lignes, je dirais que Piklist vous permet de mettre en place rapidement :

  • Des Custom Post Type.
  • Des Custom Taxonomies.
  • Des Pages d’options.
  • Des Widgets.
  • Des Metaboxes avec des champs personnalisés simples et évolués.

Ces éléments peuvent être implémenté directement dans votre thème ou sous forme de plugins enfants de Piklist.

Piklist propose des choses intéréssantes comme l’élaboration d’une interface répartie sur plusieurs onglets ou des groupes de champs de formulaires duplicables que l’on peut réordonner par cliquer/déposer, des metaboxes et des champs qui s’affichent selon certaines conditions. Les différentes possibilités de Piklist vous seront détaillées ultérieurement.

En attendant vous pouvez trouver plus d’informations sur les fonctionnalités de Piklist sur la page de présentation du plugin. Vous pouvez aussi installer et activer le plugin, un custom post type de démonstration vous sera alors proposée pour vous montrez des exemples concrets de ses possibilités.

A la date où j’écris cet article, Piklist s’est concentré sur la possibilité d’étendre l’espace d’administration de WordPress mais les auteurs du plugin ont récemment communiqués sur les futures évolutions et il semble que la possibilité de construire des éléments via l’interface WordPress soit la prochaine étape. Ces évolutions seront probablement des modules payants, Piklist restera en revanche gratuit et Open Source.

Pour conclure

WordPress, depuis quelques années, se positionne comme un outil de gestion de contenu. L’apparition des Custom Post Type et Custom Taxonomies a été dans ce sens mais il reste encore de nombreuses améliorations à apporter. Par exemple la simplification de la création des options et de metaboxes élaborés dans l’espace d’administration. La bonne nouvelle, c’est qu’un groupe de reflexion c’est constitué à ce sujet pour proposer une solution qui soit éventuellement intégrée au Core de WordPress dans les futurs versions. En attendant, Piklist me semble une solution intéressante pour répondre à ce besoin.