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. Display of a particular column can also be suppressed. Below is an example of the array for a column named 'topic': 'Topic', 'select' => 'T', 'maxlen' => 100, 'nowrap' => false, 'sort' => true ); ]]> Because so many questions related to 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 PHP, feel free to skip to the next section. As it was mentioned, there are two ways how to initialize array in PHP. Direct one using $opts['fdd']['col_name'] = array('option' => 'value') which is showed above. Postinitialization one using $opts['fdd']['col_name']['option'] = 'value' which is used in many examples in this documentation. You may realize, that it is the same if you will change or add option into basic field definition (see example 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. Field name 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: 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). Guidance / Help 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 $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). This option is optional. If there is no ['help'] option for all columns, the third "help" column will be omitted. Because the field content is not escaped, you can add any HTML markups there, for example hyperlink, JavaScript opening popup window, etc. ?'; ]]> Selection boxes 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. Display options An optional parameter to control whether a field is displayed in the add, change, copy, delete, view, list, or filter views.   A -- add   C -- change   P -- copy   V -- view   D -- delete   L -- table list   F -- table filter Input settings 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 ['options'] 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 ['input'] options. Some other flags may be added into this option as well.   R -- indicates a field is read only   W -- indicates a field is a password field   H -- indicates a field is to be hidden and marked as hidden CSS customization Per field, you can define field CSS class names postfix. This is especially useful in order to highlight one column in a table. 'ColName' ); ]]> More information about CSS handling can be found in the section. All variables in following section should have only true or false value. Sorting Allow users to sort the display on this column. Use true for enable, false for disable. Stripping tags If you are storing HTML and/or PHP content in you database columns, you may want to have $opts['fdd']['col_name']['strip_tags'] variable turned on for particular fields. It will strip HTML and PHP tags from field content, when displaying column in table listing. HTML escaping By default are all field values escaped using htmlspecialchars() PHP function. However, this is not always desirable. You can turn escaping off by setting $opts['fdd']['col_name']['escape'] to false. &name; users can benefit from the JavaScript scripting language, when validating input values before the form is submited. Required fields Simple validation JavaScript can be generated to prevent null entries by the user. If an entry is required for a particular field, set the ['js']['required'] option to true. Regular expressions 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 $opts['fdd']['col_name']['js']['regexp']. If a field does not match, a JavaScript alert will be invoked to force the user to change entered value. Regular expressions are written in Perl compatible style. The expression above allows the form to submit only when numeric characters 0-9 are entered in the field. An empty value is also allowed, but you can use ['js']['regexp'] in combination with ['js']['required'] to prevent empty entries. Hints When the ['js']['required'] option is used and the value entered is empty, or the characters entered do not match the defined ['js']['regexp'], a warning with the default message is displayed. This message can be changed using ['js']['hint']. This is especially useful for advising the user about field-specific data input restrictions. 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. Simple restriction Simple restriction means to restrict user input to the specified constants. Examples appear below. Table lookup Variables $opts['fdd']['col_name']['values']['table'] and $opts['fdd']['col_name']['values']['column'] restricts user input to the values found in the specified column of another table. The optional ['values']['description'] field allows the values displayed to the user to be different from those in the ['values']['column'] field. This is useful for giving more meaning to column values. Column joining It is also possible to have multiple fields in your description. For example, to concatenate two description labels found in a different table: 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: If prefixation with some string in column description is desired, the $opts['fdd']['col_name']['values']['description']['divs'][-1] can be used. It will precede $opts['fdd']['col_name']['values']['description']['columns'][0] column. Note that the above example contains additional features, such as filtering values using ['filters'], and ordering values using ['orderby']. Additional values Additional values to table lookup could be stored in ['values2'] array. The main difference between simple ['values'] 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: 'Displayed Article', 'hidden' => 'Hidden Article', 'disabled' => 'Disabled Article', 'deleted' => 'Deleted Article' ); ]]> 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 ['values2'] can be combined with ['values'] usage. Advanced joining Sometimes you want to restrict table joining on the output. This is important in case where ['values']['column'] is not unique in ['values']['table']. For this purpose, you can use $opts['fdd']['col_name']['values']['join'] option. Using the ['values']['filters'] simply will not work, because it is not applied at join time, but only when filling values in the drop down menu. These variables are available in this option.   $main_table -- alias of the main table   $main_column -- join column in the main table   $join_table -- alias of the values table   $join_column -- join column in the values table   $join_description -- description column in the values table &name; will create by default $main_table.$main_column = $join_table.$join_column join, what is sufficient the most cases. However you may extend it with additional conditions as well. Please note that ['values']['filters'] is used for filtering items in dropdown during Add/Edit mode (with a SQL WHERE clause) while ['values']['join'] is useful for having a correct LEFT JOIN against the main table in List/View mode. Cell attributes For setting simple HTML attributes of displayed field cells, there is a ['colattrs'] option provided. For example the alignment of the text inside a column can be controlled using the usual HTML 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. Please note, that recommended and probably also better approach for displayed columns design control is to use . Particulary point at for more information how to customize selected field appearance. Field size 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 feature. Maximum field length Maximum length of input boxes displayed for Add / Change record mode may be set. Textarea sizes 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: Character length limit 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. For example, to display only the first 30 characters from a column named 'explanation', add the following: 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: if (strlen($value) > $trimlen) { echo substr($value, 0, $trimlen - 3) . '...'; } Wrapping The 'nowrap' option is essentially equivalent to the HTML markup <td nowrap>. Print mask A string that is used by sprintf() to format field output. For more information about this function usage, please refer to its manual page in PHP documentation. Date masks Date mask is string that is used to format date and/or time fields using PHP's function call. You can use ['datemask'] option to format date and time using date() function or you can use ['strftimemask'] option to format date and time using strftime() function. See function's manual pages for valid formatting characters. 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, NULL fields and invalid dates from being displayed as date of 1st January 1970. Note that currently only fields displaying is implemented. Entering date fields concerning to these masks will be implemented in the nearly future. Number format Use this option to get a formatted version of number. It uses number_format() PHP function. Option accepts an array with one or three elements. 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. Fields can be made 'clickable' in the display using ['URL'] variable. Primary examples follows: Note that the following are available as variables for usage in ['URL']:   $key -- key field for record   $name -- name of the field   $value -- value of the field   $link -- not modified raw value   $css -- CSS class name   $page -- this HTML page   $url -- CGI variables To open a link in a new web browser window use: To display alternative link text use: Old 3.5 behaviour is also supported via ['URLprefix']. It will prepend string before if it is not already present there. Variable ['URLpostfix'] similary to ['URLprefix'] will append string after if it is not already present there. 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://". 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. The first example appends content of the firstname field to the 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 title2 field will be used if the 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 title2. Similarly, you can use SQL expression for storing data into database. The first example above makes surname uppercase when storing field into database. The second one trims all whitespace characters around title before writing it to database. As a placeholder for the field's content, there are three variables available.   $val -- value of the field   $val_as -- value with addslashes() function applied   $val_qas -- same as $val_as with quotes around If the $val is some"nice"thing, then $val_as becomes some\"nice\"thing and $val_qas becomes "some\"nice\"thing". You have to use these variables correctly in your ['sqlw'] expressions, otherwise a MySQL parsing error could occur. We recommend you use the $val_qas variable whenever possible, as it is the safest one from the mentioned alternatives. A very useful and favourite usage of the ['sqlw'] option is to explicitly tell &name; to store a NULL value instead of an empty string for the particular column. Empty string and NULL are two different values. Many people really do not like empty strings in their tables, thus now they have possibility to change them to NULL when user simply enters nothing into form input field. Another example of the ['sqlw'] 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 col_name value was not changed, then do not apply MD5() on it. If col_name value was changed, then apply MD5() function. PHP feature allows user to display any HTML code in place of a value. Behavior is the same as in triggers. 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. operation == $this->labels['Add']) { return 'add mode selected'; } else { return ''; } ?> ]]> This option is indended for advanced usage. Together with pre and before triggers, it allows tweaking the core class without the need to hack it. To change input, use before triggers or ['sqlw'] option. Because the TABs feature is one of the most important &name; features, it deserves its own documentation section. Tabbed groups of fields appear in specific page modes: Add, Change, coPy, View, or Delete. In List mode, when TAB settings are combined with , users can suppress the display of fields below the first TAB group. 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 ['navigation'] settings. TAB has its own label, which can describe fields in a particular group. 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. TAB definition is very simple. Just define the label on the TAB (1st field, 5th field, 10th field, and so on). There is also possibility to define the default TAB. In this case, the array style initialization is required. 'Personal data', 'default' => true ); ]]> In List mode, to initially display individual fields from only the first TAB group, apply to all fields below the first TAB group, for example: For users with non-compliant JavaScript browsers, you can turn TABs feature off. The general control is achieved via $opts['display']['tabs'] variable. If not specified, its value is considered as true. Variable $opts['display'] is described in sebsection. 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. 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. A good example for this is the ['trimlen'] option. Imagine you set something like this: This will trim the maximum length of text to 30 characters on all possible pages, which in this case are: table list table filter record view record delete 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. 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 ['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. Each restriction letter stands for particular page type. They are the same as those described in list under subsection.