Skip to end of metadata
Go to start of metadata

toc

Introduction

DBForms2 is a small application integrated into FluxCMS which can be used to edit database content in a very comfortable way. Only a single XML-file is required to configure a form.

Form Configuration

To generate a new form drop the corresponding configuration file into the dbforms2/ directory of your installation root. The form can then be accessed via /admin/dbforms2/<formname>.

Example of minimal form configuration file for editing the blogposts table:

This form can already be used to edit the table holding your blog posts. If the name of the configuration file for this form was /dbforms2/myform1.xml the corresponding form would be accessed through /admin/dbforms2/myform1/

Form title

To add a visible title to your form, use the title attribute in the form tag

Table prefix

To change the table prefix to something different than the globally configured value, use the tablePrefix attribute in the fields tag

General Field Attributes

  • name: Name of the field in the database
  • type: Type of the field
  • descr: Description shown on the left side of the field (default: empty)
  • disabled: Whether the field should be disabled or not (default: false, doesn't work for all field types, because it's based on the xhtml "disabled" attribute)
  • default: A default value (default="${userid}" for the logged in user id).

Basic Field Types

hidden

Same as in HTML: a field which has a value but is invisible.

fixed

FIXME: Looks like this one is broken.

text

A simple text field. Same as <input type="text"/> in HTML.

text_uri

Used to guarantee that an uri is unique. When a similar uri already exists, a new one is created by appending a number.

text_area

A text area like <textarea/> in HTML. The default size is 12 rows and 80 columns.

text_area_small

Basically the same as text_area but with fever rows. Default size is 3 rows and 80 columns.

text_wysiwyg

A Field featuring a complete XHTML wysiwyg editor. Use this field type to let a user enter advanced text with formatting, tables, images etc.

  • height: Optional attribute for a special height (be aware that the editor menu will use 30px of this). Default height is 150px.

checkbox

Generates a simple checkbox which can be toggled on or off.

date

This field has a button which pops up a small calendar when triggered. Use this to let a user select a date.

date_time

Mainly the same as date but it let's you edit the time after you selected the date (for mysql type "datetime")

date_timeutc

Document me (difference to date_time?)

date_created

Date field which is automatically updated when a new record is created.

date_changed

Date field which is automatically updated when a record is saved.

password_md5

Document me

color

A color picker to let the user select a color from a palette. The color itself is returned as a hex value.

select

Generates a dropdown element from which the user can select exactly one item. Use value nodes or a data source to generate items.

The following example uses a data sources to generate the items for the dropdown. The datasource queries the table bloglinkscategories to generate entries in the dropdown. The id of the selected category is stored in the field called bloglinkscategories. This construct can be used to edit simple one-to-many relations.

select with data from pagetree

Example:

select with data from pagetree with UID (unique collection ID)

Example:

select from all langs avaible

Example:

file

A field type which allows the user to upload files to a specified directory.

Note: This file type is deprecated, use file_browser instead.

file_browser

Use this field type to let the user select a file from the /files/ directory of the FluxCMS webroot. File_browser features a small preview image when the attribute isImage is set to true and a tooltip with a larger preview which is shown when the mouse is moved over the small preview.

File paths returned are relative to BX_WEBROOT.

nofield_html and nofield_text

writes the text in @descr into the form in bold:

writes html code into the form (the CDATA is important ):

Advanced Field Types

relation_n2m

This field type is used to manage many-to-many relations. It needs a datasource and a liveselect node.

The following example shows how to use this field type to assign blog categories to a blogpost. Three tables are involved here:

  • blogposts: The main table which is being edited
  • blogcategories: The category which stores all available blog categories
  • blogposts2categories: The relation table which stores blogposts to blogcategories assignements

Groups

Group support is currently broken.

Subforms

Subforms support is fully implemented.

The following example show how to use subforms to assign book title/summary in differents languages to one book entity.
So the involved tables are:

  • books: the main table which is being edited
  • books_content: the table which stores all the title/summary translations of every book
  • languages: the table from where we build the select field (which contains the languages)

The Chooser

The chooser is used to select a specific record from the database to be edited. It is configured using a separate node in the configuration file.

A simple chooser which shows only the post's title:

Live Select

The chooser has a special features called live select which allows the user to enter a search term in the textbox. The chooser queries the database for records matching the term and updates the chooser items accordingly. In the above example the column post_title is queried for matches.

Config Attributes

  • namefield: The name of the field which is shown as the title of the item. Use concat() or other SQL functions to select text from more than one field.
  • wherefields: Comma delimited list of the names of the fields which are queried for the search term.
  • where: Use this to apply a custom WHERE condition to the SQL query. Standard SQL syntax
  • limit: Maximum number of items which will be shown in the chooser.
  • orderby: Used to sort the entries in the chooser. Standard SQL syntax.
  • getmatcher: Used to synchronize a query to a specific GET variable. Only applied if the respective GET variable is not empty
  • notnullfields: Comma delimited list of the names of fields which mustn't be NULL (!= 'NULL')
  • leftjoin: Use this attribute to allow other tables to join your query. Standard SQL syntax.

Use {tablePrefix} in the fields namefield, where, orderby and leftjoin to automatically insert the currently configured table prefix.

Client- And Server-Side Event Handlers (1.5+ only)

To define server-side event handlers use the following syntax:

Config Attributes

  • event: The type of the event you want the handler to be registered for. See below for a complete list of currently supported events.
  • type: Type of handler. This must either be 'php' or 'js'
  • handler: The handler to be called on occurence of the event. This might be a the name of a global function or the name of a static method of a class.

Note: <eventhandler/> must be a child of the form node.

Note: client-side handlers (type='js') are not yet implemented. Use the onsavejs and onloadjs attributes instead.

Supported events are:

  • select_pre
  • select_post
  • insert_pre
  • insert_post
  • update_pre
  • update_post
  • delete_pre
  • delete_post

Troubleshooting

If you happen to have problems with a form here are some tips:

  • Watch your apache errorlog for errors
  • Most problems are caused by incorrect SQL syntax or wrong table or column names, so first check whether your queries are correct. See the list below for an idea where to start.
  • Check these URL for errors:
    • /admin/dbforms2/myform/chhooser/?q= (Chooser output)
    • /admin/dbforms2/myform/?XML=1.1 (Raw form, XML, before first XSL transformation)
    • /admin/dbforms2/myform/?XML=1 (Raw form, XHTML, after first XSL transformation)
  • If you have Firebug installed, you can watch what's going on inside DBForms2 by setting the following in /webinc/plugins/dbforms2/dbforms2.js: