Message from discussion
JForm Introduction
Received: by 10.142.162.9 with SMTP id k9mr2009759wfe.24.1232957003593;
Mon, 26 Jan 2009 00:03:23 -0800 (PST)
Return-Path: <rob.sch...@community.joomla.org>
Received: from wf-out-1314.google.com (wf-out-1314.google.com [209.85.200.170])
by mx.google.com with ESMTP id m37si2338220waf.2.2009.01.26.00.03.22;
Mon, 26 Jan 2009 00:03:23 -0800 (PST)
Received-SPF: neutral (google.com: 209.85.200.170 is neither permitted nor denied by domain of rob.sch...@community.joomla.org) client-ip=209.85.200.170;
Authentication-Results: mx.google.com; spf=neutral (google.com: 209.85.200.170 is neither permitted nor denied by domain of rob.sch...@community.joomla.org) smtp.mail=rob.sch...@community.joomla.org
Received: by wf-out-1314.google.com with SMTP id 24so5960884wfg.15
for <multiple recipients>; Mon, 26 Jan 2009 00:03:22 -0800 (PST)
MIME-Version: 1.0
Received: by 10.142.161.13 with SMTP id j13mr3991527wfe.270.1232957002367;
Mon, 26 Jan 2009 00:03:22 -0800 (PST)
Date: Mon, 26 Jan 2009 18:03:22 +1000
Message-ID: <852447420901260003o286bdac7vc147a8321738aab5@mail.gmail.com>
Subject: JForm Introduction
From: Rob Schley <rob.sch...@community.joomla.org>
To: joomla-dev-framework@googlegroups.com, joomla-dev-cms@googlegroups.com
Content-Type: multipart/alternative; boundary=000e0cd32fd026450c04615e2c39
--000e0cd32fd026450c04615e2c39
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: 7bit
Hi All,
Pardon the cross-post but I thought this was important enough to make sure
it got to all the necessary places. Some of you may have noticed a new form
package in the Joomla 1.6 trunk. The new form package provides a robust API
for creating, populating, filtering, and validating form data via XML and
PHP. The forms are created with XML similar to JParameter but JForm is
powerful enough to be used for a complete form, not just a set of
parameters.
Filtering
By defining a filter attribute on each form field, JForm will allow you to
completely sanitize your form input with one API call. The filter attribute
will accept a variety of values including "unset" for read only data,
"safehtml" for limited HTML support, "raw" for full HTML support, all
JFilterInput::clean() mechanisms including "integer", "boolean", "base64",
etc. as well as callbacks in the form of "my_callback_method" or
"JFilterOutput::stringUrlSafe".
Validation
By defining a validate attribute for each form field, JForm will also
validate form data. Some simple rules are available right now but there will
probably be more coming in the near future. To validate an e-mail address,
you can use validate="email" and the e-mail validator takes an optional
attribute unique="unique" which will validate that the e-mail address is not
in use by another user. If you use the unique option, you have to also
specify a key for the user's table. It is easy to build your own validation
rules and they can be combined to create some pretty sophisticated
validation logic.
For example:
<field
name="id"
type="hidden"
filter="integer"
/>
<field
name="email1"
type="text"
id="email1"
label="PROFILE FORM EMAIL1 LABEL"
description="PROFILE FORM EMAIL1 LABEL"
message="PROFILE FORM EMAIL1 MESSAGE"
class="inputbox validate-email"
size="30"
default=""
required="true"
filter="string"
validate="email"
field="id"
unique="true"
/>
<field
name="email2"
type="text"
id="email2"
label="PROFILE FORM EMAIL2 LABEL"
description="PROFILE FORM EMAIL2 LABEL"
message="PROFILE FORM EMAIL2 MESSAGE"
class="inputbox validate-email"
size="30"
default=""
required="true"
filter="string"
validate="equals"
field="email1"
/>
The field definitions could be used in a user data edit screen to ensure
that the user's e-mail address is unique to that user and that the email1
and email2 fields match. The email1 field will validate that the e-mail
address is unique to the user and the email2 field will verify that it's
supplied value matches the value given to email1. You can also specify
custom validation messages via the message attribute.
Getting A Form
Let's assume you have an MVC component with a "forms" folder within the
"models" folder. In the forms folder, you have a form file named
"profile.xml". To get a instance of the form you would do something like:
// Get the form.
jimport('joomla.form.form');
JForm::addFormPath(JPATH_COMPONENT.DS.'models'.DS.'forms');
$form = &JForm::getInstance('jform', 'profile', true, array('array' =>
true));
JForm::addFormPath() works similarly to JModel::addIncludePath or
JHtml::addIncludePath(). JForm::getInstance() returns a JForm instance. The
first parameter is a name to identify the form by and will come into play
when with the array option that you see in the forth parameter. The second
parameter, "profile", tells JForm where to get the XML data from and the
third option indicates that "profile" is a file name. Instead of specifying
a file name, you can pass in straight XML into the second parameter and set
the third parameter to false. The fourth parameter, array('array' => true),
tells JForm to render the individual field names as an array. If our
profile.xml contained the fields posted above, the field names would be
jform[id], jform[email1], and jform[email2]. If the array option is set to
false, the field names would be rendered as id, email1, and email2.
The array option is very convenient because it makes loading the form data
and running it through the filter/validator extremely quick.
// Get the form.
jimport('joomla.form.form');
JForm::addFormPath(JPATH_COMPONENT.DS.'models'.DS.'forms');
$form = &JForm::getInstance('jform', 'profile', true, array('array' =>
true));
// Get the profile data.
$data = JRequest::getVar('jform', array(), 'post', 'array');
// Filter and validate the form data.
$data = $form->filter($data);
$return = $form->validate($data);
// Check for errors and save...
Notes
* We are still sorting out some of the error handling and validation warning
feedback for PHP 5.2. The error handling will probably be updated in the
near future to make distinguishing hard errors from validation errors
easier.
* The library as a whole is quite powerful and I hope that it is fairly easy
to understand but it will probably require some trial and error to really
get the hang of. The newly committed com_weblinks admin component should
serve as a useful example of how to use the new form package and the access
control system will begin to use it more in the near future.
That is all I can think of right now but I'm sure I've probably forgot
something. If you guys have any questions, feel free to ask and I will do my
best to help you out.
Best,
Rob Schley
--000e0cd32fd026450c04615e2c39
Content-Type: text/html; charset=ISO-8859-1
Content-Transfer-Encoding: quoted-printable
Hi All,<div><br></div><div>Pardon the cross-post but I thought this was imp=
ortant enough to make sure it got to all the necessary places. Some of you =
may have noticed a new form package in the Joomla 1.6 trunk. The new form p=
ackage provides a robust API for creating, populating, filtering, and valid=
ating form data via XML and PHP. The forms are created with XML similar to =
JParameter but JForm is powerful enough to be used for a complete for=
m, not just a set of parameters.</div>
<div><br></div><div><span class=3D"Apple-style-span" style=3D"font-weight: =
bold;">Filtering</span></div><div><br></div><div>By defining a filter attri=
bute on each form field, JForm will allow you to completely sanitize your f=
orm input with one API call. The filter attribute will accept a variety of =
values including "unset" for read only data, "safehtml"=
for limited HTML support, "raw" for full HTML support, all JFilt=
erInput::clean() mechanisms including "integer", "boolean&qu=
ot;, "base64", etc. as well as callbacks in the form of "my_=
callback_method" or "JFilterOutput::stringUrlSafe".</div>
<div><br></div><div><span class=3D"Apple-style-span" style=3D"font-weight: =
bold;">Validation</span></div><div><br></div><div>By defining a validate at=
tribute for each form field, JForm will also validate form data. Some simpl=
e rules are available right now but there will probably be more coming in t=
he near future. To validate an e-mail address, you can use validate=3D"=
;email" and the e-mail validator takes an optional attribute unique=3D=
"unique" which will validate that the e-mail address is not in us=
e by another user. If you use the unique option, you have to also specify a=
key for the user's table. It is easy to build your own validation rule=
s and they can be combined to create some pretty sophisticated validation l=
ogic.</div>
<div><br></div><div>For example:</div><div><br></div><div><div><field</d=
iv><div><span class=3D"Apple-tab-span" style=3D"white-space:pre"> </span>na=
me=3D"id"</div><div><span class=3D"Apple-tab-span" style=3D"white=
-space:pre"> </span>type=3D"hidden"</div>
<div><span class=3D"Apple-tab-span" style=3D"white-space:pre"> </span>filte=
r=3D"integer"</div><div>/></div><div><br></div><div><field<=
/div><div><span class=3D"Apple-tab-span" style=3D"white-space:pre"> </span>=
name=3D"email1"</div>
<div><span class=3D"Apple-tab-span" style=3D"white-space:pre"> </span>type=
=3D"text"</div><div><span class=3D"Apple-tab-span" style=3D"white=
-space:pre"> </span>id=3D"email1"</div><div><span class=3D"Apple-=
tab-span" style=3D"white-space:pre"> </span>label=3D"PROFILE FORM EMAI=
L1 LABEL"</div>
<div><span class=3D"Apple-tab-span" style=3D"white-space:pre"> </span>descr=
iption=3D"PROFILE FORM EMAIL1 LABEL"</div><div><span class=3D"App=
le-tab-span" style=3D"white-space:pre"> </span>message=3D"PROFILE FORM=
EMAIL1 MESSAGE"</div>
<div><span class=3D"Apple-tab-span" style=3D"white-space:pre"> </span>class=
=3D"inputbox validate-email"</div><div><span class=3D"Apple-tab-s=
pan" style=3D"white-space:pre"> </span>size=3D"30"</div><div><spa=
n class=3D"Apple-tab-span" style=3D"white-space:pre"> </span>default=3D&quo=
t;"</div>
<div><span class=3D"Apple-tab-span" style=3D"white-space:pre"> </span>requi=
red=3D"true"</div><div><span class=3D"Apple-tab-span" style=3D"wh=
ite-space:pre"> </span>filter=3D"string"</div><div><span class=3D=
"Apple-tab-span" style=3D"white-space:pre"> </span>validate=3D"email&q=
uot;</div>
<div><span class=3D"Apple-tab-span" style=3D"white-space:pre"> </span>field=
=3D"id"</div><div><span class=3D"Apple-tab-span" style=3D"white-s=
pace:pre"> </span>unique=3D"true"</div><div>/></div><div><br><=
/div><div>
<div><field</div><div><span class=3D"Apple-tab-span" style=3D"white-spac=
e:pre"> </span>name=3D"email2"</div><div><span class=3D"Apple-tab=
-span" style=3D"white-space:pre"> </span>type=3D"text"</div><div>=
<span class=3D"Apple-tab-span" style=3D"white-space:pre"> </span>id=3D"=
;email2"</div>
<div><span class=3D"Apple-tab-span" style=3D"white-space:pre"> </span>label=
=3D"PROFILE FORM EMAIL2 LABEL"</div><div><span class=3D"Apple-tab=
-span" style=3D"white-space:pre"> </span>description=3D"PROFILE FORM E=
MAIL2 LABEL"</div>
<div><span class=3D"Apple-tab-span" style=3D"white-space:pre"> </span>messa=
ge=3D"PROFILE FORM EMAIL2 MESSAGE"</div><div><span class=3D"Apple=
-tab-span" style=3D"white-space:pre"> </span>class=3D"inputbox validat=
e-email"</div>
<div><span class=3D"Apple-tab-span" style=3D"white-space:pre"> </span>size=
=3D"30"</div><div><span class=3D"Apple-tab-span" style=3D"white-s=
pace:pre"> </span>default=3D""</div><div><span class=3D"Apple-tab=
-span" style=3D"white-space:pre"> </span>required=3D"true"</div>
<div><span class=3D"Apple-tab-span" style=3D"white-space:pre"> </span>filte=
r=3D"string"</div><div><span class=3D"Apple-tab-span" style=3D"wh=
ite-space:pre"> </span>validate=3D"equals"</div><div><span class=
=3D"Apple-tab-span" style=3D"white-space:pre"> </span>field=3D"email1&=
quot;</div>
<div>/></div><div><br></div><div>The field definitions could be used in =
a user data edit screen to ensure that the user's e-mail address is uni=
que to that user and that the email1 and email2 fields match. The email1 fi=
eld will validate that the e-mail address is unique to the user and the ema=
il2 field will verify that it's supplied value matches the value given =
to email1. You can also specify custom validation messages via the message =
attribute.</div>
<div><br></div><div><span class=3D"Apple-style-span" style=3D"font-weight: =
bold;">Getting A Form</span></div><div><br></div><div>Let's assume you =
have an MVC component with a "forms" folder within the "mode=
ls" folder. In the forms folder, you have a form file named "prof=
ile.xml". To get a instance of the form you would do something like:</=
div>
<div><br></div><div><div>// Get the form.</div><div>jimport('joomla.for=
m.form');</div><div>JForm::addFormPath(JPATH_COMPONENT.DS.'models&#=
39;.DS.'forms');</div><div>$form =3D &JForm::getInstance('j=
form', 'profile', true, array('array' =3D> true));</=
div>
</div><div><br></div><div>JForm::addFormPath() works similarly to JModel::a=
ddIncludePath or JHtml::addIncludePath(). JForm::getInstance() returns a JF=
orm instance. The first parameter is a name to identify the form by and wil=
l come into play when with the array option that you see in the forth param=
eter. The second parameter, "profile", tells JForm where to get t=
he XML data from and the third option indicates that "profile" is=
a file name. Instead of specifying a file name, you can pass in straight X=
ML into the second parameter and set the third parameter to false. The four=
th parameter, array('array' =3D> true), tells JForm to render th=
e individual field names as an array. If our profile.xml contained the fiel=
ds posted above, the field names would be jform[id], jform[email1], and jfo=
rm[email2]. If the array option is set to false, the field names would be r=
endered as id, email1, and email2. </div>
<div><br></div><div>The array option is very convenient because it makes lo=
ading the form data and running it through the filter/validator extremely q=
uick. </div><div><br></div><div><div>// Get the form.</div><div>jimpor=
t('joomla.form.form');</div>
<div>JForm::addFormPath(JPATH_COMPONENT.DS.'models'.DS.'forms&#=
39;);</div><div>$form =3D &JForm::getInstance('jform', 'pro=
file', true, array('array' =3D> true));</div><div><br></div>
<div><div>// Get the profile data.</div><div>$data =3D JRequest::getVar(=
9;jform', array(), 'post', 'array');</div><div><br></di=
v><div><div>// Filter and validate the form data.</div><div>$data<span clas=
s=3D"Apple-tab-span" style=3D"white-space:pre"> </span>=3D $form->filter=
($data);</div>
<div>$return<span class=3D"Apple-tab-span" style=3D"white-space:pre"> </spa=
n>=3D $form->validate($data);</div><div><br></div><div>// Check for erro=
rs and save...</div><div><br></div></div></div></div><div><span class=3D"Ap=
ple-style-span" style=3D"font-weight: bold;">Notes</span></div>
<div><br></div><div>* We are still sorting out some of the error handling a=
nd validation warning feedback for PHP 5.2. The error handling will probabl=
y be updated in the near future to make distinguishing hard errors from val=
idation errors easier.</div>
<div><br></div><div>* The library as a whole is quite powerful and I hope t=
hat it is fairly easy to understand but it will probably require some trial=
and error to really get the hang of. The newly committed com_weblinks admi=
n component should serve as a useful example of how to use the new form pac=
kage and the access control system will begin to use it more in the near fu=
ture. </div>
<div><br></div><div>That is all I can think of right now but I'm sure I=
've probably forgot something. If you guys have any questions, feel fre=
e to ask and I will do my best to help you out.</div><div><br></div><div>
Best,</div><div>Rob Schley</div></div></div>
--000e0cd32fd026450c04615e2c39--
|
