Form Library - Input Fields

<?php

// This is used in the set_field_as_select_plant() method.
// Indicates than an "All Plants" option should be added to drop-down.
define (ALLPLANTS_OPTION, true);

class input_field
{

    /*
    File:       input_field.class.php
    Developer:  Shane Harter
    Created:    Apr 26, 2008
    Version:    1.0

    Description:
    ---------------------------------------------------------------------------------------
    Represents an html input field on a webform class

    Instructions:
    ---------------------------------------------------------------------------------------
    Instantiate and pass-in the field_name, and a reference to the webform object that owns the field
    The webform object is expected to be bound to a data_model object.

    Once constructed, you must define the html attached to the $field. You can do it manually, passing HTML for the input directly
    into set_field().

    Or you can use pre-constructed tempalates in the form of the dozen set_field_as_*() methods. In many cases, these auto methods will
    be perfectly adequate.

    After the field is set, next set the $label. You can set HTML directly to the $this->label property, or you can use the label-builder
    by passing the label text to set_label(). This will build a <label> tag for you automatically.

    The final step is just assigning the $order that the field should be displayed in relation to other $field objects on the webform.

    Dependencies:
    ----------------------------------------------------------------------------------------
    libFormat       v1.0
    libValidate     v1.0
    libArray        v1.1
    webform         v1.0

    */

    var $label;                 // String - HTML or Plain Text - The label for the input field.
    var $field;                 // String - HTML - The input field w/ sprintf() style placeholders.
    var $order;                 // Int - The order in the form layout for this field.
    var $maxlength = 100;       // Int - The maximum number of chars in the field
    var $size = 50;             // Int - The length of the box
    var $readonly = false;      // Bool - Is this field read-only or not?
    var $disabled = false;      // Bool - Is this field disabled or not?

    var $m_data;                // Array - Data for select, checkboxset, or radioset types. Used to build options and mark the appropriate option as selected/checked
    var $m_type;                // String - This will hold the type: text, password, checkbox, radio, file, hidden, button, submit, select or textarea
    var $m_form;                // Object Reference - to the form that this is a part of
    var $m_field_name;          // String - the name of the field referenced in m_bound_field
    var $m_bound_field;         // String Reference - to the property in $this->m_form->m_bound_model that this input field is bound to.
    var $m_comparator;          // Object - Comparator.class.php - Used when iterating the $m_data array to build <select>, checkboxset()'s, and radioset()'s in comparison w/ val in the data_model

    function input_field($field_name, &$webform)
    {
        // This constructor will bind $this to the $webform object, then bind to the specific field (denoted by $field_name) in the $m_bound_model property of $webform
        // @$field_name - The name of the field used in the HTML. Must be Plaintext. Must match the property name in the data_model class (and thusly the db column name)
        // @$webform    - A reference to the webform object this is attached to. Validated as subclass of webform. Must be bound to a data_model class
        // @return      - Void - Fatal Error raised if $this cannot bind to $webform


        // First handle the $field_name. Validate as plaintext.
        // In most cases, passing meta-chars would just cause us to throw a Warning while automatically stripping out the junk.
        // But in the case of the $field_name, this is used in m_bind_field() w/ some variable-variable goodness to link to the corresponding property in the data model.
        // Therefore, it's no good. A fatal will be thrown.
        if ($field_name != htmlentities($field_name))
        {
            $e = new fatal_error('field_name passed to input_field() contains invalid chars. Only HTML-Safe chars will be used. ');
            $e->comment = "[Requested field_name: {$field_name}]";
            $e->class = 'webform';
            $e->commit();
        }

        $this->m_field_name = htmlentities($field_name);

        // Now validate & bind the webform
        // A fatal-error will be raised if this cannot be completed
        if ($this->m_bind_form($webform))
        {
            // Now that we've bound to a webform, and we have a fieldname, we can bind to a specific field in the data_model class.
            // (The Webform is bound to a data_model via the $webform->m_model property
            // A fatal-error will be raised if this cannot be completed
            $this->m_bind_field();

            // Now create a default comparator to be used
            $this->set_comparator(new comparator(S_EQUAL));
        }
    }

