|
Formation_Documentation
Documentation of the Formation module
IntroductionThe Formation module is a replacement of the current validation library as well as the Forge library. It was created due to some specific needs of mine and developed as such. It has reached a state in which it might be beneficial to other users as well. I would greatly appreciate feedback, comments, bugfixes etc. You can download the latest release from http://code.google.com/p/kohana-mptt/downloads/list or checkout the latest edition from the subversion repository. If you're looking for documentation on ModelToForm , follow the link. ModelToForm is a way to have forms generated from your models. It's a wIP. InstallationBefore installation you should know how to work with Kohana else this might become difficult. You should extract the archive and put it into your modules folder. In your application/config/config.php you should enable this module. DocumentationNow, you'll find several files in the formation folder: Field.php, Formation.php and Validation.php as well as a folder elements and a folder rules. As is usual in Kohana the files map to classes. The Field class stands for an input field in a form. Elements extend from this field, such as the Input element, Password element etc.. A field has rules for validation, these rules are found in the rules folder. The Validation class does just validation, it doesn't generate your forms. Formation class extends Validation and does generate your forms. Note I moved rules and elements in a subfolder for clarity. This means they cannot be autoloaded by Kohana unless you register a new autoloader. The Formation or Validation class usually do this but if you want to use elements or rules outside of these classes you should register the autoloader yourself. You can find it in Validation.php Your first formFirst we use the Validation class without form generation. We have a form which has to fields 'username' and 'password'. $_POST=new Validation($_POST);
$_POST['username']->add_rule('Rule_Required');
$_POST['password']->add_pre_filter('trim')->add_rule('Rule_Min_Length',8)->add_rule('Rule_Required');You see, it's easy. Normally the $POST is filled by php and you use it, now you set some rules on it's keys and let it validate. If the form is submitted the constructor takes the $POST values. If not you still create the fields in your validation and add the rules. Would work for $GET as well of course. Other methods you can carry out on a $POST field. You can use also get and set the properties, only not name $_POST['password']->screen_name='asdf'; You can at any time echo the object echo $_POST['username']; It's an array object, means you can sort it, count it, put it in a loop $_POST->asort(); count($_POST); Fun he Ok, on to the Validation class Validation classSome of the class methods
$_POST=new Validation($_POST);
$_POST['username']->add_rule('Rule_Required');
$_POST['password']->add_pre_filter('trim')->add_rule('Rule_Min_Length',8)->add_rule('Rule_Required');
if($_POST->validate())
{
echo 'have fun';
}
else
{
var_dump($_POST->errors();
}Again, fairly simple or not :) Formation classWorks pretty similar to the Validation class when it comes to adding rules, filters and callbacks. Every Element inherits from the Field class so all those methods are available. First form$form=new Formation;
$form->set_method('POST'); //is default but still
$form->set_attr('id','form_css_id');
$form->add_element('input','username')->add_rule('Rule_Exact_Length',4);
if($form->validate())
{
echo 'yah';
}
else
{
echo $form; //will call $form->render()
}You can see I create an instance of the form, set it's method and id add one element with a rule. Then I try to validate it, if it fails it renders the form. The class renders a view with the form. This view or template can be found in formation/views/formation_template.php You can change the template with $form->set_template('your_template');get_template() retrieves the template. You might have some variables in your template that you want to fill. By default there is an $legend variable. You can set variables in your template like this, just like views in Kohana. $form->legend='your legend'; $form->some_var='some value'; Formation extends Validation so the Validation methods are also available in the Formation class. ElementsLike seen in the example above you can add elements. Related methods
You can also add elements like this $input=new Element_Input('email');
$input->class='some_class';
$input->set_attr('id','some_id')
->add_rule('Rule_Matches',$form['username']);
$form->add_element($input)->label()->set_text('email label ');This means there are two syntaxes $form->add_element(new Element_Input('name'));
$form->add_element('input','name');Elements you can add
LabelLabels are special. See example $form->add_element('input','name')->label()->set_attr('id','someid')->set_text('some text');label() returns an object label of which you can set the attributes and text. Special elementsSome elements have special methods. Check the source. $form->add_element('upload','load_file')->set_directory('some_dir'); GroupsGroups also work as elements but do not extend Element_Input but Formation. The default template renders them within a <fieldset> element. You can nest them. $form->add_element('input','email');
$form->add_group(array('email'),'group1');
$form['group1']->add_element('password','Password field')->add_rule('Rule_Min_Length',8);
$form['group1']->add_group(array(),'group2');
$form['group1']['group2']->add_element('input','sth');The first argument of the add_group method can be a string or array with the names of elements, or elements themselves. If they are names they will be retrieved from the group's parents and moved to the group. Else, they will simply be added. Only the parent's elements are searched for, grandparents are not. Groups extend Formation so many Formation methods are valid here. The default template for groups is the same as for Formation. Rules, callbacks and filtersCallbacks and filters are all callbacks. RulesRules are the following
Some accept arguments, you can also set the error message, language file. In the language files that come with Formation you can see the syntax used. Storing formsUsing a form class you can store forms and use the throughout your application. Example: My_Form.php class My_Form_Core extends Formation{
public function __construct()
{
parent::__construct();
$this->legend='Some legend';
$this->add_element('input','email')->add_rule('Rule_Required');
$this->add_element('input','username')->add_rule('Rule_Required');
$this->add_element('submit','Submit');
}
}Now loading the object is as easy as $form=new My_Form; $form->render(); Example of FormationA complete example $form=new Formation;
$form->add_element('input','username')->add_rule('Rule_Exact_Length',4);
$form->add_element('upload','load')->add_rule('Rule_Upload_Size',1050);
$form->add_element('input','email')->add_rule('Rule_Email')->add_rule('Rule_Required');
$form->add_group(array('username'),'group1');
$form['group1']->add_element('password','Password field')->add_rule('Rule_Min_Length',8);
$form->add_element('submit','Submit');
$form['group1']->legend='User/pass here please';
$form->legend='Some legend';
if($form->validate())
{
echo 'validates';
}
else
{
echo $form;
}
|
Sign in to add a comment
sorry, But I got the following error, Please tell me what can I do now?
Fatal error: Class 'required' not found in D:\apachefriends\xampp\htdocs\tagsmatch\modules\formation\libraries\Field.php on line 307
Thanking you
Probably an old version of Formation. Try to add Rule_Required? instead
I got the following error:
Fatal error: Call to undefined method Form_Field?::label() in /var/www/modules/formation/views/formation_template.php on line 21
What can it mean?
I deleted this code and error disappeared:
$form->add_group(array('username'),'group1'); $form['group1']->add_element('password','Password field')->add_rule('Rule_Min_Length',8); $form->add_element('submit','Submit'); $form['group1']->legend='User/pass here please'; $form->legend='Some legend';I think there is bug somewhere around function Formation_Core?->ordered_elements(), because after this function is called an empty form field 'username' of type Form_Field? appears in $inputs array and when Kohana renders template it causes the error.
I'll look into it shortly. Might be related to the groups functionality. Thanks for the extensive bug reports.
It doesn't appear that required dropdowns aren't working.
$form->add_element('dropdown', 'field_name')->set_options(array('option1', 'option2'))->add_rule('Rule_Required?');
The validation always generates a "The field_name field is required." error message, no matter what I select when submitting the form.
It's very usefull library, but I was confronted with the next challenge: Formation-0.98 does not work with Kohana 2.2 (old ORM and ORM2 are not compatible). Thanking you.
Thanks, I think the svn version is up to date. I've been meaning to upload a new package but haven't gotten around to it.
Very nice and useful library. Thank you.
For Kohana 2.2 with the latest Formation svn (Sept. 15, 2008) had to make the following changes to get rid of the Log and Config error messages: - Formation.php (34) - replace Log::add with Kohana::log - Validation.php (33) - same thing as above - Validation.php (50) - replace Config::item with Kohana::config There may be some other places, but so far I got away with just the above.
For those interested, to "ease" the creation of custom form templates (and use field names as variables in the template - similar to Forge), add these lines:
in the Formation.php render() function, immediately after this line (360):Not much, but I personally find it clearer to see something like $username->render() or $username->label() in the template. If these were already there, I apologize for my lack of knowledge.
this is not working for me after all the changes I made. I able to get the form to show, but clicking submit with not values in the fields, simply returns the form with no error messages. Debug log records 'Formation library initialized'. Even when I enter valid data, it does not want to validate. Any ideas?
Oops... Complete change of autoloading: classes are now loaded by changing underscores to slashes to create a path, eg: Controller_Admin_User? would be found at classes/admin/user.php (See routing changes below for more information)
http://dev.kohanaphp.com/changeset/3366
This project is still alive ? I've got hope for a new version because this version have some bugs. ie. $form->set_values don't work if elements are in groups
I'm trying to get this working too. Validation seems to be broken. If I get it working I'll post the code.
I temporary solve this problem. Solution is: values must be set before grouping elements. So, if form is defined inside a library it should be done in 3 steps: 1) create form object from library, 2) settting values, 3) grouping elements. It work as expected, but looks very bad :)
I'm sorry I haven't been able to update this project but I am just too busy. Stuff is still geared towards an old version of Kohana. If anyone wants to fork it, be my guest.
syndicut: I think the error is, that there is no label() funktion in FORMATION_CORE or Element_Group?. And i'm not quite sure what should happen, or else I could make the function myself.
How to report bugs to this project, the right way ?
There is a minor "bug" in the file: i18n/en_US/validation.php
'rule_upload_size' => 'The {filename file you uploaded was too large. The maximum size allowed is {max_bytes}.',
after {filename there should be a }
Here's a modified version I've got working with Kohana V2.3.
http://www.citricity.com/formation_kohana_2_3.zip
Might fork this at some point with a new google code project.
There is another error with the class Config in file libraries/elements/Element_Label?.php on line 18, replace Config::item with Kohana::config.
brudinie, i tried your version for kohana 2.3, but still the add_group() method still raised exception.