Docs For Class DBLJSExternalSelector

Description

Utility class which formats javascript-driven record selector.

This class provides support for DBLJSLCField. It implements selecting one of N records in a popup window.

Its most important input is query, from which the items available for choice are got. The query should return (id,text) value pairs. ID is id of the record, Text is textual representation of the record, displayed to user.

Class prints form with an editbox, a listview and a submit/close buttons. In the listview, records available for choice are shown. The editbox is used for filtering. When it is not empty (user writes something to it), only records which contain the string (in editbox) as a substring are shown. (Comparison is case insensitive.) (See matchOnlyFromStart property.)

The whole selector operates in two modes - let's call them "popup" and "submit". By default, it is in the "popup" mode. If the submitURL property is set, it operates in the "submit" mode.

In popup mode:

Close button is provided which can be used to close the window
When the select button is clicked, selected item's id and text are copied to the selected opener form (see formName, idFieldName and textFieldName properties).

In submit mode:

No close button is provided
When the select button is clicked, the form is submitted. The selected id is passed as the 's' GET/POST (see formMethod property) parameter.

You will use the popup mode for the popup of DBLJSLCField. The submit mode is usually used to select a master record when creating new dependent record. (TODO Example pointer TODO)

Located in /DBLJSExternalSelector.php (line 45)

Variable Summary

bool $allowEmpty

string $formMethod

string $formName

string $idFieldName

bool $matchOnlyFromStart

string $myFormName

string $noneID

string $noneText

DBLQuery $query

string $selectText

string $submitURL

string $textFieldName

string $title

Method Summary

DBLJSExternalSelector DBLJSExternalSelector (string $formName, string $fieldName, string $title, DBLQuery &$query)

void printForm (string $formName)

void show (string $id)

Variables

bool $allowEmpty (line 75)

var: Allow empty selection to be set (will set empty id and text). Defaults to true.

string $formMethod (line 98)

var: Form method to use. Defaults to GET.

string $formName (line 52)

var: Form name in the opener ("parent") window which should be changed. Usually "editFrm", since this is the default form name DBLView uses.

string $idFieldName (line 65)

var: Name of the field (on the opener form) where to store selected ID. Defaults to fieldName constructor parameter.

bool $matchOnlyFromStart (line 84)

var: Do not search for substring, rather show records which starts with the text in the editbox. Defaults to false.

string $myFormName (line 60)

var: Form name the selector will use for the form (default "frm").

string $noneID (line 102)

var: ID of the 'none' value (default is '0')

string $noneText (line 106)

var: Text of the none value (default is localized '<None>')

DBLQuery $query (line 56)

var: Query used to get list of choices. See class description.

string $selectText (line 94)

var: Text to show in the select button. Defaults to localized (gettext) "select".

string $submitURL (line 89)

var: URL where to submit the form. If set, nothing is changed in the opener form (it may even not exist). Defaults to empty string.

string $textFieldName (line 70)

var: Name of the field (on the opener form) where to store selected text. Defaults to $fieldName."_txt".

string $title (line 79)

var: Title to be shown above the form (HTML). Constructor parameter.

Methods

Constructor DBLJSExternalSelector (line 118)

Constructor.

DBLJSExternalSelector DBLJSExternalSelector (string $formName, string $fieldName, string $title, DBLQuery &$query)

string $formName: Name of the opener form. (May be empty for submit mode.)
string $fieldName: Name of the field to set in the opener form. (May be empty for submit mode.)
string $title: Title of the form table.
DBLQuery $query: Query to get list of choides. See class description.

printForm (line 141)

Prints form itself (editbox, listview and buttons).

Override this if you wish to get different form look.

void printForm (string $formName)

string $formName: Name to use for this form.

show (line 170)

Output form and all the necessary JavaScript.

void show (string $id)

string $id: ID of the record that should be selected.