multimodelform

This extension allows to work with multiple records and different models in a edit form. It handles clientside cloning and removing input elements/fieldsets and serverside batchInsert/Update/Delete.

Creating forms with this functionality is a 'tricky' workaround in views and controllers. This widget should do the main part of the work for you. It can be useful for order/registration forms ...

See:

• Tutorial Collecting Tabular Input
• Comments at the extension jqrelcopy
• Forum comment on jqrelcopy

'multimodelform' could be an updated version of my extension jqrelcopy, but because of the different approach jqrelcopy will stay as lightweight extension for other needs. If you don't have to work with models take a look at jqrelcopy.

Note ¶

Not every form input element is supported.

You can use the a few basic CFormInputElement (text, textarea, dropdownlist, ...) and some widgets (CJuiDatePicker, see below) but at the moment

• checkbox: you have to use a checkboxlist instead (see below and the demo.3.2)
• Autocomplete ...

are not supported.

Features ¶

• Clientside Clone/Remove form elements / fieldsets with the jQuery plugin http://www.andresvidal.com/labs/relcopy.html
• Simple handling of the submitted form data in the controllers create/update action
• Simultanous editing multiple records and models (master/detail...)
• Supports validation and error summary for each model/record
• Autogenerating input form elements with the 'form builder' functionality of Yii

New since v2.0

• tableView (= gridView)
• Support for cloning widget form elements: CJuiDatePicker, extension datetimepicker

Imporant note when upgrading to v2.1

• MultiModelForm::validate and MultiModelForm::save have now the same parameterlist, so you have to add 'deletedItems' as third parameter (see Usage Validate/Save)

MultiModelForm::save($model,$validatedItems,$deleteItems,$masterValues)

Requirements ¶

• Yii 1.1.6+

Usage ¶

• Extract the files under .../protected/extensions

• Master/Detail example:

Assume you have two models 'group' (id, title) and 'member' (id, groupid, firstname,lastname,membersince). The id attribute is the autoincrement primary key.

• Generate the models 'Group' and 'Member' with gii. For testing the error summary set the members firstname/lastname as required in the rules.

• Generate the 'GroupController' and the group/views with gii. You don't need to create a 'MemberController' and the member views for this example.

• Change the default actionUpdate of the GroupController to

public function actionUpdate($id)
{
    Yii::import('ext.multimodelform.MultiModelForm');
 
    $model=$this->loadModel($id); //the Group model
 
    $member = new Member;
    $validatedMembers = array(); //ensure an empty array
 
    if(isset($_POST['Group']))
    {
        $model->attributes=$_POST['Group'];
 
        //the value for the foreign key 'groupid'
        $masterValues = array ('groupid'=>$model->id);
 
        if( //Save the master model after saving valid members
            MultiModelForm::save($member,$validatedMembers,$deleteMembers,$masterValues) &&
            $model->save()
           )
                $this->redirect(array('view','id'=>$model->id));
    }
 
    $this->render('update',array(
        'model'=>$model,
        //submit the member and validatedItems to the widget in the edit form
        'member'=>$member,
        'validatedMembers' => $validatedMembers,
    ));
}

• Change the code of actionCreate like this

public function actionCreate()
{
    Yii::import('ext.multimodelform.MultiModelForm');
 
    $model = new Group;
 
    $member = new Member;
    $validatedMembers = array();  //ensure an empty array
 
    if(isset($_POST['Group']))
    {
        $model->attributes=$_POST['Group'];
 
        if( //validate detail before saving the master
            MultiModelForm::validate($member,$validatedMembers,$deleteItems) &&
            $model->save()
           )
           {
             //the value for the foreign key 'groupid'
             $masterValues = array ('groupid'=>$model->id);
             if (MultiModelForm::save($member,$validatedMembers,$deleteMembers,$masterValues))
                $this->redirect(array('view','id'=>$model->id));
            }
    }
 
    $this->render('create',array(
        'model'=>$model,
        //submit the member and validatedItems to the widget in the edit form
        'member'=>$member,
        'validatedMembers' => $validatedMembers,
    ));
}

• Change the renderPartial in views/group/create.php and update.php to transfer the parameters $member and $validatedMembers to the _form.php

echo $this->renderPartial('_form', array('model'=>$model,
                          'member'=>$member,'validatedMembers'=>$validatedMembers));

• Change the generated code of the GroupController's form view (views/group/_form.php).

<div class="form wide">
 
<?php $form=$this->beginWidget('CActiveForm', array(
        'id'=>'group-form',
        'enableAjaxValidation'=>false,
)); ?>
 
<p class="note">Fields with <span class="required">*</span> are required.</p>
 
