This article is based on a free entry of sunday-lab, so this article includes strange sentences as well as blog. Please, correct them. Thanks.

ActionForm Overview anchor.png

Page Top

Getting Started anchor.png

I'll have explained ActionForm in XCube to you until this weekend. If you don't have your myannounce module, go to manuals and create it.

Click "create new" in myannounce module at your control panel. Message input form of myannounce module requires subject and message. If you input nothing to the form, error messages show up and request to input again. Most of input forms in XOOPS Cube 2.1 does the same behavior. Input forms never allow error requests to pass to the next page.

These controls are brought by ActionForm. ActionForm works validity check. ActionForm is very popular in web programing. The core team created their ActionForm class as sample for developers. Developers who have no library should use library that is defined in core. This is not obligations but just library. So if a developer has useful libraries, he can select his libary.

XCube_ActionForm has the following purposes:

  • Get input values by $_REQUEST, and do stripslashes() if magic_quotes_gpc is on.
  • Type Safety. Cast values with following form property settings.
  • Do validity check with following field property settings.
  • Integrate one-time token into validation.
  • Remove the difference of creating and editing.
  • Implement interfaces that exchange values with data objects.

In other words, XCube_ActionForm manages input values at outside of data object, and checks it.

XCube_ActionForm is an abstract class. So you have to define the sub class of XCube_ActionForm to use ActionForm mechanism. To read example source code, open /modules/myannounce/admin/forms/MessageEditForm.class.php. There is too large class here.

This is the sub class of XCube_ActionForm. This class sets form properties and field properties in prepare(), and implements load() and update() member functions. You might think that it's difficult to such complex class, but developers don't need to define such class directly. It's possible to generate a sub class from XML configuration files with tools. See /modules/myannounce/admin/.xml/message_edit.xml. This is a configuration file for defining a sub class of XCube_ActionForm.

There are two important things about defining a sub class:

  • You can generate sub classes of XCube_ActionForm from XML configuration file by cubson or another tool.
  • Also, you can generate the XML configuration file from database structure or XML data object configuration file.

The core team thinks that it's unpossible to define user's ActionForm handy in the design of XCube_ActionForm. So we plan to add the official converter to XOOPS Cube Legacy 2.1 release. The converter doesn't have other functions which are like cubson. But, anybody can run it because it's PHP program.

BTW, if you know struts, you might notice that the format of these XML is struts like. But, this format is not important matter because XOOPS Cube never handles these XML directly. Who wants the format is converters, and each formats are different in each tools. You come able to select your favorite format if various tools which handle various formats are released.

Page Top

Description anchor.png

XCube_ActionFrom has the recommended procedure to get maximum impact. It's the following procedure:

  1. Construct
  2. Prepare
  3. (Load)
  4. Fetch
  5. Validate
  6. Error Check
  7. (Update)

XCube_ActionForm doesn't make frameworks about this procedure, but Legacy module uses it as ideal procedure. See typical code in the following:

$form =& new Myannounce_MessageEditForm();


