<!-- $Platon: phpMyEdit/doc/sgml/configuration.fields.sgml,v 1.60 2006-09-05 08:43:44 nepto Exp $ -->
<sect1 id="configuration.fields-overview">
<title id="configuration.fields-overview.title">Definition overview</title>
<para>
Fields will be displayed in table columns left to right on the screen in the
order in which they appear in the script. Re-arrange the order of the arrays in
order to alter the order in which columns are displayed.
</para>
<para>
Display of a particular column can also be suppressed. Below is an example of
the array for a column named 'topic':
</para>
<para>
<example><title>Basic field definition</title>
<programlisting><![CDATA[
$opts['fdd']['topic'] = array(
'name' => 'Topic',
'select' => 'T',
'maxlen' => 100,
'nowrap' => false,
'sort' => true
);
]]></programlisting>
</example>
</para>
<para>
Because so many questions related to <acronym>PHP</> programming language
semantics and basis are often asked, please point on the following explanation
of "two" ways of possible field options initialization. If you are enough
experienced and familiar with <acronym>PHP</>, feel free to skip to the next
section.
</para>
<para>
As it was mentioned, there are two ways how to initialize array in
<acronym>PHP</>.
<!--
Well, I should find more clever way how to highlight code below
not using <varname> for whole code blocks. Norman will surely kick me,
if he would see this. :P
-->
<orderedlist spacing=compact>
<listitem><simpara>Direct one using
<varname>$opts['fdd']['col_name'] = array('option' => 'value')</>
which is showed above.</></>
<listitem><simpara>Postinitialization one using
<varname>$opts['fdd']['col_name']['option'] = 'value'</>
which is used in many examples in this documentation.</></>
</orderedlist>
</para>
<para>
You may realize, that it is the same if you will change or add option into basic
field definition (see example <function>array()</> and notes in first point
above) or you will add separated option initialization after this field
definition as it is described in second case.
</para>
</sect1>
<sect1 id="configuration.basic-options">
<title id="configuration.basic-options.title">Basic options</title>
<bridgehead id="configuration.name">Field name</bridgehead>
<para>
When the MySQL column name is not appropriate for display as the title of the
column in the displayed table, alternate text can be specified. To display the
word "Subject" instead of the name "Topic" for the example column from previous
chapter, add the following option to the script:
</para>
<para>
<example><title>Field name examples</title>
<programlisting><![CDATA[
$opts['fdd']['topic']['name'] = 'Subject';
]]></programlisting>
</example>
</para>
<para>
When creating MySQL tables for use with &name;, consider using the underscore
character in certain field names. For example, a MySQL column named
"last_name" will be displayed as "Last name" in tables created using &name;
(underscore characters are replaced with a space).
</para>
<bridgehead id="configuration.help">Guidance / Help</bridgehead>
<para>
Sometimes a short title can't be explicit enough, so it is neccessary to
provide the user a large description on a given field when he is manipulating
with field data. For this purpose was
<varname>$opts['fdd']['col_name']['help']</> option created. Content of this
option will appear in the third column of record display pages (Add, View, Change,
Copy and Delete modes).
</para>
<para>
This option is optional. If there is no <varname>['help']</> option for all
columns, the third "help" column will be omitted.
</para>
<para>
<example><title>Field guidance</title>
<programlisting><![CDATA[
$opts['fdd']['topic']['help'] = 'Enter topic of article here.';
]]></programlisting>
</example>
</para>
<para>
Because the field content is not escaped, you can add any HTML markups there,
for example hyperlink, JavaScript opening popup window, etc.
<example><title>Field guidance hyperlink</title>
<programlisting><![CDATA[
$opts['fdd']['topic']['help'] = '<a href="help.php?about=topic" target="_blank">?</a>';
]]></programlisting>
</example>
</para>
<bridgehead id="configuration.fields.select">Selection boxes</bridgehead>
<para>
Specify field input type as text box, numeric comparison text box, drop-down
selection, or multiple selection. The same input type will be used also for
table filtering.
<example><title>Filter selections</title>
<programlisting><![CDATA[
$opts['fdd']['col_name']['select'] = 'T'; // text box
$opts['fdd']['col_name']['select'] = 'N'; // numeric
$opts['fdd']['col_name']['select'] = 'D'; // drop down
$opts['fdd']['col_name']['select'] = 'M'; // multiple selection
$opts['fdd']['col_name']['select'] = 'O'; // radio buttons
$opts['fdd']['col_name']['select'] = 'C'; // checkboxes
]]></programlisting>
</example>
</para>
<bridgehead id="configuration.options">Display options</bridgehead>
<para>
An optional parameter to control whether a field is displayed in the add,
change, copy, delete, view, list, or filter views.
<simplelist type="horiz" columns="2">
<member> <constant>A</constant></><member> -- add</>
<member> <constant>C</constant></><member> -- change</>
<member> <constant>P</constant></><member> -- copy</>
<member> <constant>V</constant></><member> -- view</>
<member> <constant>D</constant></><member> -- delete</>
<member> <constant>L</constant></><member> -- table list</>
<member> <constant>F</constant></><member> -- table filter</>
</simplelist>
</para>
<para>
<example><title>Field display options</title>
<programlisting><![CDATA[
$opts['fdd']['col_name']['options'] = 'LF'; // shows only in table list/filter
]]></programlisting>
</example>
</para>
<bridgehead id="configuration.input">Input settings</bridgehead>
<para>
There are also additional column-specific options. These apply to certain
views or modes (add, change, delete, list). In the previous versions of &name;
these flags was part of <varname>['options']</varname> option. In the current
&version; version, the backward compatibility (BC) is preserved. However this
will be removed in the future. Thus specify these flags as a part of
<varname>['input']</varname> options. Some other flags may be added into this
option as well.
<simplelist type="horiz" columns="2">
<member> <constant>R</constant></><member> -- indicates a field is read only</>
<member> <constant>W</constant></><member> -- indicates a field is a password field</>
<member> <constant>H</constant></><member> -- indicates a field is to be hidden and marked as hidden</>
</simplelist>
</para>
<para>
<example><title>Other display options</title>
<programlisting><![CDATA[
$opts['fdd']['col_name']['input'] = 'H'; // hidden field
$opts['fdd']['col_name']['input'] = 'W'; // password field
$opts['fdd']['col_name']['input'] = 'R'; // read-only field
]]></programlisting>
</example>
</para>
<bridgehead id="configuration.fields.css">CSS customization</bridgehead>
<para>
Per field, you can define field CSS class names postfix. This is especially
useful in order to highlight one column in a table.
<example><title>Field CSS customization</title>
<programlisting><![CDATA[
$opts['fdd']['col_name']['css'] = array(
'postfix' => 'ColName'
);
]]></programlisting>
</example>
</para>
<para>
More information about CSS handling can be found in the <xref
linkend="configuration.css" endterm="configuration.css.title"> section.
</para>
</sect1>
<sect1 id="configuration.fields.booleans">
<title id="configuration.fields.booleans.title">Booleans</title>
<para>
All variables in following section should have only <constant>true</constant> or
<constant>false</constant> value.
</para>
<bridgehead id="configuration.fields.sort">Sorting</bridgehead>
<para>
Allow users to sort the display on this column. Use <constant>true</constant>
for enable, <constant>false</constant> for disable.
<example><title>Field sorting</title>
<programlisting><![CDATA[
$opts['fdd']['col_name']['sort'] = true;
$opts['fdd']['col_name']['sort'] = false;
]]></programlisting>
</example>
</para>
<bridgehead id="configuration.fields.strip-tags">Stripping tags</bridgehead>
<para>
If you are storing HTML and/or PHP content in you database columns, you may want
to have <varname>$opts['fdd']['col_name']['strip_tags']</varname> variable
turned on for particular fields. It will strip HTML and PHP tags from field
content, when displaying column in table listing.
<example><title>Stripping tags</title>
<programlisting><![CDATA[
$opts['fdd']['col_name']['strip_tags'] = true;
$opts['fdd']['col_name']['strip_tags'] = false;
]]></programlisting>
</example>
</para>
<bridgehead id="configuration.fields.escape">HTML escaping</bridgehead>
<para>
By default are all field values escaped using <ulink
url="http://www.php.net/htmlspecialchars"><function>htmlspecialchars()</function></ulink>
PHP function. However, this is not always desirable. You can turn escaping off
by setting <varname>$opts['fdd']['col_name']['escape']</varname> to
<constant>false</constant>.
<example><title>Field escaping</title>
<programlisting><![CDATA[
$opts['fdd']['col_name']['escape'] = true;
$opts['fdd']['col_name']['escape'] = false;
]]></programlisting>
</example>
</para>
</sect1>
<sect1 id="configuration.javascript-validation">
<title id="configuration.javascript-validation.title">JavaScript validation</title>
<para>
&name; users can benefit from the JavaScript scripting language, when
validating input values before the form is submited.
</para>
<bridgehead id="configuration.fields.js.required">Required fields</bridgehead>
<para>
Simple validation JavaScript can be generated to prevent null
entries by the user. If an entry is required for a particular field, set the
<varname>['js']['required']</varname> option to <constant>true</constant>.
<example><title>Required fields</title>
<programlisting><![CDATA[
$opts['fdd']['col_name']['js']['required'] = true;
$opts['fdd']['col_name']['js']['required'] = false;
]]></programlisting>
</example>
</para>
<bridgehead id="configuration.fields.js.regexp">Regular expressions</bridgehead>
<para>
JavaScript regular expressions can be a powerful way to make interactive input
validation. When used, input must match the desired regular expression defined
in the <varname>$opts['fdd']['col_name']['js']['regexp']</varname>.
If a field does not match, a JavaScript alert will be invoked to force the user
to change entered value.
<example><title>Regular expression example</title>
<programlisting><![CDATA[
$opts['fdd']['col_name']['js']['regexp'] = '/^[0-9]*$/';
]]></programlisting>
</example>
</para>
<para>
Regular expressions are written in Perl compatible style. The expression above
allows the form to submit only when numeric characters
<constant>0-9</constant> are entered in the field. An empty value is also
allowed, but you can use <varname>['js']['regexp']</varname> in combination
with <varname>['js']['required']</varname> to prevent empty entries.
</para>
<bridgehead id="configuration.fields.js.hint">Hints</bridgehead>
<para>
When the <varname>['js']['required']</varname> option is used and the value
entered is empty, or the characters entered do not match the defined
<varname>['js']['regexp']</varname>, a warning with the default message
is displayed. This message can be changed using
<varname>['js']['hint']</varname>. This is especially useful for advising the
user about field-specific data input restrictions.
<example><title>JavaScript hint</title>
<programlisting><![CDATA[
$opts['fdd']['col_name']['js']['hint']
= 'Please enter only numbers in the "col_name" field.';
]]></programlisting>
</example>
</para>
</sect1>
<sect1 id="configuration.input-restrictions">
<title id="configuration.input-restrictions.title">Input restrictions</title>
<para>
You can restrict user input for selected fields to selected values. There are
several ways to do this. A variety of methods and examples appear below.
</para>
<bridgehead>Simple restriction</bridgehead>
<para>
Simple restriction means to restrict user input to the specified constants.
Examples appear below.
<example><title>Simple input restriction</title>
<programlisting><![CDATA[
$opts['fdd']['col_name']['values'] = array('','No','Yes'); // default is '' (nothing)
$opts['fdd']['col_name']['values'] = array('','Yes','No'); // default is '' (nothing)
$opts['fdd']['col_name']['values'] = array('0','1'); // default is 0
$opts['fdd']['col_name']['values'] = array('A','B','C'); // default is A
$opts['fdd']['col_name']['values'] = array('No','Yes'); // default is No
$opts['fdd']['col_name']['values'] = array('Yes','No'); // default is Yes
$opts['fdd']['col_name']['values'] = range(1,99);
]]></programlisting>
</example>
</para>
<bridgehead>Table lookup</bridgehead>
<para>
Variables <varname>$opts['fdd']['col_name']['values']['table']</varname> and
<varname>$opts['fdd']['col_name']['values']['column']</varname> restricts user
input to the values found in the specified column of another table. The
optional <varname>['values']['description']</varname> field allows the values
displayed to the user to be different from those in the
<varname>['values']['column']</varname> field. This is useful for giving more
meaning to column values.
<example><title>Table lookup restriction</title>
<programlisting><![CDATA[
$opts['fdd']['col_name']['values']['table'] = 'extractTable';
$opts['fdd']['col_name']['values']['column'] = 'extractColumn';
$opts['fdd']['col_name']['values']['description'] = 'extractDescription'; // optional
]]></programlisting>
</example>
</para>
<bridgehead>Column joining</bridgehead>
<para>
It is also possible to have multiple fields in your description. For example,
to concatenate two description labels found in a different table:
<example><title>Advanced table lookup</title>
<programlisting><![CDATA[
$opts['fdd']['col_name']['values']['description']['columns'][0] = 'desc_column_1';
$opts['fdd']['col_name']['values']['description']['columns'][1] = 'desc_column_2';
$opts['fdd']['col_name']['values']['description']['divs'][0] = ' ';
]]></programlisting>
</example>
</para>
<para>
The 'div' component is what will be used as a divider between the columns in the
display. You don't need to define the last 'div' field if it isn't required. So,
for example if you have a series of people in a table, with a separate column
for id, first name, and last name, you could use:
<example><title>Complex table lookup example</title>
<programlisting><![CDATA[
$opts['fdd']['col_name']['values']['db'] = 'mydb'; // optional
$opts['fdd']['col_name']['values']['table'] = 'mytable';
$opts['fdd']['col_name']['values']['column'] = 'id';
$opts['fdd']['col_name']['values']['description']['columns'][0] = 'name_last';
$opts['fdd']['col_name']['values']['description']['divs'][0] = ', ';
$opts['fdd']['col_name']['values']['description']['columns'][1] = 'name_first';
$opts['fdd']['col_name']['values']['filters'] = 'id IN (1,2,3)'; // optional WHERE clause
$opts['fdd']['col_name']['values']['orderby'] = 'last_name'; // optional ORDER BY clause
]]></programlisting>
</example>
</para>
<para>
If prefixation with some string in column description is desired, the
<varname>$opts['fdd']['col_name']['values']['description']['divs'][-1]</> can
be used. It will precede
<varname>$opts['fdd']['col_name']['values']['description']['columns'][0]</>
column.
</para>
<para>
Note that the above example contains additional features, such as filtering
values using <varname>['filters']</>, and ordering values using
<varname>['orderby']</>.
</para>
<bridgehead>Additional values</bridgehead>
<para>
Additional values to table lookup could be stored in
<varname>['values2']</varname> array. The main difference between simple
<varname>['values']</varname> usage is, that array keys will be stored into
database and array values will be printed out in input section boxes. This is
especially useful for MySQL enumerations when you do not want to print out
enumeration keys, but rather some more user-friendly texts. See example:
<example><title>Input restriction using additional values</title>
<programlisting><![CDATA[
$opts['fdd']['col_name']['values2'] = array(
'displayed' => 'Displayed Article',
'hidden' => 'Hidden Article',
'disabled' => 'Disabled Article',
'deleted' => 'Deleted Article'
);
]]></programlisting>
</example>
</para>
<para>
In the example above, keywords 'displayed', 'hidden', 'disabled' and 'deleted'
will be stored in database, but user-friendly expressions will appear in
select box for user. Usage of <varname>['values2']</> can be combined with
<varname>['values']</> usage.
</para>
<bridgehead>Advanced joining</bridgehead>
<para>
Sometimes you want to restrict table joining on the output. This is important
in case where <varname>['values']['column']</varname> is not unique in
<varname>['values']['table']</varname>. For this purpose, you can use
<varname>$opts['fdd']['col_name']['values']['join']</> option. Using the
<varname>['values']['filters']</varname> simply will not work, because it is
not applied at join time, but only when filling values in the drop down menu.
</para>
<para>
These variables are available in this option.
<simplelist type="horiz" columns="2">
<member> <varname>$main_table</varname></member>
<member> -- alias of the main table</member>
<member> <varname>$main_column</varname></member>
<member> -- join column in the main table</member>
<member> <varname>$join_table</varname></member>
<member> -- alias of the values table</member>
<member> <varname>$join_column</varname></member>
<member> -- join column in the values table</member>
<member> <varname>$join_description</varname></member>
<member> -- description column in the values table</member>
</simplelist>
</para>
<para>
&name; will create by default
<varname>$main_table.$main_column = $join_table.$join_column</varname>
join, what is sufficient the most cases. However you may extend it with
additional conditions as well.
<example><title>Table lookup with advanced joining</title>
<programlisting><![CDATA[
$opts['fdd']['col_name']['values']['join']
= '$main_table.$main_column = $join_table.$join_column AND '
. '$main_table.another_col = $join_table.another_col'
]]></programlisting>
</example>
</para>
<para>
Please note that <varname>['values']['filters']</varname> is used for filtering
items in dropdown during Add/Edit mode (with a SQL WHERE clause) while
<varname>['values']['join']</varname> is useful for having a correct LEFT JOIN
against the main table in List/View mode.
</para>
</sect1>
<sect1 id="configuration.output-control">
<title id="configuration.output-control.title">Output control</title>
<bridgehead id="configuration.colattrs">Cell attributes</bridgehead>
<para>
For setting simple HTML attributes of displayed field cells, there is a
<varname>['colattrs']</varname> option provided.
</para>
<para>
For example the alignment of the text inside a column can be controlled using
the usual HTML <varname>align</> attribute of the cell tag. The text in the
column will be placed in the center. Useful if you have numbers in a column
and the title of the column is long.
<example><title>Cell attribute example</title>
<programlisting><![CDATA[
$opts['fdd']['col_name']['colattrs'] = 'align="center"';
]]></programlisting>
</example>
</para>
<para>
Please note, that recommended and probably also better approach for displayed
columns design control is to use <xref linkend="configuration.css"
endterm="configuration.css.title">. Particulary point at <xref
linkend="configuration.fields.css" endterm="configuration.fields.css"> for
more information how to customize selected field appearance.
</para>
<bridgehead id="configuration.size">Field size</bridgehead>
<para>
A size of input field can be defined. Note this does affect also table
filtering page. If you want different value for this type of page, use <xref
linkend="configuration.options-variability"
endterm="configuration.options-variability.title"> feature.
<example><title>Input field size</title>
<programlisting><![CDATA[
$opts['fdd']['col_name']['size'] = '10';
$opts['fdd']['col_name']['size|F'] = '5'; // only 5 for filter
]]></programlisting>
</example>
</para>
<bridgehead id="configuration.maxlen">Maximum field length</bridgehead>
<para>
Maximum length of input boxes displayed for Add / Change record mode may be
set.
<example><title>Field sizes</title>
<programlisting><![CDATA[
$opts['fdd']['col_name']['maxlen'] = '8';
$opts['fdd']['col_name']['maxlen'] = '24';
]]></programlisting>
</example>
</para>
<bridgehead id="configuration.textarea">Textarea sizes</bridgehead>
<para>
If the above setting does not work for you, you are probably attempting to
change textarea size. It is also possible to specify the size of a textarea used
to give multi-line input. Try something like:
</para>
<para>
<example><title>Textarea field height & width</title>
<programlisting><![CDATA[
$opts['fdd']['col_name']['textarea']['rows'] = 1;
$opts['fdd']['col_name']['textarea']['cols'] = 40;
]]></programlisting>
</example>
</para>
<bridgehead id="configuration.trimlen">Character length limit</bridgehead>
<para>
If a table contains a number of text columns which each contain quite a bit of
text, the table will likely scroll off the screen. This can be prevented by
displaying only a portion of the content from a particular column.
</para>
<para>
For example, to display only the first 30 characters from a column named
'explanation', add the following:
<example><title>Character length limit</title>
<programlisting><![CDATA[
$opts['fdd']['explanation']['trimlen'] = 30;
]]></programlisting>
</example>
</para>
<para>
You may find it useful to limit the number of characters displayed for one or
more columns. This option is approximately equivalent to the following PHP
statement:
<screen>
if (strlen($value) > $trimlen) {
echo substr($value, 0, $trimlen - 3) . '...';
}
</screen>
</para>
<bridgehead id="configuration.nowrap">Wrapping</bridgehead>
<para>
The 'nowrap' option is essentially equivalent to the HTML markup <td nowrap>.
<example><title>Wrapping</title>
<programlisting><![CDATA[
$opts['fdd']['col_name']['nowrap'] = true;
$opts['fdd']['col_name']['nowrap'] = false;
]]></programlisting>
</example>
</para>
<bridgehead id="configuration.mask">Print mask</bridgehead>
<para>
A string that is used by <function>sprintf()</> to format field output. For more
information about this function usage, please refer to its <ulink
url="http://www.php.net/sprintf">manual page</ulink> in PHP
documentation.
</para>
<para>
<example><title>Print mask field definition</title>
<programlisting><![CDATA[
$opts['fdd']['col_name']['mask'] = '%%'; // a literal percent character
$opts['fdd']['col_name']['mask'] = '%01.2f'; // currency or floating-point number
$opts['fdd']['col_name']['mask'] = '%.10s'; // trim string to 10 characters
]]></programlisting>
</example>
</para>
<bridgehead id="configuration.datemask">Date masks</bridgehead>
<para>
Date mask is string that is used to format date and/or time fields using PHP's
function call. You can use <varname>['datemask']</> option to format date and
time using <ulink
url="http://www.php.net/date"><function>date()</function></ulink>
function or you can use <varname>['strftimemask']</> option to format date and
time using <ulink
url="http://www.php.net/strftime"><function>strftime()</function></ulink>
function. See function's manual pages for valid formatting characters.
</para>
<para>
These date and time formatting functions are applied only if selected value
from database has non-zero length and is a valid date. This prevents empty
strings, <constant>NULL</constant> fields and invalid dates from being
displayed as date of 1st January 1970.
</para>
<para>
<example><title>Date mask field definitions</title>
<programlisting><![CDATA[
$opts['fdd']['col_name']['datemask'] = 'r';
]]></programlisting>
</example>
Note that currently only fields displaying is implemented. Entering date
fields concerning to these masks will be implemented in the nearly future.
</para>
<bridgehead id="configuration.number-format">Number format</bridgehead>
<para>
Use this option to get a formatted version of number. It uses <ulink
url="http://www.php.net/number_format"><function>number_format()</></> PHP
function. Option accepts an array with one or three elements.
</para>
<para>
The first array member defines the number of decimals in formatted number, the
second member specifies the character before decimals and the last array
member means separator between every group of thousands.
</para>
<para>
<example><title>Number format example</title>
<programlisting><![CDATA[
$opts['fdd']['col_name']['number_format'] = array(2, '.', ',');
]]></programlisting>
</example>
</para>
</sect1>
<sect1 id="configuration.url-linking">
<title id="configuration.url-linking.title">URL linking</title>
<para>
Fields can be made 'clickable' in the display using <varname>['URL']</varname>
variable. Primary examples follows:
<example><title>Simple URL examples</title>
<programlisting><![CDATA[
$opts['fdd']['col_name']['URL'] = 'http://$link';
$opts['fdd']['col_name']['URL'] = 'mailto:$value';
]]></programlisting>
</example>
<!-- ANOTHER EXAMPLES:
$opts['fdd']['col_name']['URL'] = 'http:';
$opts['fdd']['col_name']['URLtarget'] ='_blank';
$opts['fdd']['col_name']['URL'] = 'mailto:';
$opts['fdd']['col_name']['URL'] is , e.g.:
$opts['fdd']['col_name']['URL'] = 'mailto:' or $opts['fdd']['col_name']['URL'] = 'http:';
$opts['fdd']['col_name']['URL'] = '$page?stuff';
-->
</para>
<para>
Note that the following are available as variables for usage in <varname>['URL']</varname>:
<simplelist type=horiz columns=2>
<member> <varname>$key</varname></><member> -- key field for record</>
<member> <varname>$name</varname></><member> -- name of the field</>
<member> <varname>$value</varname></><member> -- value of the field</>
<member> <varname>$link</varname></><member> -- not modified raw value</>
<member> <varname>$css</varname></><member> -- CSS class name</>
<member> <varname>$page</varname></><member> -- this HTML page</>
<member> <varname>$url</varname></><member> -- CGI variables</>
<!-- <member> <varname>$row</varname></><member>
<function>mysql_fetch_assoc()</function> for this row</> -->
</simplelist>
</para>
<para>
To open a link in a new web browser window use:
<example><title>URL target example</title>
<programlisting><![CDATA[
$opts['fdd']['col_name']['URLtarget'] = '_blank';
]]></programlisting>
</example>
</para>
<para>
To display alternative link text use:
<example><title>URL display example</title>
<programlisting><![CDATA[
$opts['fdd']['col_name']['URLdisp'] = 'Launch Page';
]]></programlisting>
</example>
</para>
<para>
Old 3.5 behaviour is also supported via <varname>['URLprefix']</varname>. It
will prepend string before if it is not already present there. Variable
<varname>['URLpostfix']</varname> similary to <varname>['URLprefix']</varname>
will append string after if it is not already present there.
<example><title>URL prefix and postfix</title>
<programlisting><![CDATA[
$opts['fdd']['col_name']['URLprefix'] = 'mailto:';
$opts['fdd']['col_name']['URLprefix'] = 'http://';
$opts['fdd']['col_name']['URLprefix'] = array('http://', 'ftp://');
]]></programlisting>
</example>
</para>
<para>
In the third example you can see that array of prefixes or postfixes are
supported. First member of array is added to URL value only if none from the
elements was matched. This is especially useful in having intelligent URL
links with added ability to enter addresses like "www.platon.sk" without
preceding "http://".
</para>
</sect1>
<sect1 id="configuration.fields.sql">
<title id="configuration.fields.sql.title">SQL expressions</title>
<para>
There is a possibility to define a SQL expression that should be applied to
particular field when reading or writting data from database. This is very
useful when you want to interpret the field's content in different way than it
is stored in database. To be more clear, see following examples.
<example><title>Read SQL expressions</title>
<programlisting><![CDATA[
$opts['fdd']['surname']['sql'] = 'CONCAT(surname, ', ', firstname)';
$opts['fdd']['title']['sql'] = 'IF(TRIM(title) != "", title, title2)';
]]></programlisting>
</example>
</para>
<para>
The first example appends content of the <varname>firstname</> field to the
<varname>surname</> field. Because this is done on the database level, sorting
and searching (in table filtering page) on this field will properly work.
Similarly in the second example, the <varname>title2</> field will be used if
the <varname>title</> field is empty. In this manner you can define a special
static string, which should be printed in case a field is empty. Just
substitute a quoted string in place of <varname>title2</>.
</para>
<para>
Similarly, you can use SQL expression for storing data into database.
<example><title>Write SQL expressions</title>
<programlisting><![CDATA[
$opts['fdd']['surname']['sqlw'] = 'UPPER($val_qas)';
$opts['fdd']['title']['sqlw'] = 'TRIM("$val_as")';
]]></programlisting>
</example>
</para>
<para>
The first example above makes <varname>surname</> uppercase when storing field
into database. The second one trims all whitespace characters around
<varname>title</> before writing it to database.
</para>
<para>
As a placeholder for the field's content, there are three variables available.
<simplelist type="horiz" columns="2">
<member> <varname>$val</varname></member>
<member> -- value of the field</member>
<member> <varname>$val_as</varname></member>
<member> -- value with <function>addslashes()</function> function applied</member>
<member> <varname>$val_qas</varname></member>
<member> -- same as <varname>$val_as</varname> with quotes around</member>
</simplelist>
</para>
<para>
If the <varname>$val</varname> is <constant>some"nice"thing</constant>, then
<varname>$val_as</varname> becomes <constant>some\"nice\"thing</constant> and
<varname>$val_qas</varname> becomes <constant>"some\"nice\"thing"</constant>.
You have to use these variables correctly in your <varname>['sqlw']</varname>
expressions, otherwise a MySQL parsing error could occur. We recommend you use
the <varname>$val_qas</varname> variable whenever possible, as it is the
safest one from the mentioned alternatives.
</para>
<para>
A very useful and favourite usage of the <varname>['sqlw']</varname> option is
to explicitly tell &name; to store a <constant>NULL</constant> value instead
of an empty string for the particular column. Empty string and
<constant>NULL</constant> are two different values. Many people really do not
like empty strings in their tables, thus now they have possibility to change
them to <constant>NULL</constant> when user simply enters nothing into form
input field.
<example>
<title>Storing <constant>NULL</constant> instead of empty string</title>
<programlisting><![CDATA[
$opts['fdd']['col_name']['sqlw'] = 'IF($val_qas = "", NULL, $val_qas)';
]]></programlisting>
</example>
</para>
<para>
Another example of the <varname>['sqlw']</varname> usage is the storage of
user passwords. It is good idea to process user password using some well-known
hash function before saving it in the database. Following statement is used in
order to avoid re-hashing an already hashed string. This means, if
<varname>col_name</varname> value was not changed, then do not apply
<function>MD5()</function> on it. If <varname>col_name</varname> value was
changed, then apply <function>MD5()</function> function.
<example>
<title>Storing password's MD5 hash</title>
<programlisting><![CDATA[
$opts['fdd']['col_name']['sqlw'] = 'IF(col_name = $val_qas, $val_qas, MD5($val_qas))';
]]></programlisting>
</example>
</para>
</sect1>
<sect1 id="configuration.fields.php">
<title id="configuration.fields.php.title">PHP expressions</title>
<para>
PHP feature allows user to display any HTML code in place of a value. Behavior
is the same as in triggers.
</para>
<para>
If PHP option is set, a file of that name is included (and executed). All
variables avaliable in the core class are available in the included PHP file.
<example>
<title>PHP execution file</title>
<programlisting><![CDATA[
<?php
if ($this->operation == $this->labels['Add']) {
return 'add mode selected';
} else {
return '<img src="tt.png" alt="TT">';
}
?>
]]></programlisting>
</example>
This option is indended for advanced usage. Together with pre and before <link
linkend="configuration.triggers">triggers</link>, it allows tweaking the
core class without the need to hack it. To change input, use before triggers
or <varname>['sqlw']</varname> option.
</para>
</sect1>
<sect1 id="configuration.tabs-feature">
<title id="configuration.tabs-feature.title">TABs feature</title>
<para>
Because the TABs feature is one of the most important &name; features, it
deserves its own documentation section.
</para>
<para>
Tabbed groups of fields appear in specific page modes: Add, Change, coPy,
View, or Delete. In List mode, when TAB settings are combined with <xref
linkend="configuration.options" endterm="configuration.options">, users can
suppress the display of fields below the first TAB group.
</para>
<para>
This feature is for tables, which have more than a few fields. It enables you
to group fields together into groups. Every group of fields then becomes
accessible via TAB on the top or the bottom of the page, what is based on the
<varname>['navigation']</varname> settings. TAB has its own label, which can
describe fields in a particular group.
</para>
<para>
TAB is defined in the first field of group. Every following field will belong
to the same group under the same TAB untill the next TAB is defined. The first
field must have its own TAB definition. If this definition is omitted, fields
will belong to first default group and this group will be a permanent tab that
will be always visible.
</para>
<para>
TAB definition is very simple. Just define the label on the TAB (1st field,
5th field, 10th field, and so on).
<example><title>TAB definition</title>
<programlisting><![CDATA[
$opts['fdd']['col_name']['tab'] = 'Counts';
]]></programlisting>
</example>
</para>
<para>
There is also possibility to define the default TAB. In this case, the array
style initialization is required.
<example><title>Default TAB definition</title>
<programlisting><![CDATA[
$opts['fdd']['col_name']['tab'] = array(
'name' => 'Personal data',
'default' => true
);
]]></programlisting>
</example>
</para>
<para>
In List mode, to initially display individual fields from only the first TAB
group, apply <xref linkend="configuration.options"
endterm="configuration.options"> to all fields below the first TAB group, for
example:
<example><title>Display options below the first TAB</title>
<programlisting><![CDATA[
$opts['fdd']['col_name']['options'] = 'AVCPD'; // or possibly 'AVCPDF'
]]></programlisting>
</example>
</para>
<para>
For users with non-compliant JavaScript browsers, you can turn TABs feature
off. The general control is achieved via
<varname>$opts['display']['tabs']</varname> variable. If not specified, its
value is considered as <constant>true</constant>. Variable
<varname>$opts['display']</varname> is described in <xref
endterm="configuration.page-elements" linkend="configuration.page-elements">
sebsection.
<example><title>Turning TAB feature off</title>
<programlisting><![CDATA[
$opts['display']['tabs'] = false;
]]></programlisting>
</example>
</para>
</sect1>
<sect1 id="configuration.options-variability">
<title id="configuration.options-variability.title">Options variability</title>
<para>
This section does not descibe new field options. It just extends the
possibility of their initialization. Options variability can be applied to
each field option.
</para>
<para>
There is often a situation when you want to have some field option in effect
only on particular page(s). But on other pages you do not want to have this
option in effect. There are pages where a field option should be taken into
consideration, but there are also pages where the option should not appear.
</para>
<para>
A good example for this is the <varname>['trimlen']</> option. Imagine you set
something like this:
<example><title>Init without options variability</title>
<programlisting><![CDATA[
$opts['fdd']['col_name']['trimlen'] = 30;
]]></programlisting>
</example>
This will trim the maximum length of text to 30 characters on all possible
pages, which in this case are:
<itemizedlist spacing=compact>
<listitem><simpara>table list</></>
<listitem><simpara>table filter</></>
<listitem><simpara>record view</></>
<listitem><simpara>record delete</></>
</itemizedlist>
</para>
<para>
This is nice and it will work as expected, however on the record view page it
may be desirable to see the whole field content, not only first 30 characters.
Similarly we could want this also for delete page.
</para>
<para>
Thus there is a possiblity to restrict a particular option to affect only
selected types of pages. In our case we want to resctrict the
<varname>['trimlen']</> option to affect the table listing and table filtering
pages. This can be done in the following way. Take a look at "|LF" string in
the definition.
<example><title>Init with options variability</title>
<programlisting><![CDATA[
$opts['fdd']['col_name']['trimlen|LF'] = 30;
]]></programlisting>
</example>
</para>
<para>
Each restriction letter stands for particular page type. They are the same as
those described in list under <xref linkend="configuration.options"
endterm="configuration.options"> subsection.
</para>
</sect1>
Platon Group <platon@platon.sk> http://platon.sk/
|
Prihlásiť
Registrácia
English
![[BACK]](http://cvsweb.platon.sk/icons/back.gif){kind=icon}
![[TXT]](http://cvsweb.platon.sk/icons/text.gif){kind=icon}
![[DIR]](http://cvsweb.platon.sk/icons/dir.gif){kind=icon}
Vyššie na