Contents

Options de recherches
Custom Searches
Références

Options de recherches

CiviCRM offre principalement 4 options pour les recherches avancées :

Advanced Search (Recherche avancée): Formulaire Web capable de fouiller tous les champs des contacts, mais ne permet pas les disjonction (opération OU entre les critères de recherche).
Search Builder (Recherches personalisées): Permet de construire des recherches plus flexibles que la recherche avancée en utilisant une interface Web plutôt inflexible.
Custom Search: API de programmation qui permet d'exposer les paramètres d'une recherche SQL personnalisée par un formulaire Web et d'en personnaliser les résultats de recherche.
Civi Report (Comptes-rendus): Outil pouvant générer des rapports élémentaires en incluant des analyses numériques et graphiques à partir de templates programmable. Les rapports sont une option plus flexible que les recherches, mais il n'est pas possible d'appliquer sur ceux-cis des opérations massives.

Custom Searches

Composition de la requête SQL

Se référer au plus récent diagramme entité-relation pour composer la requête SQL

Données essentielles

...

Données personnalisées

Liste d'options

Les valeurs textuelles (champ label) des options (champ value) d'une liste (identifiée par option_group_id) sont référencées dans le tableau civicrm_option_value. La valeur textuelle d'un préfixe (option_group_id = 6) pour les individus de la base peut donc être récupéré comme suit:

SELECT label AS prefix
FROM civicrm_contact AS contact
LEFT JOIN civicrm_option_value AS options 
  ON ( options.option_group_id = 6 AND options.value = contact.prefix_id )
WHERE contact_type LIKE 'Individual'

$/!\$ Il pourrait cependant être préférable d'utiliser la fonction alterRow du script de recherche pour obtenir l'équivalent textuel d'une valeur numérique.