<?php
    //show errorsummary at the top for all models
    //build an array of all models to check
    echo $form->errorSummary(array_merge(array($model),$validatedMembers));
?>
 
<div class="row">
    <?php echo $form->labelEx($model,'title'); ?>
    <?php echo $form->textField($model,'title'); ?>
    <?php echo $form->error($model,'title'); ?>
</div>
 
<?php
 
// see http://www.yiiframework.com/doc/guide/1.1/en/form.table
// Note: Can be a route to a config file too,
//       or create a method 'getMultiModelForm()' in the member model
 
$memberFormConfig = array(
      'elements'=>array(
        'firstname'=>array(
            'type'=>'text',
            'maxlength'=>40,
        ),
        'lastname'=>array(
            'type'=>'text',
            'maxlength'=>40,
        ),
        'membersince'=>array(
            'type'=>'dropdownlist',
            //it is important to add an empty item because of new records
            'items'=>array(''=>'-',2009=>2009,2010=>2010,2011=>2011,),
        ),
    ));
 
$this->widget('ext.multimodelform.MultiModelForm',array(
        'id' => 'id_member', //the unique widget id
        'formConfig' => $memberFormConfig, //the form configuration array
        'model' => $member, //instance of the form model
 
        //if submitted not empty from the controller,
        //the form will be rendered with validation errors
        'validatedItems' => $validatedMembers,
 
        //array of member instances loaded from db
        'data' => $member->findAll('groupid=:groupId', array(':groupId'=>$model->id)),
    ));
?>
 
<div class="row buttons">
    <?php echo CHtml::submitButton($model->isNewRecord ? 'Create' : 'Save'); ?>
</div>
 
<?php $this->endWidget(); ?>
 
</div><!-- form -->

Usage Validate/Save ¶

The behavior has changed in v2.1. In older versions 'save' always exceuted 'validate' internally. 'validate' means to recreate all items from the form data. So there was no chance to alter the attributes of the models in $validatedItems between calling 'validate' and 'save'.

No you can do something like this.

//validate formdata and populate $validatedItems/$deleteItems
if (MultiModelForm::validate($model,$validatedItems,$deleteItems,$masterValues)) 
{
 
 //... alter the model attributes of $validatedItems if you need ... 
 
 //will not execute internally validate again, because $validatedItems/$deleteItems are not empty
 MultiModelForm::save($model,$validatedItems,$deleteItems,$masterValues);
}

But you can still use 'save' without extra validate before. Validation will be internally done when $validatedItems/$deleteItems are empty.

$validatedItems=array();
 
if(isset($_POST['FORMDATA']) && MultiModelForm::save($model,$validatedItems,$deleteItems,$masterValues)) 
{
  //... validation and saving is ok ...
  //redirect ...
}
 
//No POST data or validation error on save 
$this->render ...

Usage tableView ¶

Set the property 'tableView'=>true.

$this->widget('ext.multimodelform.MultiModelForm',array(
       ...
        'tableView' => true,
     //'tableFootCells' => array('footerCol1','footerCol2'...), //optional table footer
       ...
    ));

Usage widget form elements ¶

Yii allows type='AWidget' as form element. So in your form config array you can use:

array( 
   'elements'=>array(
         ....
          'lastname'=>array(
            'type'=>'text',
            'maxlength'=>40,
            ),
 
            'dayofbirth'=>array(              
                'type'=>'zii.widgets.jui.CJuiDatePicker',
                'language'=>'de',
                'options'=>array(
                    'showAnim'=>'fold',
                ),
           ...                      
        )
    )

This however needs a javascript workaround on cloning the date element. We have to assign the CJuiDatePicker functionality to the cloned new element.

Since v2.0 there are the properties jsBeforeClone,jsAfterClone,jsBeforeNewId,jsAfterNewId available where javascript code can be implemented. Use 'this' as the current jQuery object.

For CJuiDatePicker and the extension extension datetimepicker there are predefined functions available, so it's easy to make cloning date fields work.

You have to assign the property 'jsAfterNewId' to the prepared code.

Assume your form definition elements are defined in the array $formConfig. 'afterNewIdDatePicker' reads the options from the specified element and adds the 'datepicker':

$this->widget('ext.multimodelform.MultiModelForm',array(
       ...
         // 'jsBeforeNewId' => "alert(this.attr('id'));", 
        'jsAfterNewId' => MultiModelForm::afterNewIdDatePicker($formConfig['elements']['dayofbirth']),
       ...
    ));

Now cloning of the field 'dayofbirth' should work.

Support for 'datetimepicker' is analog (afterNewIdDateTimePicker).

For other widgets you have to find out the correct javascript code on cloning. Please let me know if you have found a javascript code for other widgets.

Note: I couldn't get Autocomplete working. Maybe one of you has an idea (see afterNewIdAutoComplete in MultiModelForm.php).

Sortable fieldsets (since v3.0) ¶

Set the property 'sortAttribute' to your db-field for sorting (should be an integer) if you want to order the items by drag/drop manually. Uses jQuery UI sortable, but works only when 'tableView' is false. See the demo.

$this->widget('ext.multimodelform.MultiModelForm',array(
       ...
        'sortAttribute' => 'position', //if assigned: sortable fieldsets is enabled
       ...
    ));

Property showAddItemOnError (since v3.0) ¶

Regarding to requests and workarounds in the forum topic:

A user should not be able to add/clone items, when in error mode (model rules not passed successfully). Now you can set the property $showAddItemOnError to false to enable this behavior. See the demo.

Properties allowAddItem and allowRemoveItem (since v3.1) ¶

For example, if you only want to allow an admin user to add new items or remove items, you can use these properties to display the addlink and the removelinks

$this->widget('ext.multimodelform.MultiModelForm',array(
       ...
       'allowAddItem' => Yii::app()->user->isAdmin(),
       'allowRemoveItem' => Yii::app()->user->hasRole('admin'),
       ...
    ));

Checkboxes ¶

Unfortunatly the basic checkbox is not supported, because it's not so easy to handle (see the comments in the forum).

But if you need checkboxes, you can use the checkboxlist - see the demo.3.2 If you only need a single checkbox you can set the item-data to an array with one item.

In the view / formConfig:

$memberFormConfig = array(
          'elements'=>array(
 
             ...
            'flags'=>array(
              'type'=>'checkboxlist',
              'items'=>array('1'=>'Founder','2'=>'Developer','3'=>'Marketing'), //One single checkbox: array('1'=>'Founder')
              ),
        ));

In the model you have to convert array <-> string on saving/loading - see the Member model in the demo

/*
     * Convert the flags array to string
     */
    public function beforeSave()
    {
        if(parent::beforeSave())
        {
            if(!empty($this->flags) && is_array($this->flags))
                $this->flags = implode(',',$this->flags);
 
            return true;
        }
 
        return false;
    }
 
   /*
    * Convert the flags string to array
    */
   public function afterFind()
   {
       $this->flags = empty($this->flags) ? array() : explode(',',$this->flags);
   }

Notes ¶

• Take a look at MultiModelForm.php for more options of the widget.

• The widget never will render a form begin/end tag. So you have always to add $this->beginWidget('CActiveForm',...) ... $this->endWidget in the view.

• The implementation of the class MultiModelEmbeddedForm needs review in upcoming Yii releases. In 1.1.6+ the only output of CActiveForm.init() and CActiveForm.run() is the form begin and end tag.

• The extension should work for non activerecord models too: instances of CModel, CFormModel...

• You can add more widgets for rendering other models in the form view. Take care to assign a unique widget id when adding more multimodelform widgets.

• Use Yii::app()->controller->action->id or $model->scenario to generate different forms for your needs (readonly fields on update ...)

Ressources ¶

• Forum topic multimodelform/jqrelcopy

• Tutorial Using Form Builder

• jQuery plugin RelCopy

Changelog ¶

• v3.3
  • Correct support for the options['limit'] property from relcopy.js. See property limitText.
• v3.2
  • New property 'hideCopyTemplate' (default:true), means that the empty copyTemplate is not visible
  • New demo with CheckBoxList
• v3.1
  • New: Added properties $allowAddItem and $allowRemoveItem
  • Bugfix: hidden fields in the Tableheader no more displayed
  • Bugfix: Strings as elements formconfig (htmlttags,CFormStringElement) have not been rendered

• v3.0

  • New: Added sortable feature for fieldsets (not in table view)
  • New: Property $showAddItemOnError=true; Show 'Add item' link and empty item in errormode
  • New: Demo with sortable fieldsets
  • Bugfixes: visible/hidden fields

• v2.2.1 Bugfix: Array elements need extra 'allEmpty' check 

• v2.2
  • Support for array elements (checkboxlist, radiolist) in form config These elements didn't work on creating only on update
• v2.1.1
  • Bugfix - Labels of hidden elements have been rendered
• v2.1
  • Bugfix - tableView: Hidden input have been rendered into a cell
  • Changed parameters and handling of MultiModelForm::save
• v2.0.1 Bugfix: Tableheader displayed hidden fields too. Better internal handling of labels, now supports required '*'
• v2.0 Added 'tableView' and support for cloning date/time widgets
• v1.0.2 Bugfix: Detailrecord was created twice on creating master
• v1.0.1 Bugfix 'Undefined Index','Undefined variable' when error_reporting(E_ALL) is set