    function set_label($label, $over_write = false)
    {
        // This function will add and auto-format the field's label w/ proper <label> tags.
        // If $this->label already has text, and $over_write is not true, the function will fail, a warning will be raised, and false will be returned.
        // Returns Boolean, False on error

        if (empty($this->label) || $over_write)
        {
            $label = htmlentities($label);
            $this->label = "<label class='webform_label' for='{$this->m_field_name}'>{$label}</label>";

            return true;
        }

        $e = new error('set_label() failed. $this->label is not empty and the over_write flag was not set');
        $e->comment = "[Requested label: {$label}] [Existing Label: {$this->label}]";
        $e->class = 'webform';
        $e->fatal = false;
        $e->raise = false;
        $e->log = true;
        $e->commit();

        return false;
    }

    function set_field($html, $over_write = false)
    {
        // This method is used to manually set the field by passing in the HTML w/ whatever webform tags you wish to implement. Seems like %value, at least, would be necessary.
        // Returns Boolean

        /*
            Note: if you're passing in a <select> it's important to know that if you want to have the webform automatically handle the selected element, you need to include
            an %options tag and an $m_data array to build the <option>'s. Otherwise, when the user posts the form, if the form is re-rendered (due to a validation error) it
            will NOT pre-select the users selected element.  The other option is for you to instantiate a NEW webform object on such a re-render and tie it to the same data_model
            the the original form was tied to (literally the same instance, not just the same class) and then render THAT form,  instead of re-rendering the webform that was posted.

            Example:

            if ($_POST)
            {
                $old = webform::load_from_post();
                $new = new myWebform($old->m_model);
                $new->render();
            }

            FURTHER NOTE:
            For these same reasons, it's reccommended that if you'd like to create a set of checkboxes or radio controls, that you let them be auto-created
            using the set_field_as_checkboxset() or set_field_as_radioset(). Creating such controls on your own may yeild strange results if you try to re-render
            the same form after a post.
         */

        if (empty($this->field) || $over_write)
        {
            $this->field = $html;
        }

        $e = new error('set_field() failed. $this->field is not empty and the over_write flag was not set');
        $e->comment = "[Requested Field: {$html}] [Existing Field: {$this->field}]";
        $e->class = 'webform';
        $e->fatal = false;
        $e->raise = false;
        $e->log = true;
        $e->commit();

        return false;
    }

    function set_comparator($comparator)
    {
        // This method accepts a comparator object and sets it to the $this->m_comparator property.
        // This is used when building the options for select, checkboxset, and radioset. As m_data is looped, a comparison is made to the curr value of the $m_bound_field so we
        // know which item to mark as SELECTED (or CHECKED as the case may be). By using a comparator it lets you do more advanced comparisons than simple equality.
        // For example: you may have a plant drop down box. In your data_model, though, that may (ie SHOULD) be a plant OBJECT. A simple comparison would fail. Instead you can create
        // a comparator that then compares the plantID from the drop down box to the plant->plantID field in the data_model. You can do translations, string manipulation (like trim()
        // or strtolower() or whatever), data type conversions, etc.

        // By default a S_EQUALITY type comparator is set.
        // Returns Bool, throws fatal error if improper args are passed.

        if (is_a($comparator, 'comparator'))
        {
            $this->m_comparator = $comparator;
            return true;
        }

        $e = new fatal_error('An error has occured while processing this form.');
        $e->comment = "set_comparator() Failed. A valid comparator object is expeceted.";
        $e->class = 'webform';
        $e->commit();

        return false;
    }

    function render_field()
    {
        // This function will parse the field placeholders and return (hopefully) valid HTML
        // We don't actually parse $this->field because we want to be able to parse-in a future value if/when the form is rendered again after the post.
        // Returns HTML

        return $this->m_parse_field();
    }

    function render_label()
    {
        // This function will parse the field placeholders and return (hopefully) valid HTML
        // We don't actually parse $this->field because we want to be able to parse-in a future value if/when the form is rendered again after the post.
        // Returns HTML

        return $this->m_parse_label();
    }

    //********************************************************************************************************************************************************************************
    // Input auto-builders
    //--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

