ullMetaWidget: how to add a new widget / field type

Introduction

ullMetaWidgets are an extension of symfony's sfForm widgets. They are mainly used for ullGenerators.

Currently the type of database column is one of integer, string, date, etc. The idea behind ullMetaWidget is to provide field types on a higher level like e.g. 'email'.

Each ullMetaWidget holds the information and logic to handle all usecases for a field.

Example for ullMetaWidgetEmail:

• A "read" widget for read-only display of the field value. For type email it would automatically provide a clickable mailto: link for the email address.
• A "edit" widget, in this case a simple <input type='text' /> tag
• Validators, in this case a check if it is a valid email address

Usage

Example for ullTableToolGenerator.

Configure a ullMetaWidget for a database table column:

• Log in as administrator
• Go to "Admin" -> "TableTool" -> "Manage column configuration"
• Edit or create a new entry for the desired column:
  • Table name: name of the database table, use the model class name of the doctrine schema, e.g. "UllUser" for table "ull_user"
  • Column name: name of the column, e.g. "office_email"
  • Type: the ullMetaWidget, e.g. "email"
  • Options: some ullMetaWidgets require additional options. Refer to the class file for reference.
  • Enabled: generally en- or disables a column
  • Show in List: display the column in list view
  • Label: Name of the column for the table header e.g "Office email address"
  • Description: a longer description of the column "Use only for business contacts"

Develop a new ullMetaWidget

Example: we create a ullMetaWidgetEmail

• Create a new ullMetaWidgetEmail.class.php file. It's a good idea to copy an existing ullMetaWidget from plugins/ullCore/lib/form/widget
• A "$columnConfig" parameter is passed to ullMetaWidget upon construction. It contains a lot of information about the current column. The options form UllColumnConfig are in $columnConfig['widgetOptions'].
• Each ullMetaWidget contains a simple __construct() method which does the following things:
  
  • Check for mandatory options (optional)
  • Process options (optional)
  • Set a sfWidget for the "edit" mode:
    
    • Example: sfWidgetFormInput
  • Set a sfValidator for the "edit" mode:
    • Example: sfValidatorEmail
  • Set a sfWidget for the "read" mode:
    • There is no existing widget for the read mode, so we write or own "ullWidgetEmail", extending "ullWidget".
      In ullWidget we simply generate a html link for the email address.
      See "ullWidget" for futher reference.
  • A validator for the "read" mode doesn't make much sense, but is required by sfForm. Always set it to "sfValidatorPass".
• Don't forget to add a unit test for your new widgets. See test/unit/ullTableTool/ for reference.
• Add an entry for your new widget to UllFieldType (Admin -> Manage field types)
• Configure your new widget as described in section "Usage" above.

 Guidelines for ullCore developers

• Don't use ullTableTool to add configurations to UllColumnConfig, UllFieldType, etc. Instead use the ullCore fixture file in plugins/ullCore/data/ullCoreFixtures.yml
• Besides the mandatory unit tests for each ullMetaWidget and ullWidget, we also test it using a functional test using ullTableTool with table "TestTable":
  
  • Edit plugins/ullCore/config/doctrine/ullTableToolSchema.yml
    • Add a new column to "TestTable" before "my_useless_column".
    • Name the column 'my_XXX' where XXX stands for the field type, e.g. "email".
  • Add testdata for the new column to plugins/ullCore/data/ullCoreFixtures.yml under "TestTable"
  • Add configuration in UllColumnConfig for TestTable
  • Extend the ullTableTool functional test 'test/functional/frontend/ullCorePlugin/ullTableToolTest.php' 
    • Note: You'll have to fix some selectors because of the added column

Ideas / Limitations

• ullMetaWidget can add multiple form fields, eg. the "password again" field for the password metaWidget.
  But each added form field is rendered in the default way by "echo $form" - each in a new row.
• It shell be possible to render multiple form fields in one row. Example: select or create for foreign keys