This widget makes the text string which can be edited by clicking on it and entering new value, using either popup or inline text field. This can be used to make quasi-interactive documents containing placeholders, for example.

Simplest possible usage of the widget is this:

$this->widget(
    'booster.widgets.TbEditableField',
    array(
        'type' => 'text',
        'model' => $model,
        'attribute' => 'name', // $model->name will be editable
        'url' => $endpoint, //url for submit data
    )
);

Note In this example we are using the Region ActiveRecord class which is backed by real table in our DB. Records are fetched randomly (try reloading this page).

Hint Try opening the Development Tools in your browser and look what request are being sent when you edit the value and press "OK".

For simplicity, you can think that $model widget config parameter accepts just the CActiveRecord instances loaded with data about some existing database record. But if you don't need or want to use CActiveRecord check out the section Forging objects to be made editable below.

Here is all parameters you can pass when creating the TbEditableField widget instance.

'validate' => 'js: function(value) {
  if ($.trim(value) == "") 
    return "This field is required";
}'

'success' => 'js: function(response, newValue) {
  if (!response.success) 
    return response.msg;
}'

'display' => 'js: function(value, sourceData) {
  var escapedValue = $("<div>").text(value).html();
  $(this).html("<b>" + escapedValue + "</b>")
}'

'onInit' => 'js: function(event, editable) {
  console.debug("X-Editable field " + editable.options.name + " ready to serve.");
}'

'onShown' => 'js: function(event) {
  var tip = $(this).data("editableContainer").tip();
  tip.find("input").val("overwriting value of input.");}'

'onHidden' => 'js: function(event, reason) {
  if (reason === "save" || reason === "cancel") {
    // auto-open next editable
    $(this).closest("tr").next().find(".editable").editable("show");
  }
}'

'onSave' => 'js: function(event, params) {
  console.debug("Saved value: " + params.newValue);
}'

Here will be presented some examples of Editable Field usage.

Note This time to speed things up no real ActiveRecords bound to database tables will be used. All models are fake in-memory ones, as described in "Faking" section below.

Text

$this->widget('booster.widgets.TbEditableField', array(
    'type' => 'text',
    'model' => $model,
    'attribute' => 'someStringAttribute',
    'url' => $endpoint, //url for submit data
));

Textarea

$this->widget('booster.widgets.TbEditableField', array(
    'type' => 'textarea',
    'model' => $model,
    'attribute' => 'someLongStringAttribute',
    'url' => $endpoint, //url for submit data
    'placement' => 'right'
));

Select

$this->widget('booster.widgets.TbEditableField', array(
    'type' => 'select2',
    'model' => $model,
    'attribute' => 'someEnumerableAttribute',
    'url' => $endpoint, //url for submit data
    'source' => array('Choose', 'your', 'destiny', '.')
));

Date

$this->widget(
    'booster.widgets.TbEditableField',
    array(
        'type' => 'date',
        'model' => $model,
        'attribute' => 'someDateAttribute',
        'url' => $endpoint, //url for submit data
        'placement' => 'right',
        'format' => 'yyyy-mm-dd',
        'viewformat' => 'mm/dd/yyyy',
        'options' => array(
            'datepicker' => array(
                'language' => 'ru'
            )
        )
    )
);

Note As you probably can see, even if Editable Field has language explicitly declared, its datepicker is still in English. This is a known bug and it'll be resolved one day.

This widget is designed to work with CActiveRecord descendant class instances, but in fact any CModel inheritors will do. Here's the strict requirements for the model passed as $model in the example above:

• It should be "not new", i. e., it should have a property named isNewRecord having the value of false.
• It should have primary key defined which has a non-empty value, i. e:
  • It should have some attribute like id which should hold the value of primary key.
  • It should have a primaryKey attribute holding the name of this "primary key" attribute.
• It should have a isAttributeSafe method which returns true when passed the name of the attribute in question.
• It should have a getAttributeLabel method which returns some human-readable label for the name of the attribute in question.

So, here's the example usage of complete fake which will be accepted by the TbEditableField widget:

class FakeActiveRecord
{
    public $isNewRecord = false;
    public $primaryKey = 'myid';
    public $myid;
    public $myattr;

    public function isAttributeSafe()
    {
        return true;
    }

    public function getAttributeLabel()
    {
        return 'Text Field';
    }
    
    public function getScenario() {
    	return 'update';
    }
}

$model = new FakeActiveRecord;
$model->myid = 1;
$model->myattr = 'Lorem Ipsum!';

$this->widget(
    'booster.widgets.TbEditableField',
    array(
        'type' => 'text',
        'model' => $model,
        'attribute' => 'myattr',
        'url' => $endpoint, //url for submit data
    )
);

Important If you are going to fake editable fields of types select2, select, date, dateui, checklist or combodate, you will have to fake an additional method: getAttribute($attr). It should return the value of the $attr attribute.

Important If you not set the type property of this widget at all or deliberately set it to null, this widget will try to guess the type based on the metadata of the DB column. You will end up faking the whole CActiveRecord.tableSchema.