(Indiquer d'où proviennent les valeurs option_group_id)

Profils personnalisés

Les champs personnalisés sont stockés dans la base sous des tableaux qui portent le nom du profil de données personnalisées correspondant civicrm_value_[Nom du profil de données]_[Identifiant numérique]. Le nom de ces champs est de la forme [Nom du champ]_[Identifiant numérique. Les caractères qui ne sont pas alphanumériques [^a-zA-Z0-9_] sont remplacés par des soulignés. Ils sont liés à l'entité (ex: le contact) qu'ils étendent par le champ entity_id. Pour obtenir les valeurs personnalisées d'un groupe de champs associé à un contact, on peut faire une jointure comme celle-ci:

SELECT a_caracteristiques.revenu_33
FROM civicrm_contact AS contact_a
INNER JOIN civicrm_value_caracteristiques_individu_6 a_caracteristiques 
  ON ( a_caracteristiques.entity_id = contact_a.id )

(Indiquer d'où proviennent les identifiants numériques)

Listes de choix des champs personnalisés

(À déterminer)

Implantation de la recherche

Le canevas template.php illustre les fondements d'une recherche typique.

D'autres canevas peuvent être trouvés dans le répertoire civicrm/CRM/Contact/Form/Search/Custom ainsi que sur le wiki de CiviCRM. Faire attention cependant au numéro de version de l'extension; toutes les recherches contribuées ne sont pas nécessairement compatibles avec la dernière version de CiviCRM!

Les recherches sont encapsulées sous une classe nommée CRM_Contact_Form_Search_Custom_[NomDeLaRecherche].

Construction de la requête SQL

La construction de la requête SQL est décomposée entre les méthodes all() , from() et where().

La méthode all() gère les opérations SELECT, GROUP BY...HAVING, ORDER BY et LIMIT.

function all( $offset = 0, $rowcount = 0, $sort = null, $includeContactIDs = false ) {
    $selectClause = "
      contact_a.id AS contact_id, 
      contact_a.sort_name AS sort_name,
      GROUP_CONCAT(a_phone.phone 
        ORDER BY a_phone.is_primary 
        DESC SEPARATOR '; ') AS phone
    ";

    // Ceci ne marche pas -- $sort n'est jamais vide
    if ( empty( $sort ) ) {
      $sort = "sort_name asc";
    }

    $groupBy = "GROUP BY contact_id, sort_name";

    return $this->sql( $selectClause,
       $offset, $rowcount, $sort,
       $includeContactIDs, $groupBy );
}

La méthode from() définit et les tableaux intérogés, incluant les jointures.

function from( ) {
  return "
    FROM civicrm_contact contact_a
    LEFT JOIN civicrm_phone a_phone ON ( a_phone.contact_id = contact_a.id )
  ";
}

La méthode where() gère les conditions de la requête.

function where( $includeContactIDs = false ) {
  $where  = "
    contact_a.contact_type   = 'Individual'
    AND contact_a.is_deceased = FALSE
    AND contact_a.is_deleted = FALSE
  ";

  $params = array( );

  return $this->whereClause( $where, $params );
}

Voir la section sur le traîtement des paramètres de recherche pour personnaliser la construction de la requête SQL à partir du formulaire.

Affichage des résultats

Les colonnes à retourner sont définies dans le contexte de la méthode __construct().

$this->_columns = array(
  ts('Contact Id')   => 'contact_id'  ,
  ts('Name')         => 'sort_name',
  // Add fields here
);

La méthode alterRow() permet de modifier les colonnes d'une rangée avant l'affichage.

function alterRow( &$row ) {
    // { on assume ici que la méthode __construct() a préalablement défini la propriété _prefixes }
    $row['prefix'] = $this->_prefixes[$row['prefix']];
}

La méthode templateFile() retourne le chemin vers le template smarty à utiliser pour l'affichage.

function templateFile( ) {
    return 'CRM/Contact/Form/Search/Custom.tpl';
}

Création des formulaires de recherche

Le formulaire de recherche est composé au sein de la méthode buildForm() à l'aide de la librairie QuickForm.

L'ordre des éléments de formulaire à présenter est définit comme suit, à la fin du buildForm():

$form->assign( 'elements', array( 'nom', 'langue', 'gender', 'roles', 'handicap' ) );

Les valeurs de défaut des items du formulaire peuvent être précisées à l'aide de la méthode setDefaultValue():

function setDefaultValues( ) {
  return array( 'roles'    => 1 );
}

=== Traîtement des paramètres de recherche ===

Étendre la méthode {{{where()

pour traiter les paramètres de recherche...

(À faire)

$count  = 1;
$clauses = array( );

$value = CRM_Utils_Array::value( 'FORMVALUE', $this->_formValues );
if ($value != '') {
        $params[$count] = array( $value, /* CHOOSE EITHER 'Integer' 'String' ... */ );
        $clauses[] = "TABLE.COLUMN = %{$count}";
        $count++;
}

if ( ! empty( $clauses ) ) {
    $where .= ' AND ' . implode( ' AND ', $clause );
}

Activation d'une recherche

Force brute

Déposer la nouvelle recherche de contact sous le répertoire civicrm/CRM/Contact/Form/Search/Custom

Sous Administrer » Personnaliser » Gestion des recherches personnalisées (ou civicrm/admin/options/custom_search&reset=1&group=custom_search), ajouter une nouvelle recherche nommée CRM_Contact_Form_Search_Custom_[[NomDeLaRecherche]]

$/!\$ Il peut être préférable d'emballer la recherche personnalisée en tant qu'extension CiviCRM.

Dans le repertoire de code custom

Comme ci-dessus mais définir civicrm/admin/setting/path?reset=1, Répertoire PHP personnalisé. Ensuite mettre le fichier dans path_custom/CRM/Contact/Form/Search/Custom (pour une recherche de type contact)

Emballage d'une extension de recherche

Étapes à suivre

Pour emballer une recherche personnalisée sous forme d'extension :

Créer un répertoire sous la forme org.koumbit.civicrm.id (id doit être unique pour chaque recherche)
Déplacer le script de recherche [NomDeLaRecherche].php dans ce répertoire
Renommer la classe de recherche par CRM_Contact_Form_Search_[Identifiant]_[NomDeLaRecherche] où l'identifiant est de la forme org_koumbit_civicrm_id
Si l'affichage est personnalisé,
- insérer le fichier [NomDuTemplate].tpl dans un répertoire nommé templates
- remplacer le contenu de la méthode templateFile() par return '[NomDuTemplate].tpl';
Produire un fichier info.xml décrivant l'extension (voir plus bas)
Archiver l'extension sous le nom org.koumbit.civicrm.id.zip
Rendre l'archive accessible publiquement, sinon CiviCRM sera incapable de la charger (à confirmer)

Fichier info.xml

Le fichier info.xml doit ressembler à ceci:

<?xml version="1.0" encoding="UTF-8" ?>
 <extension key="org.koumbit.civicrm.id" type="search">
  <callback>NomDeLaRecherche</callback>
  <name>Nom de la recherche </name>
  <description>Description de la recherche</description>
  <url>http://civicrm.koumbit.org/extensions/org.koumbit.civicrm.id.zip</url>
  <license>AGPL</license>
  <maintainer>webdev@koumbit.org</maintainer>
  <releaseDate>2011-04-01</releaseDate>
  <version>1.0</version>
  <compatibility>
   <ver>3.3</ver>
  </compatibility>
  <develStage>alpha<!-- valeurs permises :: ( alpha | beta | stable ) --></develStage>
  <comments>Inscrire tout autre commentaire pertinent.</comments>
</extension>

Pour en savoir plus :

(déterminer le workflow pour stocker une copie de l'extension sur git et pour la rendre disponible publiquement.)

Wiki

Page

User