améliorer la documentation

[pa-de-solminihac]

Notamment les points suivants :

• l'explication sur tout ce que le module CRUD permet de faire est incomplète, et peut être pas à sa place
• expliquer quel est le point d'entrée une fois installé (les URL : /monmodule, /monmodule/create etc.)

Expliquer également comment on personnalise l'affichage :

• en renommant un champ avec

$this->mapFieldName('table.champ', 'Mon <em>beau</em>nom');

• en masquant un champ avec

$this->hideField('table.champ');

• en changeant l'ordre des champs avec

$this->moveField('table.champ', 'table.champ_avant_lequel_insérer');

• en forcant le type d'un champ en surchargeant la fonction override_fields, notamment pour créer des champs d'upload, avec resize et génération de miniatures :

$resize_picture = array(
    'canevaswidth' => 640,
    'canevasheight' => 480,
    'cropwidth' => 640,
    'cropheight' => 480,
    'interieur' => 1
);
$resize_thumbnail = array(
    'canevaswidth' => 192,
    'canevasheight' => 168,
    'cropwidth' => 192,
    'cropheight' => 168,
    'interieur' => 1
);
$parameters = array(
    'max_filesize' => 10000000,
    'dest_dir' => __FILES_ROOT__ . '/files/media',
    'extensions' => array('jpg', 'jpeg', 'gif', 'png'),
    'resize_args' => $resize_picture,
    'thumbnails' => array(),
);
$parameters['thumbnails'][] = array(
    'resize_args' => $resize_thumbnail,
);
$this->overrideField('table.field', array(
    'type' => 'file'
), $parameters);

• en surchargeant les vues utilisées pour générer le HTML d'un champ, dans le fichier view/monmodule/update_fields/custom_table.champ.php :
• en créant des champs custom avec

// un simple champ vide
$this->addField('table.fake_field');
// un champ calculé avec définition SQL
$this->addField('table.calculated_field', null, array(
    'sql_definition' => 'CONCAT(IF(...))'
));

• en masquant des sections avec

$this->hideSection('xlsbutton');

• comment on peut gérer plusieurs tables et leurs relations gràce à l'attribut $this->tables du modèle :
  • inner join
  • left join, group by et tables en lecture seule
• comment on peut utiliser CRUD pour compléter des modules existants (exemple : module users, module push)
• comment on le skin avec le module skinbo sans casser le fonctionnement en AJAX :
  • installer la dépendance skinbo=2
  • ajouter une entrée dans le menu admin en surchargeant view/design/menu_admin.php
  • surcharger la vue de la page index en créant le fichier view/monmodule/index.php :

if (!$request->AJAX) {
    $this->getBlock('design/header-admin', $data, $request);
}
$this->getParentBlock($data, $request);
if (!$request->AJAX) {
    $this->getBlock('design/footer-admin', $data, $request);
}

