Création et utilisation de contrôleurs personnalisés

Objectifs de formation

Une fois cette unité terminée, vous pourrez :

Présenter un contrôleur personnalisé et ses principaux attributs
Créer une classe de contrôleur personnalisé
Utiliser un contrôleur personnalisé dans une page Visualforce

Remarque

Vous souhaitez apprendre en français ? Dans ce badge, les validations de défi pratique Trailhead se font en anglais. Les traductions sont fournies entre parenthèses à titre de référence. Veillez à copier/coller les valeurs en anglais, puis à définir la langue de votre Trailhead Playground sur Anglais et les paramètres régionaux sur États-Unis. Suivez les instructions ici.

Consultez le badge Trailhead dans votre langue pour découvrir comment profiter de l’expérience Trailhead traduite.

Présentation des contrôleurs personnalisés

Les contrôleurs personnalisés contiennent une logique et une manipulation de données personnalisées qui peuvent être utilisées par une page Visualforce. Par exemple, un contrôleur personnalisé peut récupérer une liste d’éléments à afficher, émettre un appel externe vers un service Web externe, valider et insérer des données, entre autres, et toutes ces opérations sont disponibles dans la page Visualforce qui les utilisent en tant que contrôleurs.

Nous avons déjà présenté comment Visualforce prend en charge le modèle de conception Modèle-Vue-Contrôleur (MVC) pour l’élaboration d’applications Web. Généralement, les contrôleurs récupèrent les données à afficher dans une page Visualforce et incluent le code qui est exécuté en réponse à des actions sur la page, par exemple un clic sur un bouton. Lorsque vous utilisez le contrôleur standard, la plupart des fonctionnalités dites « standard » sont fournies par la plate-forme.

Il est toutefois difficile de généraliser, car les applications Web ne sont pas toutes standard. Par conséquent, lorsque vous souhaitez remplacer une fonctionnalité existante, personnaliser la navigation via une application, utiliser des appels externes ou des services Web, ou renforcer le contrôle de l’accès aux informations de votre page, Visualforce vous laisse prendre le contrôle. Vous pouvez écrire un contrôleur personnalisé avec le langage Apex et contrôler entièrement la logique de votre application.

Création d’une page Visualforce qui utilise un contrôleur personnalisé

Ajoutez un contrôleur personnalisé à une page Visualforce en référençant le nom de la classe du contrôleur dans l’attribut <apex:page> controller.

Lorsque votre page utilise un contrôleur personnalisé, vous ne pouvez pas utiliser un contrôleur standard. Les pages utilisent un autre attribut pour définir le contrôleur personnalisé.

Ouvrez la Developer Console, puis cliquez sur File (Fichier) | New (Nouveau) | Visualforce Page (Page Visualforce) pour créer une page Visualforce. Saisissez ContactsListWithController comme nom de page.

Dans l'éditeur, remplacez le balisage par :

<apex:page controller="ContactsListWithController">
    <apex:form>
        <apex:pageBlock title="Contacts List" id="contacts_list">
            <!-- Contacts List goes here -->
        </apex:pageBlock>
    </apex:form>
</apex:page>

Lorsque vous essayez d’enregistrer cette page, vous obtenez une erreur, car ContactsListWithController n’existe pas encore. Nous vous inquiétez pas, nous allons corriger cette erreur.

Création d'une classe Apex de contrôleur personnalisé

Un contrôleur personnalisé est une simple classe Apex que vous écrivez en utilisant la Developer Console.

Il existe de nombreuses classes système et utilitaires qui peuvent vous aider à écrire une logique de contrôleur personnalisé. L'existence de la classe est la seule condition requise pour pouvoir l'utiliser en tant que contrôleur personnalisé.

Ouvrez la Developer Console, puis cliquez sur File (Fichier) | New (Nouveau) | Apex Class (Classe Apex) pour créer une classe Apex. Saisissez le nom de classe ContactsListWithController.

Dans l'éditeur, remplacez le code existant par :

public class ContactsListWithController {
// Controller code goes here
}

Comme avec les pages Visualforce, vous devez enregistrer les modifications apportées à Apex. Une petite opération sans incidence, mais qui permet d’éliminer l’erreur de la page Visualforce. Par conséquent...

Revenez à la page Visualforce et enregistrez-la de nouveau. Le message d'erreur n'est plus affiché et la page est enregistrée avec succès.
Cliquez sur Preview (Aperçu) pour prévisualiser la page à mesure que vous la modifiez. Une nouvelle fenêtre s’ouvre avec l’en-tête de page et les éléments du menu latéral standard de Salesforce, mais sans contenu.