    function set_field_as_input($over_write = false)
    {
        // This function will add and auto-format the HTML for an <input> field.
        // If $this->field already has content, and $over_write is not true, the function will fail, an error will be raised, and false will be returned

        if (empty($this->field) || $over_write)
        {
            $this->field = "<input type='text' id='%name' name='%name' value='%value' tabindex='%order' maxlength='%maxlength' size='%size' %readonly %disabled>";
            return true;
        }

        $e = new fatal_error('An error has occured while processing this form');
        $e->comment = "set_field_as_input() failed. HTML already exists and the over_write flag is not set. [Existing HTML: {$this->field}]";
        $e->class = 'webform';
        $e->commit();

        return false;
    }

    function set_field_as_textarea($over_write = false)
    {
        // This function will add and auto-format the HTML for an <textarea> field.
        // If $this->field already has content, and $over_write is not true, the function will fail, an error will be raised, and false will be returned

        if (empty($this->field) || $over_write)
        {
            $this->field = "<textarea id='%name' name='%name' tabindex='%order' cols='%size' rows='%textarea_rows' %readonly %disabled>%value</textarea>";
            return true;
        }

        $e = new fatal_error('An error has occured while processing this form');
        $e->comment = "set_field_as_textarea() failed. HTML already exists and the over_write flag is not set. [Existing HTML: {$this->field}]";
        $e->class = 'webform';
        $e->commit();

        return false;
    }

    function set_field_as_password($over_write = false)
    {
        // This function will add and auto-format the HTML for an <input type='password'> field.
        // If $this->field already has content, and $over_write is not true, the function will fail, an error will be raised, and false will be returned

        if (empty($this->field) || $over_write)
        {
            $this->field = "<input type='password' id='%name' name='%name' value='%value' tabindex='%order' size='%size' maxlength='%maxlength' %readonly %disabled>";
            return true;
        }

        $e = new fatal_error('An error has occured while processing this form');
        $e->comment = "set_field_as_password() failed. HTML already exists and the over_write flag is not set. [Existing HTML: {$this->field}]";
        $e->class = 'webform';
        $e->commit();

        return false;
    }

    function set_field_as_checkbox($over_write = false)
    {
        // This function will add and auto-format the HTML for an <input type='checkbox'> field.
        // If $this->field already has content, and $over_write is not true, the function will fail, an error will be raised, and false will be returned

        if (empty($this->field) || $over_write)
        {
            $status = ((bool)$this->m_bound_field) ? ' checked ' : '';
            $this->field = "<input type='checkbox' id='%name' name='%name' value='true' tabindex='%order' %value %readonly %disabled>";
            return true;
        }

        $e = new fatal_error('An error has occured while processing this form');
        $e->comment = "set_field_as_checkbox() failed. HTML already exists and the over_write flag is not set. [Existing HTML: {$this->field}]";
        $e->class = 'webform';
        $e->commit();

        return false;
    }

    // ** Buttons ** //

    function set_field_as_button($over_write = false)
    {
        // This function will add and auto-format the HTML for an <input type='button'> field.
        // If $this->field already has content, and $over_write is not true, the function will fail, an error will be raised, and false will be returned

        if (empty($this->field) || $over_write)
        {
            $this->field = "<input type='button' id='%name' name='%name' value='%value' tabindex='%order' %disabled>";
            return true;
        }

        $e = new fatal_error('An error has occured while processing this form');
        $e->comment = "set_field_as_button() failed. HTML already exists and the over_write flag is not set. [Existing HTML: {$this->field}]";
        $e->class = 'webform';
        $e->commit();

        return false;
    }

    function set_field_as_submit($over_write = false)
    {
        // This function will add and auto-format the HTML for an <input type='submit'> field.
        // If $this->field already has content, and $over_write is not true, the function will fail, an error will be raised, and false will be returned

        if (empty($this->field) || $over_write)
        {
            $this->field = "<input type='submit' id='%name' name='%name' value='Submit' tabindex='%order' %disabled>";
            return true;
        }

        $e = new fatal_error('An error has occured while processing this form');
        $e->comment = "set_field_as_submit() failed. HTML already exists and the over_write flag is not set. [Existing HTML: {$this->field}]";
        $e->class = 'webform';
        $e->commit();

        return false;
    }

    // ** Data-Bound Fields ** //

