Location: PHPKode > projects > Pieforms > pieforms-php5-0.2.2/doc/html/user/elements.html
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns=http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.4.1: http://docutils.sourceforge.net/" />
<title>Pieforms Elements</title>

<link rel="stylesheet" type="text/css" href="../style.css" />
</head>
<body>
<div class="document" id="pieforms-elements">
<h1 class="title">Pieforms Elements</h1>
<p><div id="breadcrumbs"><a href="http://pieforms.sourceforge.net/">Pieforms Home</a> &raquo; <a href="../">Documentation Home</a> &raquo; <a href="">Pieforms Elements</a></div></p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Author:</th><td class="field-body">Nigel McNie</td>
</tr>
<tr class="field"><th class="field-name">Contact:</th><td class="field-body"><a class="reference" href="mailto:nigel&#64;catalyst.net.nz">nigel&#64;catalyst.net.nz</a></td>
</tr>
<tr class="field"><th class="field-name">Copyright:</th><td class="field-body">This document has been placed in the public domain</td>
</tr>
</tbody>
</table>
<div class="contents topic">
<p class="topic-title first"><a id="contents" name="contents">Contents</a></p>
<ul class="simple">
<li><a class="reference" href="#overview" id="id1" name="id1">Overview</a></li>
<li><a class="reference" href="#using-elements" id="id2" name="id2">Using Elements</a><ul>
<li><a class="reference" href="#common-configuration-items-for-elements" id="id3" name="id3">Common Configuration Items for Elements</a></li>
<li><a class="reference" href="#supported-elements" id="id4" name="id4">Supported Elements</a></li>
</ul>
</li>
</ul>
</div>
<p>This document describes how elements fit into the Pieforms architecture, how you use them, and how you can write your own to suit your needs.</p>
<div class="section">
<h1><a class="toc-backref" href="#id1" id="overview" name="overview">Overview</a></h1>
<p>As you may be aware by now, if you have used Pieforms for a little while or have read the documentation that comes before this, Pieform elements represent distinct part of a form. It takes one or more elements to make up a form, but normally at least two - any elements the form has plus some kind of &quot;submit&quot; element. For example, a form may have three elements - a text box, a select dropdown, and a submit button.</p>
<p>The important thing to remember is that Pieform elements do not necessarily correspond to the standard HTML form widgets. In fact, they are a lot more powerful. While it is almost guaranteed that elements will contain at least one HTML widget, in reality they can contain almost anything you want. For the Mahara project, elements were written that:</p>
<ul class="simple">
<li>Made AJAX requests to populate select dropdowns</li>
<li>Used smarty templating to lay themselves out</li>
<li>Displayed a calendar for picking a date</li>
<li>Allowed users to maintain a list of e-mail addresses, and pick a &quot;primary&quot; address</li>
</ul>
<p>Once you understand how elements work, it will be easy for you to write your own. All you need to make sure of is that each element deals with one separate task. A good rule of thumb is to make elements that can return one value or one array of values, though in some cases you may relax this rule (for example, the email list element described above returns both a list of e-mail addresses and which one is the primary address).</p>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id2" id="using-elements" name="using-elements">Using Elements</a></h1>
<p>To use an element in your form, you name it when declaring the type of one of your form elements.</p>
<pre style="background-color:#ffc;border:1px solid #cc9;"><span style="font-weight:bold;color:#000;" title="php/php5/start">&lt;?php</span>

<span style="color:#33f;" title="php/php5/varstart">$</span><span style="color:#33f;" title="php/php5/var">form</span> <span style="color:#008000;" title="php/php5/symbol">=</span> <a href="http://www.php.net/array"><span style="color:#a1a100;" title="php/php5/keyword">array</span></a><span style="color:#008000;" title="php/php5/symbol">(</span>
    <span style="color:#f00;" title="php/php5/single_string/start">'</span><span style="color:#f00;" title="php/php5/single_string">name</span><span style="color:#f00;" title="php/php5/single_string/end">'</span> <span style="color:#008000;" title="php/php5/symbol">=</span><span style="color:#008000;" title="php/php5/symbol">&gt;</span> <span style="color:#f00;" title="php/php5/single_string/start">'</span><span style="color:#f00;" title="php/php5/single_string">myform</span><span style="color:#f00;" title="php/php5/single_string/end">'</span><span style="color:#008000;" title="php/php5/symbol">,</span>
    <span style="color:#f00;" title="php/php5/single_string/start">'</span><span style="color:#f00;" title="php/php5/single_string">elements</span><span style="color:#f00;" title="php/php5/single_string/end">'</span> <span style="color:#008000;" title="php/php5/symbol">=</span><span style="color:#008000;" title="php/php5/symbol">&gt;</span> <a href="http://www.php.net/array"><span style="color:#a1a100;" title="php/php5/keyword">array</span></a><span style="color:#008000;" title="php/php5/symbol">(</span>
        <span style="color:#f00;" title="php/php5/single_string/start">'</span><span style="color:#f00;" title="php/php5/single_string">myelement</span><span style="color:#f00;" title="php/php5/single_string/end">'</span> <span style="color:#008000;" title="php/php5/symbol">=</span><span style="color:#008000;" title="php/php5/symbol">&gt;</span> <a href="http://www.php.net/array"><span style="color:#a1a100;" title="php/php5/keyword">array</span></a><span style="color:#008000;" title="php/php5/symbol">(</span>
            <span style="color:#888;font-style:italic;" title="php/php5/single_comment/start">//</span><span style="color:#888;font-style:italic;" title="php/php5/single_comment"> Choose the type of the element here</span>
            <span style="color:#f00;" title="php/php5/single_string/start">'</span><span style="color:#f00;" title="php/php5/single_string">type</span><span style="color:#f00;" title="php/php5/single_string/end">'</span> <span style="color:#008000;" title="php/php5/symbol">=</span><span style="color:#008000;" title="php/php5/symbol">&gt;</span> <span style="color:#f00;" title="php/php5/single_string/start">'</span><span style="color:#f00;" title="php/php5/single_string">text</span><span style="color:#f00;" title="php/php5/single_string/end">'</span><span style="color:#008000;" title="php/php5/symbol">,</span>
            <span style="color:#888;font-style:italic;" title="php/php5/single_comment/start">//</span><span style="color:#888;font-style:italic;" title="php/php5/single_comment"> Any other configuration for the element goes here...</span>
        <span style="color:#008000;" title="php/php5/symbol">)</span>
    <span style="color:#008000;" title="php/php5/symbol">)</span>
<span style="color:#008000;" title="php/php5/symbol">)</span><span style="color:#008000;" title="php/php5/symbol">;</span>

