XCube_Utils::formatMessage()

This static method offers string generating function like sprintf. But, it is based on .NET string.Format().

• {0} is required.
• Input {0} with {1} characters or less.

This article explains why XCube took this format.

Languages have different grammar from each other. By that, message catalog often needs many translations. XCube recommends dividing words from a message. For example;

• Name is required.
• Message is required.
• Input password with 32 characters or less.
• Input email with 255 characters or less.
• Note is required.

If I have to translate all of them..., I will forget about XOOPS and go to bars to drink beer. spritnf() enables writing as the following;

• %s is required.
• Input {0} with {1} or less characters.

Very well. But, you have to pay notice that this method is difficult to control order and capitalize. Japanese language has different order from English in most sentences.

• [EN] Input %s with %s or less characters.
• [JA] Saitei %s moji ijoude %s wo nyuuryoku sitekudasai.

When this translation is convereted by sprintf(), you look a strange message "Input 32 with password character(s) or less". Yes, the cause is difference of grammars between English and Japanese. You have just understood one of reasons that XCube took .NET format.

• [EN] Input {0} with {1} character(s) or less.
• [JA] Saitei {1} moji ijoude {0} wo nyuuryoku sitekudasai.

sprintf() can do the same as it, but it is not known well and it can't solve another problem as the following.

• {0} is required.
• Input {0} with ...

If {0} is "password", what do you set it? "Password"? or "password"?

XCube will supply modifiers to solve this problem.

• {0:ucfirst} is required.
• Input {0} with ...

In spritnf(), it's impossible to write modifier in string literal.

Even if a module developer does not understand the plural languages, he should use this method for contributors who try to translate.

What is ActionForm? (6)

Conclusion

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.

What is ActionForm? (5)

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.

load(&$object)

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.

update(&$object)

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)
{
$obj->set('update_unixtime', time());
$obj->set('subject', $form->get('subject'));
$obj->set('message', $form->get('message'));
}

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();

What is ActionForm? (4)

I explain the recommended procedure of ActionForm also today.

Validate

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.

Error Check

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.

What is ActionForm? (3)

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();
$form->prepare();

$form->fetch();
$form->validate();

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.

Initialization

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.

Fetch

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.

What is ActionForm? (2)

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:

1. You can generate sub classes of XCube_ActionForm from XML configuration file by cubson or another tool.
2. 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.

What is ActionForm? (1)

I started to edit cubson manual. It's remix of this blog. Old entries are never modified, but the manual is updated to cover latest informations. For example, Mr,gigamaster told me the correct guidance in English OS. I shall update the manual by such reports. So users should read not the archive of blog but the manual.

Well 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.