    function set_field_as_select($data, $over_write = false)
    {
        // This function will add and auto-format the HTML for an <select> field.
        // If $this->field already has content, and $over_write is not true, the function will fail, an error will be raised, and false will be returned

        if (empty($this->field) || $over_write)
        {
            if (is_array($data))
            {
                $this->m_data = $data;

                // Now add the wrapping <select>
                $this->field = '<select id="%name" name="%name" tabindex="%order" %disabled>%options</select>';

                return true;
            }

            $e = new fatal_error('An error has occured while processing this form');
            $e->comment = "set_field_as_select() failed. The data parameter expects an array. [Data: {$data}]";
            $e->class = 'webform';
            $e->commit();
        }

        $e = new fatal_error('An error has occured while processing this form');
        $e->comment = "set_field_as_select() failed. HTML already exists and the over_write flag is not set. [Existing HTML: {$this->field}]";
        $e->class = 'webform';
        $e->commit();

        return false;
    }

    function set_field_as_select_m($data, $over_write = false)
    {
        // This function will add and auto-format the HTML for an <select MULTIPLE> field.
        // If $this->field already has content, and $over_write is not true, the function will fail, an error will be raised, and false will be returned

        if (empty($this->field) || $over_write)
        {
            if (is_array($data))
            {
                $this->m_data = $data;

                // Now add the wrapping <select>
                $this->field = '<select multiple id="%name" name="%name[]" tabindex="%order" %disabled>%options</select>';

                return true;
            }

            $e = new fatal_error('An error has occured while processing this form');
            $e->comment = "set_field_as_select_m() failed. The data parameter expects an array. [Data: {$data}]";
            $e->class = 'webform';
            $e->commit();
        }

        $e = new fatal_error('An error has occured while processing this form');
        $e->comment = "set_field_as_select_m() failed. HTML already exists and the over_write flag is not set. [Existing HTML: {$this->field}]";
        $e->class = 'webform';
        $e->commit();

        return false;
    }

    function set_field_as_checkboxset($data, $over_write = false)
    {
        // This function will add and auto-format the HTML for a set of <input type='checkbox'> fields.
        // If $this->field already has content, and $over_write is not true, the function will fail, an error will be raised, and false will be returned

        if (empty($this->field) || $over_write)
        {
            if (is_array($data))
            {
                $this->m_type = 'checkbox';
                $this->m_data = $data;
                return true;
            }

            $e = new fatal_error('An error has occured while processing this form');
            $e->comment = "set_field_as_checkboxset() failed. The data parameter expects an array. [Data: {$data}]";
            $e->class = 'webform';
            $e->commit();
        }

        $e = new fatal_error('An error has occured while processing this form');
        $e->comment = "set_field_as_select() failed. HTML already exists and the over_write flag is not set. [Existing HTML: {$this->field}]";
        $e->class = 'webform';
        $e->commit();

        return false;
    }

    function set_field_as_radioset($data, $over_write = false)
    {
        // This function will add and auto-format the HTML for a set of <input type='radio'> fields.
        // If $this->field already has content, and $over_write is not true, the function will fail, an error will be raised, and false will be returned

        if (empty($this->field) || $over_write)
        {
            if (is_array($data))
            {
                $this->m_type = 'radio';
                $this->m_data = $data;
                return true;
            }

            $e = new fatal_error('An error has occured while processing this form');
            $e->comment = "set_field_as_radioset() failed. The data parameter expects an array. [Data: {$data}]";
            $e->class = 'webform';
            $e->commit();
        }

        $e = new fatal_error('An error has occured while processing this form');
        $e->comment = "set_field_as_select() failed. HTML already exists and the over_write flag is not set. [Existing HTML: {$this->field}]";
        $e->class = 'webform';
        $e->commit();

        return false;
    }

    // ** Special Fields ** //

    function set_field_as_select_plant($all_plants_option = false, $over_write = false)
    {
        // This function will add and auto-format the HTML for an <select> field.
        // If $this->field already has content, and $over_write is not true, the function will fail, an error will be raised, and false will be returned

        if (empty($this->field) || $over_write)
        {
            $this->m_data = array();

            if ($all_plants_option)
            {
                $this->m_data[0] = 'ALL Plants';
            }

            $plants = plantCollection::load_all();
            foreach($plants->items as $plant)
            {
                $this->m_data[$plant->plantID] = $plant->shortname;
            }
            unset($plants);


            // Now add the wrapping <select>
            $this->field = '<select id="%name" name="%name" tabindex="%order" %disabled>%options</select>';

            return true;

        }

        $e = new fatal_error('An error has occured while processing this form');
        $e->comment = "set_field_as_select_plant() failed. HTML already exists and the over_write flag is not set. [Existing HTML: {$this->field}]";
        $e->class = 'webform';
        $e->commit();

        return false;
    }

