Documentation/utilities/form.html

   1 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
   2 <head>
   3         <title>CarbonPHP Documentation</title>
   4         <style type="text/css">
   5                 * {
   6                         margin: 0;
   7                         padding: 0;
   8                 }
   9
  10                 a, a:hover {
  11                         background: transparent;
  12                         border-bottom: 1px dotted #666;
  13                         color: #666;
  14                         text-decoration: none;
  15                 }
  16
  17                 a:hover {
  18                         border: 0;
  19                 }
  20
  21                 html {
  22                         font-family: "Lucida Sans Unicode", "Lucida Grande";
  23                         font-size: 14px;
  24                 }
  25
  26                 body {
  27                         background: #fff;
  28                         color: #666;
  29                 }
  30
  31                 h1 {
  32                         font-size: 15px;
  33                         font-weight: bold;
  34                         margin: 0 0 5px 0;
  35                 }
  36
  37                 h2 {
  38                         font-size: 13px;
  39                         font-weight: bold;
  40                         margin: 5px 0 5px 0;
  41                 }
  42
  43                 ol, ul {
  44                         margin: 10px 0 10px 0;
  45                         list-style-position: inside;
  46                 }
  47
  48                 p {
  49                         margin: 5px 0 5px 0;
  50                 }
  51
  52                 .content {
  53                         border: 1px dotted #444;
  54                         margin: 10px;
  55                         padding: 10px;
  56                         text-align: justify;
  57                         width: 700px;
  58                 }
  59
  60                 .example {
  61                         border: 1px solid #ccc;
  62                         background: #eee;
  63                         margin: 10px;
  64                         padding: 10px;
  65                         text-align: left;
  66                 }
  67         </style>
  68 </head>
  69
  70 <body>
  71         <div class="content">
  72                 <h1>Form Utility</h1>
  73
  74                 <p>The form utility file contains functions that assist in working with and creating forms.  You load the
  75                 utility with the following piece of code.</p>
  76
  77                 <div class="example">
  78                         $this->load->utility('form');
  79                 </div>
  80         </div>
  81
  82         <div class="content">
  83                 <h1>form_open()</h1>
  84
  85                 <p>This function creates an opening form tag with a base URL built from your configuration preferences.  It
  86                 will optionally let you add form attributes and hidden input fields.  The main benefit of using this function
  87                 rather than hard coding your own HTML is that it permits your site to be more portable in the event you
  88                 choose to change your URLs.</p>
  89
  90                 <div class="example">
  91                         echo form_open('email/submit');
  92                 </div>
  93
  94                 <p>The above example will create a form that looks like the following.</p>
  95
  96                 <div class="example">
  97                         &lt;form method="post" action="http://www.your-domain.com/index.php/email/submit" /&gt;
  98                 </div>
  99
 100                 <p>Attributes can be added by passing an associative array as the second parameter.</p>
 101
 102                 <div class="example">
 103                         $attr = array('class' => 'someform', 'id' => 'email');<br />
 104                         <br />
 105                         echo form_open('email/submit', $attr);
 106                 </div>
 107
 108                 <p>This code would create the following opening form tag.</p>
 109
 110                 <div class="example">
 111                         &lt;form method="post" action="http://www.your-domain.com/index.php/email/submit"
 112                                 class="someform" id="email" /&gt;
 113                 </div>
 114
 115                 <p>You can create hidden fields by passing an associative array as a the third parameter.</p>
 116
 117                 <div class="example">
 118                         $hidden = array('username' => 'John', 'id' => '2');<br />
 119                         <br />
 120                         echo form_open('email/send', '', $hidden);
 121                 </div>
 122
 123                 <p>The above example will create the following form.</p>
 124
 125                 <div class="example">
 126                         &lt;form method="post" action="http:/www.your-domain.com/index.php/email/submit" /&gt;<br />
 127                         &lt;input type="hidden" name="username" value="John" /&gt;<br />
 128                         &lt;input type="hidden" name="id" value="2" /&gt;
 129                 </div>
 130         </div>
 131
 132         <div class="content">
 133                 <h1>form_input()</h1>
 134
 135                 <p>This function lets you generate a standard text input field.  You can minimally pass the field name
 136                 and a value in the first and second parameters.</p>
 137
 138                 <div class="example">
 139                         echo form_input('username', 'john');
 140                 </div>
 141
 142                 <p>You can pass an associative array containing any data you wish your form to contain.</p>
 143
 144                 <div class="example">
 145                         $data = array(<br />
 146                         &nbsp;&nbsp;&nbsp;&nbsp;'name' => 'username',<br />
 147                         &nbsp;&nbsp;&nbsp;&nbsp;'id' => 'username',<br />
 148                         &nbsp;&nbsp;&nbsp;&nbsp;'value' => 'john',<br />
 149                         &nbsp;&nbsp;&nbsp;&nbsp;'maxlength' => '100',<br />
 150                         &nbsp;&nbsp;&nbsp;&nbsp;'size' => '50',<br />
 151                         &nbsp;&nbsp;&nbsp;&nbsp;'style' => 'width: 100px'<br />
 152                         );<br />
 153                         <br />
 154                         echo form_input($data);
 155                 </div>
 156
 157                 <p>If you would like your form to contain any additional data like JavaScript you can pass it as a string
 158                 in the third parameter.</p>
 159
 160                 <div class="example">
 161                         $js = 'onclick="somefunction();"';<br />
 162                         <br />
 163                         echo form_input('username', 'john', $js);
 164                 </div>
 165         </div>
 166
 167         <div class="content">
 168                 <h1>form_password()</h1>
 169
 170                 <p>This function is identical to <b>form_input()</b> except that it sets it as a password type.</p>
 171         </div>
 172
 173         <div class="content">
 174                 <h1>form_upload()</h1>
 175
 176                 <p>This function is identical to <b>form_input()</b> except that it set it as a file type, allowing it to
 177                 be used to upload files.</p>
 178         </div>
 179
 180         <div class="content">
 181                 <h1>form_textarea()</h1>
 182
 183                 <p>This function is identical to <b>form_input()</b> exception that it generates a 'textarea' type.  Instead
 184                 if maxlength and size attributes in the above example, you will instead specify rows and cols.</p>
 185         </div>
 186
 187         <div class="content">
 188                 <h1>form_dropdown()</h1>
 189
 190                 <p>This function lets you create a standard dropdown field.  The first parameter will contain the name of
 191                 the field, the second parameter is an associative array of options and the third parameter will contain
 192                 the value you wish to be selected by default.</p>
 193
 194                 <div class="example">
 195                         $options = array(<br />
 196                         &nbsp;&nbsp;&nbsp;&nbsp;'small' => 'Small shirt',<br />
 197                         &nbsp;&nbsp;&nbsp;&nbsp;'medium' => 'Medium shirt',<br />
 198                         &nbsp;&nbsp;&nbsp;&nbsp;'large' => 'Large shirt',<br />
 199                         &nbsp;&nbsp;&nbsp;&nbsp;'xlarge' => 'Extra large shirt'<br />
 200                         );<br />
 201                         <br />
 202                         echo form_dropdown('shirts', $options, 'large');
 203                 </div>
 204
 205                 <p>If you wish to add any additional data like JavaScript you can pass it as a string in the fourth
 206                 parameter.</p>
 207
 208                 <div class="example">
 209                         $js = 'onchange="somefunction();"';<br />
 210                         <br />
 211                         echo form_dropdown('shirts', $options, 'large', $js);
 212                 </div>
 213         </div>
 214
 215         <div class="content">
 216                 <h1>form_fieldset()</h1>
 217
 218                 <p>This function lets you generate a fieldset/legend field.</p>
 219
 220                 <div class="example">
 221                         echo form_fieldset('Address Information');<br />
 222                         echo "fieldset content here\n";<br />
 223                         echo form_fieldset_close();<br />
 224                         <br />
 225                         // Produces<br />
 226                         &lt;fieldset id="address_info"&gt;<br />
 227                         &lt;legend>Address Information&lt;/legend&gt;<br />
 228                         form content here<br />
 229                         &lt;/fieldset&gt;
 230                 </div>
 231
 232                 <p>Similar to the other functions, you can submit an associative array in the second parameter
 233                 if you prefer to set addtional attributes.</p>
 234
 235                 <div class="example">
 236                         $attributes = array('id' => 'address_info', 'class' => 'address_info');<br />
 237                         echo form_fieldset('Address Information', $attributes);<br />
 238                         echo "&lt;p&gt;fieldset content here&lt;/p&gt;\n";<br />
 239                         echo form_fieldset_close();<br />
 240                         <br />
 241                         // Produces<br />
 242                         &lt;fieldset id="address_info" class="address_info"&gt;<br />
 243                         &lt;legend&gt;Address Information&lt;/legend&gt;<br />
 244                         &lt;p&gt;form content here&lt;/p&gt;<br />
 245                         &lt;/fieldset&gt;
 246                 </div>
 247         </div>
 248
 249         <div class="content">
 250                 <h1>form_fieldset_close()</h1>
 251
 252                 <p>Produces a closing &lt;fieldset&gt; tag.  The only advantage to using this function is it permits you to pass
 253                 data to it which will be added below to the tag.</p>
 254
 255                 <div class="example">
 256                         $string = "&lt;/div&gt;&lt;/div&gt;";<br />
 257                         <br />
 258                         echo fieldset_close($string);<br />
 259                         <br />
 260                         // Produces:<br />
 261                         &lt;/fieldset&gt;<br />
 262                         &lt;/div&gt;&lt;/div&gt;<br />
 263                 </div>
 264         </div>
 265
 266         <div class="content">
 267                 <h1>form_checkbox()</h1>
 268
 269                 <p>This function lets you generate a checkbox field.</p>
 270
 271                 <div class="example">
 272                         echo form_checkbox('email', 'accept', true);
 273                 </div>
 274
 275                 <p>The third parameter contains a true or false to determine whether the checkbox should be checked or not.</p>
 276
 277                 <p>Similar to the other form functions, you can pass an array of attributes to the functions.</p>
 278
 279                 <div class="example">
 280                         $data = array(<br />
 281                         &nbsp;&nbsp;&nbsp;&nbsp;'name' => 'email',<br />
 282                         &nbsp;&nbsp;&nbsp;&nbsp;'id' => 'email',<br />
 283                         &nbsp;&nbsp;&nbsp;&nbsp;'value' => 'accept',<br />
 284                         &nbsp;&nbsp;&nbsp;&nbsp;'checked' => true,<br />
 285                         &nbsp;&nbsp;&nbsp;&nbsp;'style' => 'width: 10px;'<br />
 286                         );<br />
 287                         <br />
 288                         echo form_checkbox($data);
 289                 </div>
 290
 291                 <p>Just like the other functions if you wish the tag to contain additional data like JavaScript, you
 292                 pass it as a string in the fourth parameter.</p>
 293
 294                 <div class="example">
 295                         $js = 'onclick="somefunction();"';<br />
 296                         <br />
 297                         echo form_checkbox('email', 'accept', true, $js);
 298                 </div>
 299         </div>
 300
 301         <div class="content">
 302                 <h1>form_radio()</h1>
 303
 304                 <p>This function is identical to the <b>form_checkbox()</b> function except it creates a radio type field.</p>
 305         </div>
 306
 307         <div class="content">
 308                 <h1>form_submit()</h1>
 309
 310                 <p>This function lets you generate a standard submit button.</p>
 311
 312                 <div class="example">
 313                         echo form_submit('submit', 'Submit');
 314                 </div>
 315
 316                 <p>As the same as other functions you can submit an associative array in the first parameter if you prefer to
 317                 set your own attributes, the third parameter lets your add extra data for your form like JavaScript.</p>
 318         </div>
 319
 320         <div class="content">
 321                 <h1>form_label()</h1>
 322
 323                 <p>This function lets you generate a &lt;label&gt;.</p>
 324
 325                 <div class="example">
 326                         echo form_label('What is your Name', 'username');<br />
 327                         <br />
 328                         // Would produce:<br />
 329                         &lt;label id="username"&gt;What is your Name&lt;/label&gt;
 330                 </div>
 331
 332                 <p>Similar to the other functions you can submit an associative array in the third parameter.</p>
 333
 334                 <div class="example">
 335                         $attributes = array(<br />
 336                         &nbsp;&nbsp;&nbsp;&nbsp;'class' => 'mycustomclass',<br />
 337                         &nbsp;&nbsp;&nbsp;&nbsp;'style' => 'color: #000;',<br />
 338                         );<br />
 339                         echo form_label('What is your Name', 'username', $attributes);<br />
 340                         <br />
 341                         // Produces:<br />
 342                         &lt;label id="username" class="mycustomclass" style="color: #000;"&gt;What is your Name&lt;/label&gt;
 343                 </div>
 344         </div>
 345
 346         <div class="content">
 347                 <h1>form_reset()</h1>
 348
 349                 <p>This function generates a standard reset button, it is similar to <b>form_submit()</b>.</p>
 350         </div>
 351
 352         <div class="content">
 353                 <h1>form_close()</h1>
 354
 355                 <p>This function produces a closing form tag.  The only advantage to using this function is it allows you to
 356                 pass data to it which will be added below the tag.</p>
 357
 358                 <div class="example">
 359                         $string = '&lt;/div&gt;';<br />
 360                         <br />
 361                         echo form_close($string);<br />
 362                         <br />
 363                         // This produces:<br />
 364                         // &lt;/form&gt;<br />
 365                         // &lt;/div&gt;
 366                 </div>
 367         </div>
 368
 369         <div class="content">
 370                 <h1>form_prep()</h1>
 371
 372                 <p>This function allows you to safely use HTML and characters such as quotes within form elements without
 373                 breaking out of the form.</p>
 374
 375                 <div class="example">
 376                         $string = 'Here is a string containing "quoted" text.';<br />
 377                         <br />
 378                         &lt;input type="text" name="form" value="$string" /&gt;
 379                 </div>
 380
 381                 <p>Since the string contains quoted text so it will cause the form to break.  The <b>form_prep()</b> function
 382                 converts HTML so that it can be used safely.</p>
 383
 384                 <div class="example">
 385                         &lt;input type="text" name="form" value="&lt;?php echo form_prep($string); ?&gt;" /&gt;
 386                 </div>
 387
 388                 <p>If you use any of the form utlity functions the values will automatically be prepped for you.</p>
 389         </div>
 390 </body>
 391
 392 </html>