Joomla! Documentation™

Warning!

Het sql formulierveld type biedt een drop-down lijst met alle items uit de uitvoer van een query op de Joomla database. Indien het veld een opgeslagen waarde heeft, wordt deze geselecteerd als de pagina voor het eerst geladen wordt. Indien niet, wordt de standaard waarde (als die er is) geselecteerd.

• type (verplicht) moet sql zijn.
• name (verplicht) is de unieke naam van het veld. Dit moet overeenkomen met de naam van de kolom uit het resultaat van de query die de waarden bevat die getoond worden aan de gebruikers in de drop-down lijst, tenzij een andere naam is opgegeven in het value_field attribuut.
• label (verplicht) (vertaalbaar) is de beschrijvende titel van het veld.
• query (verplicht als u de sql_* attributen niet gebruikt) is de SQL query die de gegevens levert voor de drop-down lijst. De query moet twee kolommen teruggeven; één genaamd 'value' (tenzij overschreven door het key_field attribuut) die de waarde van de items bevat; de andere die hetzelfde heet als de waarde van het 'name' attribuut (tenzij overschreven door het value_field attribuut) die de tekst bevat die getoond moet worden in de drop-down lijst.
• default (optioneel) is de standaard waarde. Dit is de waarde van de 'value' kolom, tenzij overschreven door het key_field attribuut.
• description (optioneel) (vertaalbaar) is tekst die getoond wordt als tooltip als de gebruiker de muis beweegt over de drop-down box.
• multiple (optional) turns the field into a multi-selector. Use multiple="multiple".
• key_field (optioneel) is de naam van de kolom die waarden bevat voor de parameter. Indien weggelaten zal de kolom genaamd 'value' gebruikt worden, indien die bestaat.
• value_field (optioneel) is de naam van de kolom die de waarden bevat die getoond wordt aan de gebruikers in de drop-down lijst. Indien weggelaten zal de kolom met dezelfde naam als het naamattribuut gebruikt worden, als die bestaat.
• translate (optioneel) zal de uitvoer van het value_field vertalen indien op 'true'. Het staat standaard op '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.

Voorbeeld XML-parameter definitie:

<field
    name="title"
    type="sql"
    default="10"
    label="Select an article"
    query="SELECT id AS value, title AS text FROM #__content"
    />

Let op dat een AS clausule gebruikt is in dit voorbeeld, omdat de jos_content tabel geen kolom heeft genaamd 'value'. In feite hebben zeer weinig tabellen in de Joomla database een kolom genaamd 'value'. Als alternatief kunt u een key_field attribuut gebruiken om de kolom te definiëren die gebruikt moet worden in plaats van 'value':

<field
    name="title"
    type="sql"
    default="10"
    label="Select an article"
    query="SELECT id, title FROM #__content"
    key_field="id"
    />

Dit geeft het gelijke resultaat als het vorige voorbeeld.

Beide kolomnamen moet moeten misschien een alias krijgen. Stel bijvoorbeeld dat u uw veld genoemd wil hebben 'myfield' in plaats van 'title' in het voorgaande voorbeeld. Dan kunt u dit doen:

<field
    name="myfield"
    type="sql"
    default="10"
    label="Select an article"
    query="SELECT id AS value, title AS myfield FROM #__content"
    />

Of als alternatief:

<field
    name="myfield"
    type="sql"
    default="10"
    label="Select an article"
    query="SELECT id, title FROM #__content"
    key_field="id"
    value_field="title"
    />

U kunt velden ook samenstellen of berekenen in het SQL statement. Stel bijvoorbeeld dat u in de lijst de aanmaakdatum/tijd van elk artikel wilt koppelen aan de titel van het artikel. Dan kunt u het SQL statement gebruiken:

SELECT id, concat( title, ' (', created, ')') AS title FROM #__content

U kunt ook een statische optie in de XML specificeren met behulp van de <option></option> tag. Kijk alstublieft naar het volgende voorbeeld.

<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" 
    />

Warning!

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

Let op: De SQL statements moeten juist zijn voor het type en versie van de onderliggende database waar Joomla op draait. Dit is waarschijnlijk een versie van MySQL, maar het kan iets anders zijn. Er is geen mogelijkheid een database te benaderen anders dan die waar Joomla zelf op draait.

Let op: Zoals in deze voorbeelden getoond, het database voorvoegsel (vaak jos) moet in het vorm #__ (hash-underscore-underscore) gegeven worden. Het zal automatisch vervangen worden door het echte database voorvoegsel gebruikt door Joomla.

Zie ook

• Lijst met standaard formulierveld types