    // ** Miscellaneous Fields ** //

    function set_field_as_upload($over_write = false)
    {
        // This function will add and auto-format the HTML for an <input type='file'> field.
        // If $this->field already has content, and $over_write is not true, the function will fail, an error will be raised, and false will be returned

        if (empty($this->field) || $over_write)
        {
            $this->field = "<input type='file' id='%name' name='%name' tabindex='%order' %disabled>";
            return true;
        }

        $e = new fatal_error('An error has occured while processing this form');
        $e->comment = "set_field_as_upload() failed. HTML already exists and the over_write flag is not set. [Existing HTML: {$this->field}]";
        $e->class = 'webform';
        $e->commit();

        return false;
    }

    function set_field_as_hidden($over_write = false)
    {
        // This function will add and auto-format the HTML for an <input type='hidden'> field.
        // If $this->field already has content, and $over_write is not true, the function will fail, an error will be raised, and false will be returned

        if (empty($this->field) || $over_write)
        {
            $this->field = "<input type='hidden' id='%name' name='%name' value='%value'>";
            return true;
        }

        $e = new fatal_error('An error has occured while processing this form');
        $e->comment = "set_field_as_hidden() failed. HTML already exists and the over_write flag is not set. [Existing HTML: {$this->field}]";
        $e->class = 'webform';
        $e->commit();

        return false;
    }


    //********************************************************************************************************************************************************************************
    // Private Methods
    //--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
    function m_detect_type()
    {
        // This method is used to determine what kind of element is being used by munging the $this->field var
        // Populates $this->m_type and returns void

        // Define and INSTR comparator that will look for the
        // second argument inside the first, case insensitive.
        $o = new comparator(S_INSTR);

        switch(true)
        {
            case ($o->evaluate($this->field, "type='text'")):
            case ($o->evaluate($this->field, 'type="text"')):

                $this->m_type = 'text';
                break;

            case ($o->evaluate($this->field, "type='password'")):
            case ($o->evaluate($this->field, 'type="password"')):

                $this->m_type = 'password';
                break;

            case ($o->evaluate($this->field, "type='checkbox'")):
            case ($o->evaluate($this->field, 'type="checkbox"')):

                $this->m_type = 'checkbox';
                break;

            case ($o->evaluate($this->field, "type='radio'")):
            case ($o->evaluate($this->field, 'type="radio"')):

                $this->m_type = 'radio';
                break;

            case ($o->evaluate($this->field, "type='file'")):
            case ($o->evaluate($this->field, 'type="file"')):

                $this->m_type = 'file';
                break;

            case ($o->evaluate($this->field, "type='hidden'")):
            case ($o->evaluate($this->field, 'type="hidden"')):

                $this->m_type = 'hidden';
                break;

            case ($o->evaluate($this->field, "type='button'")):
            case ($o->evaluate($this->field, 'type="button"')):

                $this->m_type = 'button';
                break;

            case ($o->evaluate($this->field, "type='submit'")):
            case ($o->evaluate($this->field, 'type="submit"')):

                $this->m_type = 'submit';
                break;

            case ($o->evaluate($this->field, '<select')):

                $this->m_type = 'select';
                break;

            case ($o->evaluate($this->field, '<textarea')):

                $this->m_type = 'textarea';
                break;

        }
    }