if ($form->hasError()) {
    // display error

In fact, developers don't need to type these codes because code generators generate various typical code. But, let's read these codes to understand the procedure.

Page Top

Initialization anchor.png

Call prepare() after new operator. Prepare() consists of generated code which is complex and long. So developers write their initialization code in constructor. In using, both of these functions has to be called.

Page Top

Fetch anchor.png

ActionForm gets input values from $_REQUEST and keeps into its properties. After fetching, these values can be accessed by get() member function.

ActionForm fetches specified values only, and does casting conversion with type setting. Therefore, developers don't need to think casting conversion as long as they use get(). If null byte or bad control code are sent to string property or text property, XCube_ActionFrom aborts the program.

If you are a video game programer, imagine getting values of a joypad. Perhaps, the special class for joypad might work in the special condition about joypad, then keeps values only. Most developers don't need to program to fight BIOS or device drivers. Also developers with ActionForm don't need to program for some special conditions of web.

Type settings of form property for casting conversion are BOOL, INT, FLOAT, STRING and TEXT. TEXT accepts CR and LF, but STRING doesn't accept them.

In addition, developers can override fetch() in each form properties. If you want to know this special usage, read the comment in source code or create a document from source code with document systems.

Page Top

Validate anchor.png

ActionForm does validity check inside it. For example, "email" is string which has the special pattern. ActionForm fetches the input value as string and validates it as email. In this case, string is the information at __form property__, and email is the information at __field property__.

Its validity check is worked with field property setting. XCube and Legacy has various field property. Of course, developers can add on their validation pattern as field property.

If values violate the validity check, ActionForm comes to keep error messages which is tied up with the check. And, the one time token (ticket) is also checked in this process. The one time token of XCube_ActionForm is a kind of transaction tokens. Developers can handle the one time token as validations.

Page Top

Error Check anchor.png

hasError() checks whether the ActionForm has errors. Developers can access error messages of the ActionForm through getErrorMessages() member function.

Cubson recommends changing the business logic by request kind. If it's GET or errors, display the input form any number of times until successful. If it's POST and no errors, go to next procedures. By this loop, a user doesn't lose his input values even if it's errors.


For example, in myaccount module, try to click "Submit" button without message value. One error message will be displayed. But, the subject is not lost. You can't go to next procedure until you fill the message form. Also this loop works also in the case of token errors.

Page Top

How to exchange input values anchor.png

XCube_ActionForm is a device at web's requests for developer. But it doesn't connect to database. XOOPS Cube recommends separating ActionForm from business logics and database.


To use values which ActionForm received, you can make XoopsSimpleObject relay. XCube_ActionForm has interfaces to do it.

Page Top

load(&$object) anchor.png


You should implement the logic which copies values of $object to ActionForm in load(). XCube_ActionForm is difficult to have initial values. So you can use XoopsSimpleObject to set ActionForm. This method is important for edit function. If you send loaded object to ActionForm, it's re-edit contents. If you send new object to ActionForm, it's create contents. In other words, this is "Remove the difference of creating and editing".


In addition, you can use this member function for special loading. For example, ActionForm can copy a value as string from $object's integer value.

Page Top

update(&$object) anchor.png


You should implement the logic which copies values of ActionForm to $object. This member function has to be called after validation successful. As well as load(), you can use this member function for special updating. For example, "modified date time" field should not be copied from user's input values. In this case, you can always set time() to that field.


See example ActionForm in your myannounce module:

function update(&$obj)

This upload() doesn't overwrite 'create_unixtime'. And, it use time() for 'update_unixtime'. These techniques are used for protecting important field from users. For example, user's ActionForm should not handle the field which only administrators can edit. If you understand this concept, you can switch ActionForm by user type:

$actionForm $xoopsUser->isAdmin() ?
              new EditForm4Admin() : new EditForm4User();

Page Top

Conclusion anchor.png

XCube_ActionForm::load() and update() can be used for various variables because these functions are "virtual"(C++) and "abstract". Generated code by cubson uses these member function and switching GET/POST well. The following dialog shows the procedure in cubson's code for editing. You will understand that cubson contrive to use features of XCube_ActionForm.


As you know, cubson observes recommended rules of XOOPS Cube. In editing, Cubson splits the program into three objects, which are the business logic(action), ActionForm and XoopsSimpleObject. Perhaps, the point that you want to edit in generated code is validation and preparation of display. So you should customize ActionForm at first after cubson generates basic codes. You almost always don't need to write code for customizing ActionForm. You may modify XML configuration file and re-generate ActionForm by cubson.

You have just finished learning basic concept of XCube_ActionForm in this section. In next section, you will experience customizing ActionForm by cubson to actually.

Front page   Freeze Diff Backup Copy Rename ReloadPrint View   New Page Page list Search Recent changes   Help   RSS of recent changes (RSS 1.0) RSS of recent changes (RSS 2.0) RSS of recent changes (RSS Atom) Powered by xpWiki
Counter: 21892, today: 4, yesterday: 2
Princeps date: 2007-02-28 (Wed) 14:57:57
Last-modified: 2007-02-28 (Wed) 14:57:57 (JST) (4559d) by minahito

Welcome | News | Overview | Documentation | Forum | Tutorialstop
Brasilian | French | German | Greek | Japanese | Korean | Russian | T-Chinese
Powered by XOOPS Cube 2001-2011 The XOOPS Cube Project