8.3. Profile checking

Interchange can check forms for compliance with requirements. The mechanism uses a profile, which is set via the mv_form_profile or mv_order_profile variables.

8.3.1. mv_form_profile

The mv_form_profile checks happen before any other action. They are designed to prevent submission of a form if required parameters are not present.

You define the profiles either in scratch space or with files specified in the OrderProfile directive.

Specifications take the form of an order page variable (like name or address), followed by an equals sign and a check type. There are many provided check types, and custom ones can be defined in a user-specified file using the CodeDef configuration directive.

Standard check types:

required

A non-blank value is required in the user session space. It may have been submitted on a previous form.

mandatory

Must be non-blank, and must have been specified on this form, not a saved value from a previous form

phone

The field must look like a phone number, by a very loose specification allowing numbers from all countries

phone_us

Must have US phone number formatting, with area code

state

Must be a US state, including DC and Puerto Rico.

province

Must be a Canadian province or pre-1997 territory.

state_province

Must be a US state or Canadian province.

zip

Must have US postal code formatting, with optional ZIP+4. Also called by the alias us_postcode.

ca_postcode

Must have Canadian postal code formatting. Checks for a valid first letter.

postcode

Must have Canadian or US postal code formatting.

true

Field begins with y, 1, or t (Yes, 1, or True) - not case sensitive

false

Field begins with n, 0, or f (No, 0, or False) - not case sensitive

email

Rudimentary email address check, must have an '@' sign, a name, and a minimal domain

regex

One or more regular expressions (space-separated) to check against. To check that all submissions of the "foo" variable have "bar" at the beginning, do:

            foo=regex ^bar

You can add an error message by putting it in quotes at the end:

       foo=regex ^bar "You must have bar at the beginning of this"

You can require that the value not match the regex by preceding the regex with a ! character (and no space afterwards):

       foo=regex !^bar "You may not have bar at the beginning!"

length

A range of lengths you want the input to be:

       foo=length 4-10

That will require foo be from 4 to 10 characters long.

unique

Tests to see that the value would be a unique key in a table:

       foo=unique userdb Sorry, that username is already taken

filter

Runs the value through an Interchange filter and checks that the returned value is equal to the original value.

       foo=filter entities Sorry, no HTML allowed

To check for all lower-case characters:

            foo=filter lower Sorry, no uppercase characters

Also, there are pragmas that can be used to change behavior:

&charge

Perform a real-time charge operation. If set to any value but "custom", it will use Interchange's CyberCash routines. To set to something else, use the value "custom ROUTINE". The ROUTINE should be a GlobalSub which will cause the charge operation to occur -- if it returns non-blank, non-zero the profile will have succeeded. If it returns 0 or undef or blank, the profile will return failure.

&credit_card

Checks the mv_credit_card_* variables for validity. If set to "standard", it will use Interchange's encrypt_standard_cc routines. This destroys the CGI value of mv_credit_card_number -- if you don't want that to happen (perhaps to save it for sending to CyberCash) then add the word keep on the end.
Example:

        # Checks credit card number and destroys number after encryption
        # The charge operation can never work
    
        &credit_card=standard
        &charge=custom authorizenet
    
        # Checks credit card number and keeps number after encryption
        # The charge operation can now work
    
        &credit_card=standard keep
        &charge=custom authorizenet

You can supply your own check routine with a GlobalSub:

        &credit_card=check_cc

The GlobalSub check_cc will be used to check and encrypt the credit card number, and its return value will be used to determine profile success.

&fail

Sets the mv_nextpage value for a failed check.

        &fail=page4

If the submit process succeeds, the user will be sent to the page page4.

&fatal

Set to '&fatal=yes' if an error should generate the error page.

&final

Set to '&final=yes' if a successful check should cause the order to be placed.

&update

Set to '&update=yes' if a successful check should cause the variable to be copied from the CGI space to the Values space. This is like [update values] except only for that variable.
This is typically used when using a mv_form_profile check so that a failing check will not cause all values to be reset to their former state upon returning to the form.

&return

Causes profile processing to terminate with either a success or failure depending on what follows. If it is non-blank and non-zero, the profile succeeds.

        # Success :)
        &return 1
    
        # Failure :\
        &return 0

Will ignore the &fatal pragma, but &final is still in effect if set.

&set

Set a user session variable to a value, i.e. &set=mv_email [value email]. This will not cause failure if blank or zero.

&setcheck

Set a user session variable to a value, i.e. &set=mv_email [value email]. This will cause failure if set to a blank or zero. It is usually placed at the end after a &fatal pragma would have caused the process to stop if there was an error -- can also be used to determine pass/fail based on a derived value, as it will cause failure if it evaluates to zero or a blank value.

&success

Sets the mv_nextpage value if the profile succeeds. Example:

        &success=page5

If the submit process succeeds, the user will be sent to the page page5.

&update

Normally if an mv_form_profile check fails none of the form values are put in the user session, meaning that the [value ...] tag will not reflect what the user has submitted. If you set &update=yes, then as each variable is checked its value will be updated. Example:

        &update=yes

Even if the profile check fails, any variables checked before the &fatal=yes setting will be updated.

As an added measure of control, the specification is evaluated for the special Interchange tags to provide conditional setting of order parameters. With the [perl] [/perl] capability, quite complex checks can be done. Also, the name of the page to be displayed on an error can be set in the mv_failpage variable.

Error messages are set by appending the desired error message to the line containing the check:

city=required Please fill in your city.

This sets the value of the error associated with name, and can be displayed with the error tag:

        [error name=city show_error=1]