Class Db_FormBehavior

Db_FormBehavior class

Defined in	/phproad/modules/db/behaviors/db_formbehavior.php, lines 29-2061
Inheritance	Phpr_Extension » Phpr_ControllerBehavior » Db_FormBehavior
Author	LemonStand eCommerce Inc.

Adds form handling features to back-end controllers. This class allows to extend any back-end controller with a form handling functionality. It allows to render Create, Edit and Preview forms along with processing corresponding AJAX events for saving and deleting records.

The extension can be added to a controller by listing the class name in the $implement property of the controller class:

class AbcBlog_Posts extends Backend_Controller
{
  public $implement = 'Db_FormBehavior, Db_ListBehavior';
  ...

The class works only with Db_ActiveRecord models. Model columns and form fields should be defined in the model in order to be displayed in a form.

To configure the extension, its properties should be defined in the extended controller class. Only the $form_model_class property is required. Please read the Administration Area Forms article for the usage examples and details.

Public properties

Property	Type	Description	Defined By
form_create_save_flash	string	a message to display after a new record has been successfully saved.	Db_FormBehavior
form_create_save_redirect	string	an URL to redirect the browser after the Create form is successfully processed.	Db_FormBehavior
form_create_title	string	specifies a title of the Create Record page.	Db_FormBehavior
form_delete_redirect	string	an URL to redirect the browser after a record has been deleted.	Db_FormBehavior
form_edit_delete_flash	string	a message to display after a record has been successfully deleted.	Db_FormBehavior
form_edit_save_flash	string	a message to display after an existing record has been successfully saved.	Db_FormBehavior
form_edit_save_redirect	string	an URL to redirect the browser after the Save form is successfully processed.	Db_FormBehavior
form_edit_title	string	specifies a title of the Edit Record page.	Db_FormBehavior
form_model_class	string	a name of the model class.	Db_FormBehavior
form_not_found_message	string	message to display on the Edit and Preview pages in case if the record is not found.	Db_FormBehavior
form_preview_title	string	specifies a title of the Preview Record page.	Db_FormBehavior
form_redirect	string	an URL to redirect the browser after a form is saved or the record is deleted.	Db_FormBehavior

Public methods

Method	Description	Defined By
formAfterCreateSave()	called after a new record is saved to the database.	Db_FormBehavior
formAfterDelete()	called after a record is deleted from the database.	Db_FormBehavior
formAfterEditSave()	called after an existing record is saved to the database.	Db_FormBehavior
formAfterSave()	called after a new or existing record is saved to the database.	Db_FormBehavior
formBeforeCreateSave()	called before a new record is saved to the database.	Db_FormBehavior
formBeforeEditSave()	called before an existing record is saved to the database.	Db_FormBehavior
formBeforeSave()	called before a new or existing record is saved to the database.	Db_FormBehavior
formCreateModelObject()	creates the form model object for the Create page.	Db_FormBehavior
formFindModelObject()	finds a model object for the Edit page.	Db_FormBehavior
formRender()	renders the form.	Db_FormBehavior
formRenderPreview()	renders the form in Preview (read-only) mode.	Db_FormBehavior

Events

Event	Description
core:onAfterFormRecordCreate	Triggered after a new model is saved to the database.
core:onAfterFormRecordDelete	Triggered after an existing model is deleted from the database.
core:onAfterFormRecordUpdate	Triggered after an existing model is saved to the database.
core:onBeforeFormRecordCreate	Triggered before a new model is saved to the database.
core:onBeforeFormRecordDelete	Triggered before an existing model is deleted from the database.
core:onBeforeFormRecordUpdate	Triggered before an existing model is saved to the database.
core:onBeforeFormRender	Triggered before an Administration Area form is rendered.
core:onBeforeFormRenderPreview	Triggered before an Administration Area preview (read-only) form is rendered.

Property details

¶ form_create_save_flash property

public string $form_create_save_flash;

A message to display after a new record has been successfully saved.

¶ form_create_save_redirect property

public string $form_create_save_redirect;

An URL to redirect the browser after the Create form is successfully processed. This value overrides the $form_redirect property.

¶ form_create_title property

public string $form_create_title;

Specifies a title of the Create Record page. The default value is Create.

¶ form_delete_redirect property

public string $form_delete_redirect;

An URL to redirect the browser after a record has been deleted. This value overrides the $form_redirect and $form_edit_save_redirect properties.

¶ form_edit_delete_flash property

public string $form_edit_delete_flash;

A message to display after a record has been successfully deleted.

¶ form_edit_save_flash property

public string $form_edit_save_flash;

A message to display after an existing record has been successfully saved.

¶ form_edit_save_redirect property

public string $form_edit_save_redirect;

An URL to redirect the browser after the Save form is successfully processed. This value overrides the $form_redirect property.

¶ form_edit_title property

public string $form_edit_title;

Specifies a title of the Edit Record page. The default value is Edit.

¶ form_model_class property

public string $form_model_class;

A name of the model class.

¶ form_not_found_message property

public string $form_not_found_message;

Message to display on the Edit and Preview pages in case if the record is not found. The default value is "Record not found".

¶ form_preview_title property

public string $form_preview_title;

Specifies a title of the Preview Record page. The default value is Preview.

¶ form_redirect property

public string $form_redirect;

An URL to redirect the browser after a form is saved or the record is deleted. Use the url() for creating back-end URLs. Example:

$this->form_redirect = url('/shop/product_types');

Method details

¶ formAfterCreateSave() method

public void formAfterCreateSave(Db_ActiveRecord $model, string $session_key)

$model	Db_ActiveRecord	specifies a model object saved to the database.
$session_key	string	specifies the form session key.

Called after a new record is saved to the database. This method can be overridden in the controller and used as an event handler.

¶ formAfterDelete() method

public void formAfterDelete(Db_ActiveRecord $model, string $session_key)

$model	Db_ActiveRecord	specifies a deleted model object.
$session_key	string	specifies the form session key.

Called after a record is deleted from the database. This method can be overridden in the controller and used as an event handler.

¶ formAfterEditSave() method

public void formAfterEditSave(Db_ActiveRecord $model, string $session_key)

$model	Db_ActiveRecord	specifies a model object saved to the database.
$session_key	string	specifies the form session key.

Called after an existing record is saved to the database. This method can be overridden in the controller and used as an event handler.

¶ formAfterSave() method

public void formAfterSave(Db_ActiveRecord $model, string $session_key)

$model	Db_ActiveRecord	specifies a model object saved to the database.
$session_key	string	specifies the form session key.

Called after a new or existing record is saved to the database. This method can be overridden in the controller and used as an event handler.

¶ formBeforeCreateSave() method

public void formBeforeCreateSave(Db_ActiveRecord $model, string $session_key)

$model	Db_ActiveRecord	specifies a model object to be saved to the database.
$session_key	string	specifies the form session key.

Called before a new record is saved to the database. This method can be overridden in the controller and used as an event handler.

¶ formBeforeEditSave() method

public void formBeforeEditSave(Db_ActiveRecord $model, string $session_key)

$model	Db_ActiveRecord	specifies a model object to be saved to the database.
$session_key	string	specifies the form session key.

Called before an existing record is saved to the database. This method can be overridden in the controller and used as an event handler.

¶ formBeforeSave() method

public void formBeforeSave(Db_ActiveRecord $model, string $session_key)

$model	Db_ActiveRecord	specifies a model object to be saved to the database.
$session_key	string	specifies the form session key.

Called before a new or existing record is saved to the database. This method can be overridden in the controller and used as an event handler.

¶ formCreateModelObject() method

public Db_ActiveRecord formCreateModelObject()

{return}	Db_ActiveRecord	returns the model object.

Creates the form model object for the Create page. This method can be overridden in the controller class if a special actions should be performed in order to create the model. By default the method creates an object of class specified in the $form_model_class property.

¶ formFindModelObject() method

public Db_ActiveRecord formFindModelObject(integer $record_id)

$record_id	integer	specifies the primary key value.
{return}	Db_ActiveRecord	returns the model object.

Finds a model object for the Edit page. This method can be overridden in the controller class if a special actions should be performed in order to load a model from the database. By default the method creates an object of class specified in the $form_model_class property and then finds a record by the primary key value specified in the page URL.

¶ formRender() method

public void formRender(Db_ActiveRecord $model=NULL)

$model	Db_ActiveRecord	optional model object to override the model class specified in the $form_model_class property.

Renders the form. This method should be called on the Create or Edit pages. The FORM element and buttons should be defined separately. The buttons should trigger events with names corresponding the action name - create_onSave, edit_onSave, etc. The event handlers are defined in the extension class. Example of the Create form:

<?= Phpr_Form::openTag() ?>
  <? $this->formRender() ?>

  <?= backend_ajax_button('Create', 'create_onSave', array('class'=>'default')) ?>
  <?= backend_ajax_button('Cancel', 'create_onCancel') ?>
</form>

Example of the Edit form:

<?= Phpr_Form::openTag(array('id'=>'form_element')) ?>
  <? $this->formRender() ?>

  <?= backend_ajax_button('Save', 'edit_onSave', array('class'=>'default')) ?>
  <?= backend_ajax_button('Cancel', 'edit_onCancel') ?>
  <?= backend_ajax_button('Delete', 'edit_onDelete', array('class'=>"right"), "confirm: 'Do you really want to delete this record?'") ?>

  <div class="clear"></div>
</form>

¶ formRenderPreview() method

public void formRenderPreview(Db_ActiveRecord $model=NULL)

$model	Db_ActiveRecord	optional model object to override the model class specified in the $form_model_class property.

Renders the form in Preview (read-only) mode. This method should be called on the Preview page. Example:

<? $this->formRenderPreview() ?>

LemonStand API