Configuration

La configuration du CMS est relativement importante: il permettra d'indiquer toutes les informations nécessaires pour son bon fonctionnement, notamment:

Le type de plugin
La version du plugin
La version du CMS requise
Si le plugin utilise le système de traductions
La configuration que l'utilisateur doit remplir
Etc..

Le format de configuration

La configuration doit être dans le fichier config.cfg.php, sous le format suivant:

<?php/*
  -- reste de la configuration en format JSON --
*/?>

A chaque modification du fichier de configuration, vérifiez que celui ci respecte le format JSON, avec JSONLint ou JSON Editor Online par exemple.

Dans les exemples qui vont suivre, nous ne préciserons pas les commentaires de protections PHP (<?php/* et */?>) pour des raisons de lisibilité.

Configuration minimum

Commençons par la configuration minimum, avec le bloc plugin:

{
  "plugin": {
    "name": "Slider",
    "type": "header",
    "version": "1.0.0",
    "require": {
      "cms": "0.3.0"
    }
  }
}

plugin.name: Nom du plugin
plugin.type: Type de plugin (parmi page, header, sidebar, custom)
plugin.version: Version du plugin (format x.x.x recommandé)
plugin.require.cms: Version minimum du CMS pour que le plugin fonctionne, c'est à dire que le plugin est compatible que si le CMS est en version 0.3.0 ou plus

Langues supportées

Ensuite, si votre plugin est multilingue (fortement recommandé), il faut le préciser en ajoutant ceci après le bloc plugin:

  "lang": {
    "translation": true,
    "default_language": "<langue par défaut>"
  }

La langue par défaut sera utilisée si le CMS utilise une langue que votre plugin n'a pas. Si votre plugin est traduit en anglais, mettez "en" (correspond au code de langue de l'anglais). Nous verrons comment fonctionne les langues dans la page suivante. Notre configuration ressemble désormais à ceci:

{
  "plugin": {
    "name": "Slider",
    "type": "header",
    "version": "1.0.0",
    "require": {
      "cms": "0.3.0"
    }
  },
  "lang": {
    "translation": true,
    "default_language": "en"
  }
}

Configuration utilisateur

Ensuite, il y a 2 blocs importants pour le plugin: data et config. Il permettront à l'utilisateur de configurer le plugin. Ces 2 blocs se configure de la même façon, mais ont 2 fonctionnalités différentes:

Le bloc config sera remplis par l'utilisateur une fois par plugin, elle correspond à la configuration globale de plugin.

Le bloc data pourra être remplis par l'utilisateur à chaque fois que le plugin est utilisé. Si le plugin est de type en-tête, alors l'utilisateur devra configurer le plugin suivant le bloc data a chaque fois.

Par exemple, pour un plugin qui affiche une popup sur chaque page (via les événements, donc de type custom), la configuration sera dans le bloc config.

Mais pour un plugin Slider (de type en-tête), il faudra configurer le bloc data pour que l'utilisateur choisisse les Slide à chaque fois qu'il l'utilise comme en-tête.

Concrètement, les blocs data et config servent à indiquer a OverCms ce que l'utilisateur doit remplir. Voici comment les champs sont définis:

  "data": {
    "<nom du champ>": {
      "title": "<nom d'affichage>",
      "type": "<type de champ>",
      "required": "<champ requis ? true/false>",
      "required_icon": "<champ requis ? true/false, si true, affiche une icone>",
      "default": "<valeur par défaut>",
      "tooltip": "<indication si on survole le titre>",
      "placeholder": "<indication dans le champ>",
      "pattern": "<regex de validation>",
      "pattern_info": "<message en cas d'erreur du pattern>",
      "choices": "<liste des choix pour les type radio, checkbox, select>"
    }
  }

Pour notre plugin Slider, nous allons demander à l'utilisateur de remplir 2 champs: le titre et l'image de fond.

  "data": {
    "title": {
      "title": "SLIDER.TITLE",
      "type": "input"
    },
    "picture": {
      "title": "SLIDER.URL_PICTURE",
      "type": "input"
    }
  }

Les titres SLIDER.TITLE et SLIDER.URL_PICTURE correspondent aux tags de traductions, nous y revenons plus tard. Avec cette configuration, l'utilisateur verra ceci:

Bien ! Maintenant, on peut utiliser tooltip et placeholder pour donner des indications à l'utilisateurs. Essayons ceci:

  "data": {
    "title": {
      "title": "SLIDER.TITLE",
      "type": "input",
      "placeholder": "SLIDER.TITLE_PLACEHOLDER"
    },
    "picture": {
      "title": "SLIDER.URL_PICTURE",
      "type": "input",
      "tooltip": "SLIDER.URL_PICTURE_TOOLTIP"
    }
  }

