File: README.md

Recommend this page to a friend!

README.md

File:	`README.md`
Role:	Documentation
Content type:	`text/markdown`
Description:	Cless documentation
Class:	Paul's PHP Form Class Compose and display HTML forms in Web pages
Author:	By Paul M. Foster
Last change:
Date:	3 years ago
Size:	`10,946 bytes`

Download

Paul's Form Library

Paul's Form Library is a PHP form library. You use it to make creating forms easier. It saves on writing the whole thing out in HTML.

Field Types

The library allows you to create the following field types:

text
password
select
date
radio
checkbox
textarea
hidden
submit
file

General Use

Normally, the individual fields are defined in an array. This is then either fed to the form class constructor, or fed to the form object via the set() method. In the view, the individual fields are typically called out where needed. For example:

$fields = [
	'username' => [
		'name' => 'username',
		'type' => 'text',
		'size' => 20,
		'maxlength' => 20,
		'required' => 1
	],
	'password' => [
		'name' => 'password',
		'type' => 'password',
		'size' => 10,
		'maxlength' => 20,
		'required' => 1,
	],
	's1' => [
		'name' => 's1',
		'type' => 'submit',
		'value' => 'Send'
	]
];

$form = new form($fields);

The above code would be in the controller. In the view, there might be something like:

<form method="post" action="#">
<label>Username</label>&nbsp;<?php $form->text('username'); ?>
<br/>
<label>Password</label>&nbsp;<?php $form->password('password'); ?>
<br/>
<?php $form->submit('s1'); ?>
</form>

Individual Field Types

What follows are the various field types and the parameters which may be defined for each field type. For the most part, the parameters for each field correspond to attributes of the <input> tag in HTML. For example, every field has a "name" parameter. This corresponds to the "name" attribute, like this:

<input name="name_of_field" ...>

Text Fields

name: This is the index in the POST variable for this field.
type: "text"
label: The label which will be used with the `show()` method
size: This is the how wide the field will be.
maxlength: How many characters can be typed in a field?
class: Here you may specify a class for your text field
required: (0 or 1) This ensures the form won't post until this field is filled in.
value: If the field already has a value, specify it here
javascript: Specify any javascript function which applies to this field

Password Fields

name: This is the index in the POST variable for this field.
type: "password"
label: The label which will be used with the `show()` method
size: This is the how wide the field will be.
maxlength: How many characters can be typed in a field?
class: Here you may specify a class for your text field
required: (0 or 1) This ensures the form won't post until this field is filled in.
value: If the field already has a value, specify it here
javascript: Specify any javascript function which applies to this field

Date Fields

name: This is the index in the POST variable for this field.
type: "date"
label: The label which will be used with the `show()` method
class: Here you may specify a class for your text field
required: (0 or 1) This ensures the form won't post until this field is filled in.
value: If the field already has a value, specify it here; these must be in ISO 8601 format, like 2021-06-22.

Select Fields

Select fields (dropdown menus) require a series of options to work. You must define these before you define the field itself. These options are in an array, where each member contains two components-- a label component called "lbl", and a value component called "val". Like this:

$fruit_options = [
	['lbl' => 'Apple', 'val' => 'A'],
	['lbl' => 'Pear', 'val' => 'P'],
	['lbl' => 'Watermelon', 'val' => 'W']
];

Other parameters:

name: This is the index in the POST variable for this field.
type: "select"
label: The label which will be used with the `show()` method
class: Here you may specify a class for your text field
required: (0 or 1) This ensures the form won't post until this field is filled in.
multi: (0 or 1) Set this if you want to be able to select multiple items
options: The options defined earlier, like `options => $fruit_options,`
value: The default option, if there is one

Radio Fields

Radio fields are like a hybrid of select fields and checkboxes. Like "select" fields, they require options to be defined before the field is specified. This is because, normally, you'd have more than one radio button which the user must select between.

An additional parameter is "direction". This comes about because you would normally have a label for each button. You want the buttons to appear on the right or the left of the label. In some cases, you want your radio buttons to stack one on top of each other. The direction parameter can take on these values:

L: button on the left, label on the right
R: label on the left, button on the right
LV: button on the left, label on the right, buttons stacked
RV: label on the left, button on the right, buttons stacked