    function m_build_options()
    {
        // This method is used to parse the $m_data array into <option> tags for selects.
        // We have to re-build the <option> tags on ever render so we can mark the correct one as selected.
        // Returns HTML <option> tags

        $options = '';

        if ('select' == $this->m_type && is_array($this->m_data))
        {

            // If this has associative keys, use the array key as the HTML value and the array value as the Label.
            // Otherwise, use the array value as both the HTML value and HTML label
            if (libArray::is_associative_keys($this->m_data))
            {
                foreach ($this->m_data as $value => $label)
                {
                    // Determine if this is the selected value before running it thru plain()
                    // If multiple selections are allowed, the result will be an array in the $_POST, thus the in_array()
                    $status = ($this->m_comparator->evaluate($this->m_bound_field, $value) || @in_array($value, $this->m_bound_field)) ? ' selected' : '';

                    $value = htmlentities($value);
                    $label = htmlentities($label);

                    $options .= "<option value='{$value}'{$status}>{$label}</option>";
                }
            }
            else
            {
                // The $data array is single dim.
                // This means that the <select> options will use the same key as display name

                foreach ($this->m_data as $value)
                {
                    // Determine if this is the selected value before running it thru html_safe()
                    $status = ($value == $this->m_bound_field) ? ' selected' : '';

                    $value = @htmlentities($value);

                    $options .= "<option{$status} value='{$value}'>{$value}</option>";
                }
            }
        }

        return $options;
    }

    function m_build_checkboxset()
    {
        // This method is used to parse the $m_data array into <input type='checkbox'> tags for a checkboxset.
        // We have to re-build the checkboxset on ever render so we can mark the correct one(s) as selected.
        // Returns HTML tags

        $checkboxset = '';

        if ('checkbox' == $this->m_type && is_array($this->m_data))
        {
            if (libArray::is_associative_keys($this->m_data))
            {
                // The $data array is an array of arrays.
                // This means each checkbox  has a corresponding text label in the [1] position of the nested-arrays

                foreach ($this->m_data as $value => $label)
                {
                    // Determine if this is the selected value before running it thru html_safe()
                    // If more than one box is checked in the checkboxset, it'll be an array in the $_POST
                    $status = ($this->m_comparator->evaluate($this->m_bound_field, $value) || @in_array($value, $this->m_bound_field)) ? ' checked' : '';

                    $value = @htmlentities($value);
                    $label = @htmlentities($label);

                    // We put the label after the checkbox so they will all be left-aligned
                    $checkboxset .= "<br><input type='checkbox' name='%name[]' id='%name_{$value}' value='{$value}'{$status} %disabled><label for='%name_{$value}'>{$label}</label>";
                }
            }
            else
            {
                // The $data array is single dim.
                // This means that the checkboxeswill use the same key as display name

                foreach ($this->m_data as $value)
                {
                    // Determine if this is the selected value before running it thru html_safe()
                    $status = ($value == $this->m_bound_field) ? ' checked' : '';

                    $value = @htmlentities($value);

                    $checkboxset .= "<br><input type='checkbox' name='%name[]' id='%name_{$value}' value='{$value}'{$status} %disabled><label for='%name_{$value}'>{$value}</label>";
                }
            }
        }

        return $checkboxset;
    }

    function m_build_radioset()
    {
        // This method is used to parse the $m_data array into <input type='radio'> tags for a radioset.
        // We have to re-build the checkboxset on ever render so we can mark the correct one(s) as selected.
        // Returns HTML tags

        $radioset = '';

        if ('radio' == $this->m_type && is_array($this->m_data))
        {
            if (libArray::is_associative_keys($this->m_data))
            {
                // The $data array is an array of arrays.
                // This means each radio option has a corresponding text label in the [1] position of the nested-arrays

                foreach ($this->m_data as $value => $label)
                {
                    // Determine if this is the selected value before running it thru html_safe()
                    $status = ($this->m_comparator->evaluate($this->m_bound_field, $value)) ? ' checked ' : '';

                    // Clense them...
                    $value = @htmlentities($value);
                    $label = @htmlentities($label);

                    // We put the label after the textbox so the textboxes will all be left-aligned
                    $radioset .= "<br><input type='radio' name='%name' id='%name_{$value}' value='{$value}' {$status} %disabled><label for='%name_{$value}'>{$label}</label>";
                }
            }
            else
            {
                // The $data array is single dim.
                // This means that the <select> options will use the same key as display name

                foreach ($this->m_data as $value)
                {
                    // Determine if this is the selected value before running it thru htmlentities()
                    $status = ($value == $this->m_bound_field) ? ' checked ' : '';

                    $value = @htmlentities($value);

                    $radioset .= "<br><input type='radio' id='%name_{$value}' name='%name' value='{$value}' {$status} %disabled>";
                }
            }
        }

        return $radioset;
    }