• comment on protège une page avec des droits (installer la dépendance users=4, surcharger les contrôleurs des pages à protéger en utilisant :

$this->getModel('users')->needPrivilèges('nom_du_privilege');

[pa-de-solminihac]

Il faudra parler aussi des raccourcis :

• need_privileges, hide_sections, rename_fields, override_fields, hide_fields, add_fields, move_fields, voire alter_fields...
• ainsi que de leurs déclinaisons : *_read, *_create_or_update, *_index...

[pa-de-solminihac]

À voir aussi :

• différencier le masquage de champ (avec hideField) et le passage en "hidden" (avec overrideField)
• comment donner une valeur par défaut à un champ avec setDefaultValue (par défaut, seulement si $this->data['formtype'] == 'create'. on peut forcer en passant $params['force_default_value'])
• comment forcer la valeur d'un champ lors de l'enregistrement

[pa-de-solminihac]

À voir aussi :

• comment gérer le nettoyage des champs : surcharger sanitize (ou sanitizeValues dans le modèle). Par défaut on sanitize déjà automatiquement les date/time/datetime, les entiers, les booléens, et on strip_tags tout le reste.
• comment définir des champs comme obligatoires avec setMandatoryField
• comment gérer la validation des champs aussi bien côté client que côté serveur grâce à AJAX, en surchargeant la fonction validate :

public function validate($insecure_values, $insecure_primary_key = null)
{
    $previous_errors = parent::validate($insecure_values, $insecure_primary_key);
    $my_errors = array();
    if ($insecure_values['table-field'] < 5) {
        $my_errors['table-field'] = 'le champ table-field doit être supérieur ou égal à 5';
    }
    return $this->getModel('fonctions')->array_replace_recursive($my_errors, $previous_errors);
}

À détailer pour la gestion d'erreurs avec handle_errors...

[pa-de-solminihac]

À voir aussi :

• comment renommer les valeurs affichées dans un select :

$this->renameOptions(array(
    'table.champ1' => 'Mon champ 1',
    'table.champ2' => 'Mon champ 2',
));

• comment forcer les valeurs affichées dans un select :

$this->setFieldValues(array(
    '1' => 'Nom 1',
    '2' => 'Nom 2',
    '3' => 'Nom 3',
));

Remarque : setFieldValues forcera l'affichage sous forme d'un select. On pourra aussi le passer en bouton radio :

$this->overrideField('table.field', 'radio');

• comment appliquer un traitement au onchange du select : en enregistrant un script dans le footer avec la fonction register_foot du module cssjs

[pa-de-solminihac]

Je viens de publier la version 4.18 de CRUD qui est à jour avec les éléments cités ci-dessus.

Avec aussi :

Evolutions HTML5 :

• prise en charge de davantage des types de champs (principalement HTML5 mais aussi meilleure reconnaissance des champs SQL + mapping "span" pour un simple affichage)
• gestion des champs obligatoires
• validation côté serveur faite en AJAX, activée par défaut, intégrée côté client avec la validation native HTML5 si disponible, avec fallbacks (javascript si dispo, ou html sinon)

Ajout de wrappers pour faciliter l'utilisation générale

• divers setters et getters :
  • setDefaultValue, getFieldValue... sous diverses formes : set_, unset_, versions batch, setAll_, unsetAll_...
  • pour les champs à valeurs fixées type select/radio : getFieldValues, renameOption...
• mise en évidence des hooks depuis lesquels appeler les wrappers, avec MAJ de la documentation (dans leurs docblocks respectifs) :
  • override_fields, alter_values, rename_fields, hide_fields, add_fields, move_fields, hide_sections, need_privileges
• corrections mineures (labels des boutons radio, du texte de l'erreur unknown_element...)

[pa-de-solminihac]

Comment choisir le type de liens générés par défaut (sur le listing par exemple) :

public function alter_values_index($params = null)
{
    $ret = parent::alter_values_index($params);
    $this->setFormLinks('read'); // générer des liens vers les pages crud/read
    return $ret;
}

On peut également surcharger les liens :

• des boutons de toutes les pages avec overrideUrlButton()
• des lignes de la page index avec overrideUrlRow()

[pa-de-solminihac]

Propager des paramètres supplémentaires dans les liens générés par CRUD (pour mieux intégrer CRUD dans un site) :

    // injection systématique (dans tous les liens générés par CRUD) du paramètre 'app' récupéré en GET
    public function set_options($request = null, $params = null)
    {
        $ret = parent::set_options($request, $params);
        $this->setOption('url_parameters', array(
            'app' => $request->get('string', 'app'),
        ));
        return $ret;
    }

[pa-de-solminihac]

Ajouter des classes CSS aux formulaires générés par CRUD (pour skin bootstrap ou autres), par exemple sur les formulaires de création/modification.

• directement depuis le contrôleur :

    public function alter_values_create_or_update($params = null)
    {
        $ret = parent::alter_values_create_or_update($params);
        $this->data['more_classes_delbutton'] = array_merge_recursive($this->data['more_classes_wrap'], array(
            'well'
        ));
        return $ret;
    }

• ou alors dans une surcharge de la vue monmodule/update.php :

$data['more_classes_wrap'] = array_merge_recursive($data['more_classes_wrap'], array(
    'well',
));

Remarque

On peut aussi renommer les boutons de la même manière (button_label_*)

Surcharges possibles

La liste des surcharges possibles dans le fichier crudCrudController.php est :

    public function alter_values_index($params = null)
    {
        // pour injecter des classes CSS supplementaires, compléter ces tableaux dans une surcharge avec array_merge
        $this->data['more_classes_wrap'] = array();
        $this->data['more_classes_table'] = array();
        $this->data['more_classes_xlsbutton'] = array();
        $this->data['more_classes_createbutton'] = array();
        $this->data['button_label_create'] = 'Nouveau';
        $this->data['button_label_xls'] = 'Exporter';
    }

    public function alter_values_create_or_update($params = null)
    {
        $this->data['more_classes_wrap'] = array();
        $this->data['more_classes_form'] = array();
        $this->data['more_classes_field_wrap'] = array();
        $this->data['more_classes_field_key'] = array();
        $this->data['more_classes_field_val'] = array();
        $this->data['more_classes_field_comment'] = array();
        $this->data['more_classes_field_checkbox'] = array();
        $this->data['more_classes_backbutton'] = array();
        $this->data['more_classes_savebutton'] = array();
        $this->data['more_classes_delbutton'] = array();
        $this->data['button_label_back'] = 'Annuler';
        $this->data['button_label_save'] = 'Enregistrer';
        $this->data['button_label_del'] = 'Supprimer';
    }

    public function alter_values_read($params = null)
    {
        $this->data['more_classes_wrap'] = array();
        $this->data['more_classes_field_wrap'] = array();
        $this->data['more_classes_field_key'] = array();
        $this->data['more_classes_field_val'] = array();
        $this->data['more_classes_img'] = array();
    }

[pa-de-solminihac]

Parler des nouveautés de CRUD 5, notamment :

Responsive design

• intégration avec le module BOOTSTRAP3 et responsive design avec BOOTSTRAP3CRUD : module permettant de skinner les formulaires CRUD avec bootstrap / bootstrap-material.
• vue index responsive, CSS en table-layout: fixed (désactivable avec l'option de config [module_crud]table_layout_fixed). Grâce au table-layout: fixed on peut définir précisément en CSS la taille d'une colonne, par exemple :

.clementine_crud-list_table_col_clementine_TABLE-FIELD {
    width: 120px !important
}

Header et footer

• chargement automatique des blocks header et footer s'ils existent (monmodule/header et monmodule/footer du module héritant de CRUD, voire crud/header et crud/footer par défaut).
• header/footer surchargeables par page : module/header-create.php par exemple
• ajout de header,footer,updatebutton aux sections masquables avec hideSection

Personnalisation des formulaires générés

• surcharges facilitées des classes CSS et libellés des boutons avec les fonctions addClass/removeClass (qui manipulent $this->data['more_classes_*'] et $this->data['button_label_*'])
• fonction wrapFields() pour encadrer un (ou une série de) champ(s) avec un block ouvrant et un block fermant

Personnalisation des liens

'url_retour_parameters' dans l'url_retour (par exemple pour récupérer l'id de l'enregistrement qu'on vient de créer)

• passage de paramètres dans toutes les URL générées grâce à setOption('url_parameters', ...)

Mappings

• mapping 'togglebutton' pour une checkbox interprétée spécialement si skin avec le module BOOTSTRAP3MATERIAL
• mapping span pour un simple affichage (avec champ "hidden" correspondant)
• mapping input pour forcer un input type="text"
• gestion des attributs HTML readonly fonctionne sur textarea, input [type=*], date/time, checkbox, togglebutton, radio, et file), disabled, et autofocus, positionnable par le biais de la fonction overrideField qui permet aussi de surcharger toutes les métas
• mapping 'date'/'time'/'datetime', et formats de dates configurables avec [module_crud]default_date_format.
• intégration avec le module BOOTSTRAP3DATETIMEPICKER pour avoir eonasdan-datetimepicker (soit en fallback pour les navigateurs qui ne gèrent pas nativement le champ en HTML5, soit systématiquement si on le configure avec [module_bootstrap3datetimepicker]force_crud_datepicker=1)

Hooks

• hook alter_post pour permettre de modifier/compléter les données postées avant de les sauver
• hooks wrap_fields_* pour centraliser les appels à wrapFields()
• ajout de $request comme premier paramètre dans les hooks add_fields*, override_fields*, move_fields*, rename_fields*, hide_sections*, hide_fields*, alter_values*, wrap_fields*