The "options" parameter has the same structure as those of the "select" field type. But in the case of radio fields, the "lbl" parameter is the label which will appear next to the button. The "val" parameter is what registers when the particular button is pressed.

Parameters are as follows:

name: This is the index in the POST variable for this field.
type: "radio"
label: The label which will be used with the `show()` method
class: Here you may specify a class for your text field
options: See above discussion
direction: See above discussion
checked: This is the value already existing for this field, if any

Checkbox Fields

The parameters are as follows:

name: This is the index in the POST variable for this field.
type: "checkbox"
label: The label which will be used with the `show()` method
class: Here you may specify a class for your field
value: The value returned if this box is checked
checked: The pre-existing value for this field, if applicable.

Textarea Fields

The parameters:

name: This is the index in the POST variable for this field.
type: "textarea"
label: The label which will be used with the `show()` method
class: Here you may specify a class for your field
maxlength: Maximum characters for this textarea
value: The value returned if this box is checked
cols: Columns for the textarea
rows: Rows for the textarea
wrap: ('hard' or 'soft') The "wrap" parameter for a textarea field
required: (1 or 0) Is this field required?

Hidden Fields

"Hidden" fields are specified in HTML and passed through the POST variable in forms.

The parameters:

name: This is the index in the POST variable for this field.
type: "hidden"
value: The value for this field

File Fields

The "file" field allows you to upload a field to a website. It gives the user a local file browsing window. The parameters are:

name: This is the index in the POST variable for this field.
type: "file"
label: The label which will be used with the `show()` method
class: Here you may specify a class for your field

In order to make a "file" field work, there are two additional requirements. First you must add an "enctype" clause to the <form> tag like this:

<form method="post" action="#" enctype="multipart/form-data">

The second thing needed is a hidden field like this:

<input type="hidden" name="MAX_FILE_SIZE" value="100000000"/>

You can specify this this way:

$fields = [
	'MAX_FILE_SIZE' => [
		'name' => 'MAX_FILE_SIZE',
		'type' => 'hidden',
		'value' => 1000000000
	],
	...
];

Submit Fields

These are the buttons on a form. Parameters as follows:

name: This is the index in the POST variable for this field.
type: "submit"
value: The label which will be on the button

Additional Class Methods

There are two static methods which can be used in the library. The first is the button() method. Here is the function signature:

static function button($legend, $link)

This creates a clickable button with a label on it. The first parameter is the label for the button. The second parameter is the URL you want the user to go to when the button is pressed.

The second method is this:

static function abandon($link)

This is like the "button()" method, except that you don't specify the label; it says Abandon. The parameter you pass is the link the user goes to when he or she presses the button.

How To Populate The Form Object

There are two ways to instantiate or populate the form object. The first way to do it is to pass the fields array to the constructor, like this:

$form = new form($fields)

The second way to populate the form object with fields is to use the set() method. This assumes you've already instantiated a form object. Like this:

$form = new form();
$form->set($fields);

Outputting Fields

There are three ways of outputting fields to your form screen. As shown above, you can use the method corresponding to your field type, like this:

<?php $form->text('name'); ?>

There is a secondary way to call this function, where you feed the method any default value for that field. Like this:

<?php $form->text('name', 'Paul Foster'); ?>

You can accomplish this same thing by using the "value" parameter in specifying your field, as above.

It's worth noting that you can't use the wrong method for your field. That is, you can't use the text() routine to display a "password" field. You'll get an error.

Another way to display a field is to use the output() method, like this:

<?php $form->output('name', 'Paul Foster'); ?>

In this case, you may use the output() method with any field type. It's a sort of a generic method. The only problem with it is that when you're looking over your view code, and you've used this method, you won't know the type of the fields involved.

The third way to display your fields is in aggregate. In other words, you make one call for the whole form, rather than one function call for each field. Like this:

<?php $form->show(); ?>

In order to make this work properly, you must surround it with a table, like this:

<form method="post" action="#">
<table>
<?php $form->show(); ?>
</table>
</form>

Normally, you would manually specify a label for each field, entirely outside of the form method calls. The output() method allows you to avoid this. The output() method will take the "name" parameter of the field definition to act as the label for ths field. This is true unless you also specify a "label" parameter on a field definition. In that case, this "label" string will be used instead.

Testing

There should be a file called formtest.php accompanying this package. This is an actual example of how this code is put together. You can examine this code and copy or modify it as you like.