.. ==================================================
.. FOR YOUR INFORMATION
.. --------------------------------------------------
.. -*- coding: utf-8 -*- with BOM.

.. include:: ../../../Includes.txt

ForeignSingle
^^^^^^^^^^^^^

This is another dropdown form element but hte values originate in another (a foreign) table. Written to the database is not the actual shown value but an ID of it (although you could actually save the originally shown value as well). So what you need to configure is the foreign table (the table where the entries for the dropdown come from) and what field/column to show as well as the one to save to the own original table respectively.

sForeignDatabase
----------------

String. If set and different from the default database in this SQL Frontend, all calls relevant to this foreign key are executed on this foreign database. Keep in mind that the database has to be accessible by the same database user as defined in *dbal*.

sForeignTable
-------------

String. The table to fetch the entries from (within the same database).

sForeignColumn
--------------

String. Column/Field to save into the original/own table.

sForeignColumnShow
------------------

String. The column/field to show to the user.

sForeignTableOrderBy
--------------------

String. The column/field to sort the foreign table by. Define the order in which to display the values to the user. Append an *ASC* (from a to z) or *DESC* (from z to a) to specify the direction.

Example: ::

    name ASC

bForeignHideEmptyEntry
----------------------

Boolean. If true, empty entries (we are talking about sForeignColumn) are not shown at all.

aForeignWhereShow
-----------------

Array with where additions that is applied to the foreign table when loading values for output. Example: ::

    'aForeignWhereShow' => array(
        'pid:24',
        'hidden:0'
    )

**Hint:** You may use the well-known markers (see, for instance, dbal/MySql/sWhereGet) here. Example: ::

    'aForeignWhereShow' => array(
        'pid:###i:GP:id###',
        'hidden:0',
        'email:###s:fe_user:email###'
    )

aForeignWhereForm
-----------------

Array with where additions that is applied to the foreign table when loading values for the **form**. Example is actually the same as aForeignWhereShow except that you might want to add something or leave something out.

The **difference between aForeignWhereShow and aForeignWhereForm** is that the first is applied when loading values for outputs whereas the latter is applied when loading values for the form dropdown. This might come in handy whenever you want to give the user the possibility to select only entries that are x and y but want to display them even if they are now not y anymore. More practical example: Let users only select entries that are not hidden but since you change those settings from time to time you might still want to display entries where the foreign keys are -- in the meantime -- hiden.

bShowEmptyEntry
---------------

Boolean. If set to true (default is false) an empty entry is shown. The empty entry is always shown as empty but the value to save into the database may vary (e.g., empty string, 0, -, etc.). Set the value to something different than an empty string using sEmptyString.

sEmptyString
------------

String, default is a, well, empty string (''). This is the value that is saved into the database if bShowEmptyEntry is set to true and the user selected this very entry.

aMapping
--------

This is a very powerful *array* setting that allows you to translate real database-saved values to nicely formatted outputs (not for the form, though). Now this sounds as if you don't want to do that on your own but for limited amount of options it makes sense to configure that manually.

The only thing you need to do is to configure the value you want to translate (*map*, thus the name) as array key and the output it should become (*be mapped on*) as the configuration value. Pretty easy example: Translate the cars into their logos: ::

    'aMapping' => array(
        '10' => '<img src="fileadmin/img/volvo.png" alt="Volvo" />',
        '11' => '<img src="fileadmin/img/saab.png" alt="Saab" />',
        '20' => '<img src="fileadmin/img/mercedes.png" alt="Mercedes" />',
        '21' => '<img src="fileadmin/img/audi.png" alt="Audi" />'
    )

sWrap
-----

String, just like with other column handlers. However, in foreign handlers you may access other columns from the foreign table as well. Use markers like ###columnname### or ###col-columnname###. Additionally and due to the fact that even ###col-columnname### might be overwritten by equally named columns within the original table, you may use ###foreigncol-columnname### (e.g., ###foreigncol-uid###).