Ticket #340: pagelinks-doc.txt

File pagelinks-doc.txt, 6.2 kB (added by xian, 1 year ago)

Documentation d'utilisation

Line 
1 Lorsque que l'on doit afficher une liste de résultats à l'écran et que cette liste est longue, il peut être judicieux de la répartir sur plusieurs pages. Le plugin Pagelinks facilite l'affichage d'un tel système de pagination, avec des liens pointant vers les différentes pages de résultats.
2
3
4 == APPEL DU PLUGIN DANS UN TEMPLATE ==
5
6 Pour utiliser le plugin avec les comportements par défaut, il suffit d'utiliser la syntaxe suivante.
7
8  {pagelinks module~action, paramètres de l'action,  nombre total de résultats, résultat courant, nombre de résultat par page, nom du paramètre d'offset, propriétés d'affichage}
9
10 Exemple :
11
12  <p>{pagelinks 'myModule~default_index', array(),  283, 60, 15, "offset"}</p>
13
14 == PARAMETRES ==
15
16 ** Module~Action **
17
18 Sélecteur de l'action qui doit être appelé par les liens de pages
19
20 **Paramètres de l'action** :
21
22 Tableau contenant les paramètres métiers à placer dans l'url des liens de pages.
23
24  <p>{pagelinks 'myModule~default_index', **array("param1" => 1, "param2" => "deux")**,  283, 60, 15, "offset"}</p>
25
26 Si il n'y aucun paramètre à passer, on utilise un tableau vide :
27
28  <p>{pagelinks 'myModule~default_index', **array()**,  283, 60, 15, "offset"}</p>
29
30 ** Nombre total de résultats **
31
32 Nombre entier représentant le nombre total des résultats répondant à votre requête. Vous devez donc l'avoir calculé au préalable.
33
34  <p>{pagelinks 'myModule~default_index', array(),  **283**, 60, 15, "offset"}</p>
35
36 ** Résultat courant **
37
38 Nombre entier représentant l'offset, c'est à dire l'index du résultat courant. Dans l'exemple suivant, on indique que la page courante est celle qui contient le 60ème résultat disponible.
39
40  <p>{pagelinks 'myModule~default_index', array(),  283, **60**, 15, "offset"}</p>
41
42 ** Nombre de résultats par page **
43
44 Nombre entier représentant le nombre de résultats contenus dans une page. Dans l'exemple suivant, on indique que chaque page contient 15 résultats.
45
46  <p>{pagelinks 'myModule~default_index', array(),  283, 60, **15**, "offset"}</p>
47
48 ** Nom du paramètre d'offset **
49
50 Chaine de caractère contenant le nom que doit prendre le paramètre correspondant à l'offset dans l'url des liens de pages. Dans l'exemple suivant, le paramètre s'appelle "offset".
51
52  <p>{pagelinks 'myModule~default_index', array(),  283, 60, 15, **"offset"**}</p>
53
54 ** Propriétés d'affichage **
55
56 Tableau contenant les paramètres liés à l'affichage du plugin. Ce paramètre est optionnel. S'il est omis, le plugin utilise le comportement par défaut, à savoir qu'il affiche l'intégralité des liens avec leur intitulé par défaut.
57
58 Il est donc possible de personnaliser l'affichage, en définissant le nombre de liens à afficher ainsi que les intitulés des liens spéciaux (page suivante, page précédente, etc.). Pour cela on ajoute simplement un tableau de paramètres supplémentaires comme ci-dessous dans l'appel.
59
60  <p>{pagelinks 'myModule~default_index', array(),  283, 60, 15, "offset", **array('start-label' => 'début', 'end-label' => 'fin', 'prev-label'  => 'précédent', 'next-label'  => 'suivant', 'area-size'  => 5)**}</p>
61
62 Il est ainsi possible de renseigner une ou plusieurs des valeurs d'index suivantes qui viendront écraser le comportement défini par défaut.
63
64 * 'start-label' : Libellé du lien de la première page de résultats disponible. Si la valeur est une chaine vide, le lien ne sera pas affiché.
65
66 * 'prev-label' : Libellé du lien de la page de résultats précédente. Si la valeur est une chaine vide, le lien ne sera pas affiché.
67  
68 * 'next-label' : Libellé du lien de la page de résultats suivante. Si la valeur est une chaine vide, le lien ne sera pas affiché.
69
70 * 'end-label' : Libellé du lien de la dernière page de résultats disponible. Si la valeur est une chaine vide, le lien ne sera pas affiché.
71
72 * 'area-size' : Nombre de liens à afficher avant et après la page courante. Si la valeur est 0, tous les liens seront affiché.
73
74 L'exemple suivant renomme les liens "précédent" et "suivant", et masque les liens de début et de fin. De plus un maximum de 5 pages sera affiché de part et d'autre de la page courante.
75
76  <p>{pagelinks 'myModule~default_index', array(),  283, 60, 15, "offset", **array('start-label' => '', 'end-label' => '', 'prev-label'  => 'précédent', 'next-label'  => 'suivant', 'area-size'  => 5)**}</p>
77
78 L'exemple suivant renomme les liens "précédent" et "suivant", et utilise le libellé par défaut pour les liens de début et de fin. De plus l'intégralité des liens sera affichée.
79
80  <p>{pagelinks 'myModule~default_index', array(),  283, 60, 15, "offset", **array('prev-label'  => 'précédent', 'next-label'  => 'suivant')**}</p>
81  
82 Bien entendu, il est aussi possible de possible d'utiliser un tableau de paramètres déclaré dans le controlleur.
83
84  $properties = array('start-label' => '',
85                              'prev-label'  => 'précédent',
86                          'next-label'  => 'suivant',
87                                      'end-label'   => '',
88                              'area-size'  => 5);
89  
90  $rep->body->assign('properties',$properties);
91
92 L'appel du template aura donc la forme suivante.
93
94  <p>{pagelinks 'myModule~default_index', array(),  283, 80, 15, "offset", **$properties**}</p>
95
96
97 == LOCALISATION DES INTITULES ==
98
99 Il est possible de localiser les intitulés des liens spéciaux en utilisant jLocale de la façon suivante.
100
101  $properties = array('start-label' => jLocale::get("bar~foo.pagelinks.start"),
102                              'prev-label'  => jLocale::get("bar~foo.pagelinks.prev"),
103                          'next-label'  => jLocale::get("bar~foo.pagelinks.next"),
104                                      'end-label'   => jLocale::get("bar~foo.pagelinks.end"),
105                              'area-size'  => 0);
106
107
108 == MISE EN FORME AVEC CSS ==
109
110 Le plugin Pagelinks met à disposition les classes CSS suivantes pour permettre de styler les liens de pagination comme désiré.
111
112  ul.pagelinks
113  li.pagelinks-start
114  li.pagelinks-prev
115  li.pagelinks-current
116  li.pagelinks-next
117  li.pagelinks-end
118
119 Exemple de feuille de style minimaliste pour une utilisation de Pagelinks avec les propriétés d'affichage par défaut.
120
121  ul.pagelinks>li {
122         display: inline;
123  }
124
125  ul.pagelinks>li:before {
126         content: ' | ';
127  }
128
129  ul.pagelinks>li.pagelinks-start:before {
130         content: '';
131  }
Download in other formats: Original Format