Type de champ de formulaire SQL
From Joomla! Documentation
L'utilisation de ce type de champ de formulaire générique vous oblige à écrire du SQL dans un fichier XML. Pour plus de flexibilité, vous devez envisager de créer votre propre type de champ de formulaire en dépendance de la classe JFormField.
Le type de champ de formulaire sql fournit une liste déroulante d'entrées récupérées par au cours d'une requête dans la base de données Joomla. Si le champ a une valeur enregistrée, cette option est sélectionnée lors du premier chargement de la page. Sinon, la valeur par défaut (le cas échéant) est sélectionnée.
- type (obligatoire) doit être "sql".
- name (nom) (obligatoire) est le nom unique du champ. Il doit correspondre au nom de la colonne des résultats de requêtes qui contient les valeurs qui seront affichées à l'utilisateur dans la liste déroulante, à moins qu'un nom différent soit spécifié par l’attribut value_field.
- label (étiquette) (obligatoire) (traduisible) est le titre descriptif du champ.
- query (requête) (obligatoire si les attributs sql_* ne sont pas utilisés) est la requête SQL qui va fournir les données de la liste déroulante. La requête doit retourner deux colonnes : une appelée 'value' (à moins d'une surcharge par l'attribut key_field) qui va contenir les valeurs des éléments de la liste ; l'autre appelée de la même façon que la valeur du nom de l'attribut (à moins d'une surcharge par l'attribut value_field) contenant le texte à afficher dans la liste déroulante.
- default (par défaut) (facultatif) est la valeur par défaut. C'est la valeur du champ 'value', à moins d'être substituée par l'attribut key_field.
- description (facultatif) (traduisible) est le texte qui s'affichera dans une info-bulle lorsque l'utilisateur passe sa souris sur la liste déroulante.
- multiple (optional) turns the field into a multi-selector. Use multiple="multiple".
- key_field (facultatif) est le nom de la colonne qui contient les valeurs pour le paramètre. Si omis, alors la colonne appelée 'value'sera utilisée si elle existe.
- value_field (facultatif) est le nom de la colonne qui contient les valeurs à afficher à l'utilisateur dans la liste déroulante. Si omis, alors la colonne avec le même nom que le nom de l'attribut sera utilisée si elle existe.
- translate (traduction) (facultatif) permet de traduire la sortie de value_field si défini sur 'true'. La valeur par défaut est 'false'.
- header (optional) (translatable) will add an entry, with an empty value, at the top of the list of options. This is usually used to add a "- Select something -" entry to the list. See the examples for an alternative way of achieving this.
- sql_select (mandatory if not using the query attribute) is the SELECT clause of the SQL statement. Only one such clause is permitted.
- sql_from (mandatory if not using the query attribute) is the FROM clause of the SQL statement.
- sql_join (optional) is the LEFT JOIN clause of the SQL statement. Only one such clause is permitted.
- sql_where (optional) is the WHERE clause of the SQL statement. Only one such clause is permitted.
- sql_group (optional) is the GROUP BY clause of the SQL statement.
- sql_order (optional) is the ORDER BY clause of the SQL statement.
- sql_filter (optional) filters the list by the value of another field. A field name or a comma-separated list of field names can be given. The field names must correspond to column names in the database table being queried. See the examples for further explanation.
- sql_default_{FIELD_NAME} (optional) is the default value used by the sql_filter attribute when the value of the {FIELD_NAME} filter has not been set. See the examples for further explanation.
Exemple de définition de paramètre de champ XML :
<field
name="title"
type="sql"
default="10"
label="Select an article"
query="SELECT id AS value, title AS text FROM #__content"
/>
Remarquez qu'une clause 'AS' a été utilisée dans cet exemple car la table jos_content n'a pas de colonne appelée 'value'. En fait, très peu de tables dans la base de données Joomla! disposent d'une colonne 'value'. Alternativement, vous pouvez utiliser l'attribut key_field pour définir la colonne pouvant être utilisée à la place de 'value' :
<field
name="title"
type="sql"
default="10"
label="Select an article"
query="SELECT id, title FROM #__content"
key_field="id"
/>
Cela donnera des résultats identiques à l'exemple précédent.
Les deux noms de colonne peuvent avoir besoin d'alias. Par exemple, supposons que vous souhaitez que le nom de votre champ soit '''myfield''' au lieu de '''title''' pour l'exemple précédent. Alors, vous pouvez faire ceci :
<field
name="myfield"
type="sql"
default="10"
label="Select an article"
query="SELECT id AS value, title AS myfield FROM #__content"
/>
Ou alternativement :
<field
name="myfield"
type="sql"
default="10"
label="Select an article"
query="SELECT id, title FROM #__content"
key_field="id"
value_field="title"
/>
Vous pouvez également assembler ou des champs de calculs dans l'instruction SQL. Par exemple, supposons que vous souhaitiez ajouter la date et l'heure de chaque article aux titres des articles dans la liste. Vous pouvez alors utiliser cette instruction SQL :
SELECT id, concat( title, ' (', created, ')') AS title FROM #__content
Vous pouvez également spécifier une option statique dans le fichier XML à l'aide des balises <option></option>. Veuillez regarder l'exemple suivant.
<field
name="myfield"
type="sql"
default="10"
label="Select an article"
query="SELECT id, title FROM #__content"
key_field="id"
value_field="title"
required="true"
>
<option value="">Please select your option</option>
</field>
Alternatively, you can achieve the same result using the header attribute as follows:
<field
name="myfield"
type="sql"
default="10"
label="Select an article"
query="SELECT id, title FROM #__content"
key_field="id"
value_field="title"
required="true"
header="Please select your option"
/>
Alternative query syntax
Starting with Joomla 3.5, an alternative to the query attribute allows some additional features. These features are not available if the query attribute is present. For example, this field definition:
<field
name="example_group"
type="sql"
label="COM_EXAMPLE_GROUP"
query="SELECT e.* FROM #__example AS e GROUP BY name ORDER e.id ASC"
key_field="id"
value_field="name"
/>
can be expressed as:
<field
name="example_group"
type="sql"
label="COM_EXAMPLE_GROUP"
sql_select="e.*"
sql_from="#__example AS e"
sql_group="name"
sql_order="e.id ASC"
key_field="id"
value_field="name"
/>
The following feature linked fields as filters is currently not working! See Github issue 22241
One advantage to using this syntax is that it allows the use of linked fields as filters. For example, suppose you have a form containing two select lists, one called groups and the other called subgroups. The groups field is straightforward:
<field name="groups"
type="sql"
label="COM_EXAMPLE_GROUPS"
sql_select="e.*"
sql_from="#__example_groups AS e"
sql_group="name"
sql_order="e.id ASC"
key_field="id"
value_field="name"
/>
but the subgroups field includes an sql_filter attribute which refers to the groups field by name:
<field name="subgroups"
type="sql"
label="COM_EXAMPLE_SUBGROUPS"
sql_select="e.*"
sql_from="#__example_subgroups AS e"
sql_group="name"
sql_order="e.id ASC"
sql_filter="groups"
key_field="id"
value_field="name"
/>
Then if the groups field has the value 99, the following SQL statement will be executed for the subgroups field:
SELECT e.* FROM jos_example_subgroups AS e WHERE `groups` = 99 GROUP BY `name` ORDER BY e.id ASC
To filter on multiple fields, you can use a comma-separated list of filter names in the sql_filter clause. For example, if there is a filter called groups with the value 99 and a filter called categories with the value 12, then
sql_filter="groups,categories"
will produce the SQL WHERE clause:
WHERE `groups` = 99 AND `categories` = 12
You can also define a default value for any filter that might not have a value when the field is evaluated by adding sql_default_{FIELD_NAME} attributes. For example, suppose that the default value for the groups filter is 0 and the default value for the categories filter is 0, then this definition:
<field name="subgroups"
type="sql"
label="COM_EXAMPLE_SUBGROUPS"
sql_select="e.*"
sql_from="#__example_subgroups AS e"
sql_group="name"
sql_order="e.id ASC"
sql_filter="groups,categories"
sql_default_groups="0"
sql_default_categories="1"
key_field="id"
value_field="name"
/>
will produce this SQL statement when initially evaluated with no filters:
SELECT e.* FROM jos_example_subgroups AS e WHERE `groups` = 0 AND `categories` = 1 GROUP BY `name` ORDER BY e.id ASC
Remarque : les instructions SQL doivent être correctes et adaptées au type de la version de la base de données que Joomla utilise. Ce sera probablement une version de MySQL, mais cela peut être un autre type. Il est impossible d'interroger des bases de données autres que celle que Joomla est en train d'exécuter.
Remarque : comme le montrent ces exemples, le préfixe de base de données (souvent jos
) doit être entré sous la forme #__
(hashtag-underscore-underscore). Il sera alors automatiquement remplacé par le préfixe de base de données utilisé par Joomla.