Use setData() method of your form object. Give it your control name as first argument and its value as second.

  $form->setData("firstname","Laurent");

You can of course, retrieve value from a dao, a business class or anything else.

If you retrieve values from a dao, there is a more efficient way to fill your form. initFromDao() method allows to fill multiple form fields. Indicate a dao selector as first argument. The second argument should be the value of the primary key of the record to retrieve, if the id of the form doesn't correspond to this key (the key value can be an array of values if the primary key is on several fields). So if you don't indicate a key, the id of the form will be took as the key.

   $form = jForms::create("shop~product", $product_id);
   $form->initFromDao("shop~products");

Form will be filled with values of the record whose id is $product_id in "shop~products" dao. You can also indicate a record object to initFromDao() instead of a selector.

However, note that only controls whose name (or ref) are the same as dao properties will be pre-filled. Others will stay untouched.

You could use more than one dao to fill your fields. Your form fields could correspond to multiple tables in database for example.

<checkboxes> and <listbox multiple="true"> controls could be filled with more than one value. (Beware, here we talk about values to be pre-selected and not the list if choices label).

You can still use setData() by giving an array of values to pre-select:

    $form->setData('categories', array(5, 8, 10));

But, commonly, those value lists reside in database and are retrieve from a join statement. ie. a table having as primary key two or more foreign keys. Each foreign key being a primary key of a different table. Imagine a table for products ('products'), a table for product categories ('categories'), and a product can belong to more than one category, you will construct a join table ('products_categories'), associating product keys and category keys (product_id and category_id).

If you want to fill your listbox or your checkboxes, you should read from 'products_categories' table. jForms provide a method on your form object to achieve this initControlFromDao():

   $form->initControlFromDao("categories", "shop~products_categories");

Of course, you should before define a "shop~products_categories" dao. jForms expects as first dao key the one identifying a product and as second one the one identifying a category. Even if it is not the case, you could give an array fo key names as third arg to initControlFromDao():

   $form->initControlFromDao("categories", "shop~products_categories", array('product_id','category_id'));

Note that this example is an edit product form. Here we assume that the form id corresponds to a product id and as so initControlFromDao() will use it as search criteria to retrieve category id.

In jforms xml file, we have documented several ways to populate choices of a <menulist>, a <listbox>, a <radiobuttons> or a <checkboxes> controls (static data, dao, class).

Those could still be unsufficient. In that situation, declare neither <item> tag nor dao* or class attribute in you XML file. In your controller, define your choices as follow:

   // retrieve your choices in an associative array,
   $data = array(...);
   
   // create an object that implement jIFormsDatasource2
   $datasource = new jFormsStaticDatasource();
   $datasource->data = $data
   
   // retrieve the control and assign data
   $form->getControl('control_name')->datasource = $datasource;

In $data, keys should be value of choices and values should be label of choices.

Note : you should do this in "show" action, ie. action that display your form.

There are situations where you do not want to display some controls of your form. Use deactivate() and isActivated(). Those two methods expect a control name as argument. The latter return true if the control is activated. It is useful for checking a submitted form. The first one activate or deactivate a control. It accepts an optional parameter indicating whether to deactivate (if true) or activate (if false).

   $form->deactivate('control_name');
   // similar to
   $form->deactivate('control_name', true);

   // and to re-activate it :
   $form->deactivate('control_name', false);

   // check a control state :
   if ($form->isActivated('control_name')) ...
    

The deactivation is the preferred method, because it is simpler, and by reading the XML file, you know all used controls.

However, in some case you need to add several controls, for exemple repeated controls, depending of external values. For example, in a form dedicated to a news article, when you modify it, you would like to add an input for each label of photos attached to this article. So you would add a control for each label, depending of the number of photos.

In this kind of case, you have to instancy some new controls by hand, and add them to the form, before to manipulate it in each action:

• retrieve the form with jForms::get() or jForms::create() (but not jForms::fill(), see below)
• instancy an object which inherits from jFormsControl. There is a class for each type of controls: jFormsControlInput, jFormsControlListbox, jFormsControlRadiobuttons, jFormsControlHtmlEditor, etc. See the full list in the reference documentation.
• add this object to the form object, with the addControl method, or the addControlBefore method to add the control after a specific one.
• you can then display the form, or fill it with data of the request, by using initFromRequest().

You have to add these fields each time you create or retrieve the form. Indeed, each time you retrieve the form with jForms::get() or jForms::fill(), jForms always instancy the form object generated by jForms from what it is described in the XML file. So the form object doesn't contain your fields. That's why you have to add your fields before the display, but also before the retrieval of submitted data, so jForms know which data to retrieve.

1 – adding a field during the initialization:

  $form = jForms::get('myModule~myForm');
  $ctrl= new jFormsControlinput('identifiant');
  $ctrl->required=true;
  $ctrl->datatype->addFacet('maxLength',255);
  $ctrl->label='Identifiant';
  $ctrl->size=100;
  $form->addControl($ctrl);

2 – adding a field after the form submit :

  $form = jForms::get('myModule~myForm');
  $ctrl= new jFormsControlinput('identifiant');
  $ctrl->required=true;
  $ctrl->datatype->addFacet('maxLength',255);
  $ctrl->label='Identifiant';
  $ctrl->size=100;
  $form->addControl($ctrl);
  $form->initFromRequest();

You can put the code which add the field, into a private method of your controller, so you don't have to duplicate it in each action you use the form.

• *Warning** : you mustn't use the fill() method, because this method do a get() followed immediately by initFromRequest(), so it doesn't give you the opportunity to add your field before the retrieval of data. If you call it, your field won't receive corresponding data.

3 - During the dynamic fill of a control

If the form contain a list depending on an other control, a http request is made to the jforms controller to fill this list.

During this action, the controller emit an event jformsPrepareToFillDynamicList before to generate the list content and to return it to the browser. This event allow to prepare the form object with all expected controls.

The event has these parameters:

• form: the form object.
• controlRef: the id of the control containing the list that will be generated.