<span style="font-weight:bold;color:#000;" title="php/php5/end">?&gt;</span></pre><p>In the above example, the element has been declared as having a type of 'text'. The text element is for a standard HTML text input. You put any other configuration for the element in there as well. For example, you can declare the default value for the element using <tt class="docutils literal"><span class="pre">defaultvalue</span></tt> or its size using <tt class="docutils literal"><span class="pre">size</span></tt>. The list varies per element, but the major ones are listed here.</p>
<div class="section">
<h2><a class="toc-backref" href="#id3" id="common-configuration-items-for-elements" name="common-configuration-items-for-elements">Common Configuration Items for Elements</a></h2>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">These items are supported by most of the standard elements, although their behaviour may vary between elements</p>
</div>
<table border="1" class="docutils">
<colgroup>
<col width="8%" />
<col width="92%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Item</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr><td><tt class="docutils literal"><span class="pre">defaultvalue</span></tt></td>
<td>What value the element should have by default</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">value</span></tt></td>
<td>The value the element should have <em>regardless of what the user submits</em></td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">accesskey</span></tt></td>
<td>What value to use for the <tt class="docutils literal"><span class="pre">accesskey</span></tt> attribute of the element</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">class</span></tt></td>
<td>What value to use for the <tt class="docutils literal"><span class="pre">class</span></tt> attribute of the element</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">dir</span></tt></td>
<td>What value to use for the <tt class="docutils literal"><span class="pre">dir</span></tt> attribute of the element</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">lang</span></tt></td>
<td>What value to use for the <tt class="docutils literal"><span class="pre">lang</span></tt> attribute of the element</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">onclick</span></tt></td>
<td>What value to use for the <tt class="docutils literal"><span class="pre">onclick</span></tt> attribute of the element. Note that it is preferred that you use MochiKit's event handling library if you can.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">style</span></tt></td>
<td>What value to use for the <tt class="docutils literal"><span class="pre">style</span></tt> attribute of the element</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">name</span></tt></td>
<td>You can name your elements using the <tt class="docutils literal"><span class="pre">name</span></tt> item, but the name for the element is usually sourced by the array key it was declared with.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">id</span></tt></td>
<td>What to use as an ID for the element. Pieforms gives all your elements IDs, so you generally should not set one this way.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">size</span></tt></td>
<td>What to use for the &quot;size&quot; of an element. The meaning varies from element to element, but generally means what the <tt class="docutils literal"><span class="pre">size</span></tt> attribute means for the element in HTML.</td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">tabindex</span></tt></td>
<td>What to use for the tabindex of an element. Pieforms manages tabindex automatically, and you can set the tabindex for every element in the form elsewhere, so generally there is no need to set this.</td>
</tr>
</tbody>
</table>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id4" id="supported-elements" name="supported-elements">Supported Elements</a></h2>
<p>The elements that you can use will depend on several things, such as what version of Pieforms you have, what elements you have written or downloaded, and what you have set the search path for plugins as. Here is a list of Pieform elements that come with Pieforms.</p>
<ul class="simple">
<li>button</li>
<li>bytes</li>
<li>calendar</li>
<li>cancel</li>
<li>checkbox</li>
<li>date</li>
<li>expiry</li>
<li>fieldset</li>
<li>file</li>
<li>hidden</li>
<li>html</li>
<li>image</li>
<li>password</li>
<li>radio</li>
<li>select</li>
<li>submitcancel</li>
<li>submit</li>
<li>textarea</li>
<li>text</li>
</ul>
<p><div id="breadcrumbs"><a href="http://pieforms.sourceforge.net/">Pieforms Home</a> &raquo; <a href="../">Documentation Home</a> &raquo; <a href="">Pieforms Elements</a></div></p>
</div>
</div>
</div>

<div id="footer">Pieforms by <a href="http://nigel.mcnie.name/">Nigel McNie</a> and <a href="http://pieforms.sourceforge.net/about#authors">others</a>,
&copy; 2006 Catalyst IT Ltd. Pieforms is released under the <a href="http://gnu.org/licences/gpl.html">GNU GPL</a></div>
</body>
</html>
Return current item: Pieforms