    function m_parse_label()
    {
        // This private function will parse the place-holder values in $this->field
        // Valid placeholders: %name
        // Returns Void

        $label = $this->label;
        $label = str_replace('%name', $this->m_field_name, $label);

        return $label;
    }

    function m_parse_field()
    {
        // This private function will parse the place-holder values in $this->field
        // Valid placeholders: %name, %order, %value, %maxlength, %size, %readonly, %disabled, %textarea_rows, %options
        // Returns Void

        // Always act on a local copy. The contents of $this->field are NEVER parsed. It retains the webform tags so we can
        // re-parse new values into it if the form is posted and re-rendered (for example, to display validation errs and give user a chance to fix them)
        $field = $this->field;

        // First, determine what kind of field this is.
        // It doesn't matter here at this step, but we'll need to know for after the form gets posted and now is the best time to run the check
        $this->m_detect_type();

        // Next, parse the %value.
        // This is going to be different depending on the field type.
        switch ($this->m_type)
        {
            case 'text':
            case 'password':
            case 'hidden':
            case 'textarea':
            case 'file':
            case 'button':
            case 'submit':
                $field = str_replace('%value', $this->m_bound_field, $field);
                break;

            case 'checkbox':
                if (is_array($this->m_data))
                {
                    // Checkbox Set. Must be rebuilt from $m_data
                    $field = $this->m_build_checkboxset();
                }
                else
                {
                    // Single Checkbox.
                    $field = ((bool)$this->m_bound_field) ? str_replace('%value', ' checked ', $field) : str_replace('%value', '', $field);
                }
                break;

            case 'radio':
                if (is_array($this->m_data))
                {
                    // Checkbox Set. Must be rebuilt from $m_data
                    $field = $this->m_build_radioset();
                }
                else
                {
                    // Single Checkbox.
                    $field = ((bool)$this->m_bound_field) ? str_replace('%value', ' checked ', $field) : str_replace('%value', '', $field);
                }
                break;

            case 'select':
                // At present, %value is N/A when dealing w/ <select>
                break;
        }


        $field = str_replace('%name',       $this->m_field_name,    $field);
        $field = str_replace('%order',      $this->order,           $field);

        $field = str_replace('%maxlength',  $this->maxlength,       $field);
        $field = str_replace('%size',       $this->size,            $field);

        $field = str_replace('%readonly',   ($this->readonly) ? 'readonly' : '', $field);
        $field = str_replace('%disabled',   ($this->disabled) ? 'disabled' : '', $field);

        // This is used to figure out the rows of the textarea
        // Simply taking the maxlength, dividing by $size (which is used in the cols attribute of a textarea) to determine needed rows
        $field = str_replace('%textarea_rows',  ($this->maxlength / $this->size > 1) ? intval($this->maxlength / $this->size) : 1,  $field);

        // This is going to re-build the <options> on every call so we can keep the selected option current.
        // See comments in set_field() for more info
        //$field = str_replace('%options', $this->m_build_options(), $field);
        $field = preg_replace('/%options/', $this->m_build_options(), $field );

        return $field;
    }

    function m_bind_form($webform)
    {
        // Expects a reference to a valid webform object.
        // Throws fatal error if not supplied

        if (false == is_subclass_of($webform, 'webform'))
        {
            $e = new fatal_error('An error has occured while processing this form');
            $e->comment = 'input_field object could not bind form. A valid webform object is expected.';
            $e->class = 'webform';
            $e->commit();

            return false;
        }

        // It's all validated.
        // Bind the form to m_form, and bind the appropriate field on the form's bound data_model.
        $this->m_form = $webform;

        return true;
    }

    function m_bind_field()
    {
        // This method expects the object to already be bound to a webfrom and have a m_field_name set.
        // It will connect to the data model via the webform and create a reference to the matching property.
        // Returns Boolean.

        if (false == is_subclass_of($this->m_form->m_model, 'data_model'))
        {
            $e = new fatal_error('An error has occured while processing this form');
            $e->comment = 'input_field object could not bind form. The form object is valid, but it does not contain a valid data_model object';
            $e->class = 'webform';
            $e->commit();

            return false;
        }

        $this->m_bound_field =& $this->m_form->m_model->{$this->m_field_name};

        return true;
    }
}

?>