Avec les traductions suivantes: SLIDER.TITLE_PLACEHOLDER = Titre du slide, et SLIDER.URL_PICTURE_TOOLTIP = Lien vers l'image, on obtient ceci:

Le tooltip est affichée que si on survole le titre.

Un premier problème se pose: comment faire pour que l'utilisateur entre plusieurs slide ? Et bien tout est prévu avec le type group. En effet ce type de champ permet de faire un groupe d'autre champ:

  "data": {
    "slide": {
      "type": "group",
      "max": 10,
      "title": "SLIDE_NUMBER",
      "form": {
        -- autres champs -- 
      }
    }
  }

Dans le titre, %number% est remplacé par le numéro du groupe. Dans l'exemple, la traduction de SLIDE_NUMBER sera Slide #%number%. Dans form, il suffit de mettre les champs précédents. Ce qui nous donne:

  "data": {
    "slide": {
      "type": "group",
      "max": 10,
      "title": "SLIDE_NUMBER",
      "form": {
        "title": {
          "title": "SLIDER.TITLE",
          "type": "input",
          "placeholder": "SLIDER.TITLE_PLACEHOLDER"
        },
        "picture": {
          "title": "SLIDER.URL_PICTURE",
          "type": "input",
          "tooltip": "SLIDER.URL_PICTURE_TOOLTIP"
        }
      }
    }
  }

Ce code permet à l'utilisateur de rentrer un maximum de 10 slides, comme ceci:

Le tutoriel est fini, cependant il y a beaucoup de types différents, qui sont tous plus bas sur cette page.

Page suivante: Traductions

Types

Ordinaire:

input: affiche un simple champ (une ligne de texte) - Exemple
text: affiche un champ étendu (plusieurs lignes possible) - Exemple
bbcode: un éditeur de texte BBCode - Exemple
checkbox: cases à cocher - Exemple
radio: une option à sélectionner - Exemple
select: une option à sélectionner - Exemple

Présentation:

divider: affiche une barre de séparation (<hr>)
space: affiche un espace vertical

Spécial:

group: un groupe de plusieurs configurations - Exemple
label: simplement du texte affiché (un titre, une consigne, ..)
html: du code html qui sera directement inclus. Par exemple pour un sélecteur de couleur.
free: du code html, sans le titre habituel. Par exemple pour insérer un code javascript.

Pour html et free, utilisez un script au lieu d'insérer le code directement. Par exemple:

    "colorpicker": {
      "type": "free",
      "content": "<script src=\"{HTTP_SITE_ROOT}plugin/Slider/admin/colorpicker.js\"></script>"
    }

Dans le panel admin ROOT correspond à site.fr/admin/. Il faut donc utiliser HTTP_SITE_ROOT pour obtenir la racine du site sans le /admin/.

Exemples

Les tags de traductions sont remplacés par les traductions directement.

{
  "plugin": {
    "name": "Nom du plugin",
    "type": "custom",
    "version": "1.0.0",
    "require": {
      "cms": "1.0.0"
    }
  },
  "lang": {
    "translation": true,
    "default_language": "en"
  },
  "config": {
    "slides": {
      "type": "group",
      "max": 10,
      "title": "Slide n°%number%",
      "form": {
        "name": {
          "type": "input",
          "title": "Titre du slide",
          "placeholder": "Le texte qui sera affichée sur le slide",
          "required_icon": true
        }
      }
    },
    "site": {
      "type": "input",
      "title": "Votre site",
      "required": true,
      "placeholder": "http://"
    },
    "services": {
      "type": "checkbox",
      "title": "Services",
      "tooltip": "Choisissez les services",
      "choices": {
        "sav": "Service Après Vente",
        "warranty": "Garantie livraison",
        "free": "Frais de port gratuits",
        "fast": "Livraison rapide"
      },
      "default": [
        "sav",
        "free"
      ]
    },
    "display": {
      "type": "radio",
      "title": "Afficher",
      "choices": {
        "true": "Oui",
        "false": "Non"
      },
      "default": "false"
    },
    "greetings": {
      "title": "Message de bienvenue",
      "type": "text",
      "required": true
    },
    "description": {
      "title": "Description",
      "type": "bbcode",
      "placeholder": "Décrivez votre activité"
    },
    "version": {
      "title": "Couleur",
      "type": "select",
      "choices": {
        "red": "Rouge",
        "blue": "Bleu",
        "green": "Green",
        "orange": "Orange",
        "yellow": "Yellow",
        "white": "White"
      },
      "required_icon": true
    },
    "break1": "divider",
    "break2": "space",
    "info": {
      "type": "label",
      "content": "Pensez à remplir tous les champs"
    },
    "titre": {
      "type": "html",
      "content": "<h1>Informations</h1>"
    },
    "script": {
      "type": "free",
      "content": "<script src=\"{HTTP_SITE_ROOT}plugin/Slider/admin/colorpicker.js\"></script>"
    }
  }
}