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:

<?xml version="1.0"?>
<dbform:form xmlns:dbform="http://bitflux.org/dbforms2/1.0">


    <dbform:fields table="blogposts">
        <dbform:field name="post_title" type="text" descr="Title"/>
        <dbform:field name="post_content" type="text_wysiwyg" isxml="true" descr="Content"/>
    </dbform:fields>


    <dbform:chooser namefield="concat( post_title )" wherefields="post_title" 

     orderby="post_title ASC" limit="35"/>


</dbform:form>

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/

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="$
  Unknown macro: {userid}
  " for the logged in user id).

Basic Field Types

hidden

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

<dbform:field name="id" type="hidden"/>

fixed

FIXME: Looks like this one is broken.

text

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

<dbform:field name="post_title" type="text" descr="Title"/>

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.

<dbform:field name="post_uri" type="text_uri" descr="URI"/>

text_area

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

<dbform:field name="post_content" type="text_area" descr="Content" isxml="true"/>

text_area_small

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

<dbform:field name="post_content" type="text_area_small" descr="Content" isxml="true"/>

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.

<dbform:field name="post_content" type="text_wysiwyg" descr="Content" isxml="true"/>

checkbox

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

<dbform:field name="published" type="checkbox" descr="Published" default="1"/>

date

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

<dbform:field name="post_date" type="date" descr="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.

<dbform:field name="bgcolor" type="color" descr="Background Color"/>

select

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

<dbform:field name="post_comment_mode" type="select" descr="Comment Mode" default="3">

    <dbform:value name="1">Allow comments for 1 month</dbform:value>
    <dbform:value name="2">Always allow comments</dbform:value>
    <dbform:value name="3">No comments allowed</dbform:value>

</dbform:field>

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.

<dbform:field name="bloglinkscategories" descr="Category" type="select">

    <dbform:datasource type="foreign" table="bloglinkscategories" order="rang" 
    namefield="name" orderby="rang" idfield="id"/>

</dbform:field>

select with data from pagetree

Example:

<dbform:field name="uri" descr="URI" type="select" default="">
            <dbform:datasource type="pagetree" subtree="/produkte/"></dbform:datasource>
        </dbform:field>

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.

<dbform:field name="image_fileref" type="file_browser" isImage="true" descr="Image"/>

nofield_html and nofield_text

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

<dbform:nofield type="text" descr="here a text"/>

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

<dbform:nofield name="nofieldtest" type="html" descr="foo">
    <value>
<![CDATA[
<a href="#" onclick="return doSomething()">do Something</a>
]]></value>
</dbform:nofield>

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

  <dbform:field 
  
      name="post_category"
      type="relation_n2m" 
      relationtable="blogposts2categories" 
      thisidfield="blogposts_id"
      thatidfield="blogcategories_id"
      descr="Category">
      
      <dbform:datasource type="foreign" namefield="fullname" idfield="id" table="blogcategories" order="l"/>
      <dbform:liveselect namefield="fullname" idfield="id" wherefields="fullname,fulluri" 
       table="blogcategories" orderby="l" limit="35"/>
  
  </dbform:field>

Groups

Group support is currently broken.

Subforms

Subforms support is fully implemented but not yet documented.

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:

<dbform:chooser namefield="post_title" wherefields="post_title" orderby="post_title ASC"/>

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:

<dbform:eventhandler event="update_pre" type="php" handler="update_pre1"/>
    <dbform:eventhandler event="update_pre" type="php" handler="update_pre2"/>
    <dbform:eventhandler event="update_post" type="php" handler="foo::update_post"/>

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:

  DBFORMS2_DEBUGLOG_ENABLED = true;