À première vue, les deux éléments que vous avez créés ne semblent pas très intéressants. Bien qu’il existe 90 % de code d’espace réservé, les deux éléments (page Visualforce et contrôleur Apex) sont liés. Dès que vous ajoutez un code au contrôleur, votre page peut l'utiliser.

Au-delà des concepts de base

Vous avez peut-être remarqué que cette classe de contrôleur personnalisé n’hérite d’aucune autre classe et ne met en œuvre aucune interface pour respecter les conditions requises d’un contrôleur Visualforce. Les contrôleurs plus complexes sont dans le même cas, car il n'existe aucun type de classe à hériter ni d'interface à mettre en oeuvre. Par conséquent, vous pouvez créer librement vos propres classes et interfaces en apprenant à maîtriser le langage Apex.

Ajout d'une méthode pour récupérer des enregistrements

Créez une méthode d'obtention qui exécute une requête SOQL afin de renvoyer les enregistrements à afficher dans votre page.

L'objet principal de la plupart des contrôleurs est de récupérer des données à afficher ou de gérer des mises à jour de données. Dans ce simple contrôleur, il suffit d’exécuter une requête SOQL de base qui récupère des enregistrements de contact et les rend disponibles dans la page Visualforce.

Dans la classe ContactsListWithController, remplacez la ligne de commentaire // Controller code goes here par le code ci-dessous.
```
private String sortOrder = 'LastName';
public List<Contact> getContacts() {
    List<Contact> results = Database.query(
        'SELECT Id, FirstName, LastName, Title, Email ' +
        'FROM Contact ' +
        'ORDER BY ' + sortOrder + ' ASC ' +
        'LIMIT 10'
    );
    return results;
}
```
Ce code ajoute une variable membre privée, une chaîne nommée sortOrder, ainsi qu’une méthode publique, getContacts(). sortOrder est très facile à comprendre. Il correspond au nom du champ de tri des contacts. getContacts() est aussi relativement simple, bien que difficile à analyser de prime abord si vous ne l’avez jamais vu dans Apex. Cette méthode sert à exécuter une requête SOQL qui récupère une liste d'enregistrements de contacts pour la renvoyer à l'appelant de la méthode. Qui est l'appelant ? La page Visualforce bien entendu !

Dans la page ContactsListWithController, remplacez la ligne de commentaire  par le balisage ci-dessous.

<!-- Contacts List -->
<apex:pageBlockTable value="{! contacts }" var="ct">
    <apex:column value="{! ct.FirstName }"/>
    <apex:column value="{! ct.LastName }"/>
    <apex:column value="{! ct.Title }"/>
    <apex:column value="{! ct.Email }"/>
</apex:pageBlockTable>

Lorsque vous enregistrez cette page, vous devriez voir apparaître un tableau d’apparence familière qui présente des coordonnées. Une liste de contacts sauvegardée par un contrôleur personnalisé

Une liste de contacts sauvegardée par un contrôleur personnalisé

Le balisage de la page ContactsListWithController est relativement familier. À l’exception de l’attribut controller de la balise <apex:page>, ce code est identique à celui utilisé pour créer la page avec le contrôleur standard.

La différence réside dans l’évaluation de l’expression {!contacts }. Sur cette page, Visualforce traduit cette expression dans un appel à la méthode getContacts() de votre contrôleur. Cette méthode renvoie une liste d’enregistrements de contacts, que le composant <apex:pageBlockTable> attend.

La méthode getContacts() est une méthode d’obtention. C’est un modèle général, où {!someExpression } dans votre balisage Visualforce se connecte automatiquement à une méthode appelée getSomeExpression() dans votre contrôleur. Cette méthode est la plus simple pour permettre à votre page d'accéder aux données à afficher.

Ajout d'une nouvelle méthode d'action

Créez des méthodes d'action dans votre contrôleur personnalisé afin de répondre à une entrée utilisateur sur la page.

L'affichage des données est important, mais la possibilité de répondre aux actions des utilisateurs est essentielle pour toute application Web. À l’aide d’un contrôleur personnalisé, vous pouvez créer toutes les actions personnalisées que vous souhaitez prendre en charge dans une page, en écrivant des méthodes d’action pour répondre à l’activité des utilisateurs.

Dans la classe ContactsListWithController, sous la méthode getContacts(), ajoutez les deux méthodes ci-dessous.
```
public void sortByLastName() {
    this.sortOrder = 'LastName';
}
public void sortByFirstName() {
    this.sortOrder = 'FirstName';
}
```
Ces deux méthodes modifient la valeur de la variable privée sortOrder. sortOrder est utilisé dans la requête SOQL qui récupère les contacts. Une modification de sortOrder change l’ordre des résultats.

Dans la page ContactsListWithController, remplacez les deux balises <apex:column> de ct.FirstName et ct.LastName par le balisage ci-dessous.

<apex:column value="{! ct.FirstName }">
    <apex:facet name="header">
        <apex:commandLink action="{! sortByFirstName }"
            reRender="contacts_list">First Name
        </apex:commandLink>
    </apex:facet>
</apex:column>
<apex:column value="{! ct.LastName }">
    <apex:facet name="header">
        <apex:commandLink action="{! sortByLastName }"
            reRender="contacts_list">Last Name
        </apex:commandLink>
    </apex:facet>
</apex:column>

La présentation semble inchangée, mais lorsque vous cliquez sur les en-têtes des colonnes Prénom et Nom, l'ordre de tri de la liste de contacts change. Très bien !

Le nouveau balisage ajoute deux composants imbriqués à chaque composant <apex:column>. <apex:column> contient un en-tête de texte brut, mais nous voulons pouvoir cliquer sur l’en-tête. <apex:facet> permet de définir le contenu de l’en-tête de la colonne. Nous souhaitons définir un lien qui appelle la méthode d'action appropriée. Le lien est créé en utilisant le composant <apex:commandLink>, avec l’attribut action défini sur une expression qui référence la méthode d’action dans notre contrôleur (notez que contrairement aux méthodes d'obtention, les méthodes d'action portent le même nom que l'expression qui les référence).

Une fois cliqué, le lien déclenche la méthode d'action dans le contrôleur. La méthode d'action modifie la variable privée de l'ordre de tri, puis le tableau est restitué. Lorsque le tableau est affiché, {!contacts } est réévalué, ce qui réexécute la requête avec l’ordre de tri défini, quel qu’il soit. Le tableau est ainsi trié dans l'ordre demandé par le clic de l'utilisateur.

Au-delà des concepts de base

Le texte de l'en-tête des colonnes de prénom et de nom est codé en dur dans ce balisage. Que ce passe-t-il lorsque les utilisateurs ne maîtrisent pas l'anglais ? L'interface utilisateur standard de Salesforce propose des noms de champ traduits pour tous les objets standard. Vous pouvez également saisir vos propres traductions pour les objets personnalisés. Comment pouvez-vous accéder aux traductions ? Au lieu du texte brut, essayez le balisage suivant : <apex:outputText value="{!$ObjectType.Contact.Fields.FirstName.Label }"/>. Cette méthode de référencement de l'étiquette d'un champ est la plus efficace, car même si votre organisation utilise partout la même langue, le nom du champ est automatiquement mis à jour lorsque vous le modifiez.

En savoir plus...

Avec les contrôleurs personnalisés et le langage Apex, vous pouvez laisser libre cours à votre imagination dans vos pages Visualforce.

Les méthodes d'obtention extraient les données de votre contrôleur vers votre page. Des méthodes de définition existent, qui permettent de soumettre des valeurs depuis la page vers votre contrôleur. De la même façon que les méthodes d'obtention, vous ajoutez le préfixe « set » à vos méthodes de définition. Ces méthodes contiennent un argument.

L’utilisation de propriétés Apex constitue une alternative aux méthodes d’obtention et de définition. Les propriétés correspondent à une combinaison entre une variable et des méthodes d'obtention et de définition, avec une syntaxe qui les assemble de façon explicite. Une simple propriété qui référence un objet personnalisé peut être déclarée comme suit :

public MyObject__c myVariable { get; set; }

Les propriétés peuvent être publiques ou privées, et en lecture seule ou même en écriture seule, en omettant get ou set (l'obtention ou la définition). Vous pouvez également créer des mises en oeuvre de méthodes d'obtention ou de définition afin d'exécuter une logique qui s'ajoute aux simples opérations d'enregistrement et de récupération d'une valeur.

Les propriétés correspondent à une fonctionnalité générale d’Apex, elles ne sont pas spécifiques à Visualforce. Apex est un langage de programmation complet. Il convient non seulement à la conception des pages Visualforce complexes, mais il est également utilisé dans de nombreux contextes de développement de la plate-forme Lightning. Pour connaître les nombreuses façons de l'utiliser le langage Apex, consultez les autres rubriques Apex disponibles dans cette documentation et les ressources référencées à la fin de cette page.

Initialement, le cycle de vie d’une requête et d’une réponse Visualforce peut sembler complexe. Il est notamment important de comprendre qu'il n'existe aucun ordre spécifique pour appeler des méthodes d'obtention ou de définition (ou les propriétés qui les utilisent). Par conséquent, ne définissez aucune dépendance à un ordre d'exécution entre ces méthodes. D’autres informations plus complètes sont disponibles dans les sections correspondantes du guide du développeur Visualforce, notamment au sein du chapitre Contrôleurs personnalisés et extensions de contrôleur.

Ressources