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

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

ForeignMultiple1n
^^^^^^^^^^^^^^^^^

.. figure:: ../../../Images/Configuration/ForeignMultiple1n.png
	:width: 500px
	:alt: ForeignMultiple1n form element

	Allows to add various entries in a 1:n-related table to the current entry.

This is a bit like the ForeignSingle handler except that the user does not have options to choose from but an empty input field to enter values that are saved in the foreign table and "connected" with our original table.

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 in the foreign table to write the user's input into.

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

String. The column/field to sort the foreign table by when showing them. 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

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

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

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

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.


sLocalUid
---------

String. This is the column of the original (our current own) table that holds the ID that should be written to the foreign table in order to set up the relation.

Example: ::

    uid

sForeignColumnParent
--------------------

String. As the counterpart of sLocalUid this is the column within the foreign table that will receive the value in sLocalUid. So if sLocalUid is the primary key column of the original table, this is something like the parent key field within the foreign table.

Example: ::

    pid

nMaxCount
---------

Number. Maximum amount of entries. -1 is unlimited.

Example: ::

    3

sWrapSingle
-----------

String. Wrapper for every single entry. Don't forget to include a pipe symbol (|). Example: ::

    <li>|</li>

sConcatenate
------------

String. Now think of the uploaded files being outputted in a normal or detail view. How would you like to chain multiple images together? Default is a simple comma but you might change that here.

Example: ::

    ,

sConcatenateRaw
---------------

String. See sConcatenate. This is pretty much the same except that this chaining string is used whenever we need a raw output (at the moment, only CSV files are built upon raw outputs).