Perfect Format - Format and Validate Web Page Input
Perfect Format
(c) Copyright 2002 - 2004, Evans Programming
All Rights Reserved
End User License Agreement (EULA)
Perfect Format License Agreement
(c) Copyright 2002 - 2004, Evans Programming
All Rights Reserved
Please read the terms and conditions of this agreement carefully before using Perfect Format or it's associated programs and documentation. This agreement represents the entire understanding between you and Evans Programming, concerning Perfect Format, and supersedes any prior agreements.
Evans Programming, hereafter referred to as the Author, has developed certain programming and software to be covered by the terms of this agreement.
The Perfect Format software, hereinafter referred to as the Program, embodies and reflects certain Trade Secrets and Copyrights of the Author.
BY INSTALLING OR USING THIS SOFTWARE YOU ARE AGREEING TO BECOME BOUND BY THE TERMS OF THIS AGREEMENT. IF YOU DO NOT AGREE TO THE TERMS OF THIS AGREEMENT THEN DO NOT INSTALL OR USE THE PROGRAM.
LICENSE GRANT: The Author grants to you, and you accept upon first use, a non-exclusive right to use the software contained herein as authorized by this agreement.
Licenser's Rights: You acknowledge and agree that the Program consists of proprietary products of the Author, protected under U.S. copyright law and trade secret laws of general applicability.
You are granted a limited right of use as follows: You may install the trial version of the program for 30 days for the purposes of evaluation. 30 days after first use of the trial program the commercial version of the program must be purchased or the trial version must be uninstalled.
You may use the trial version for development purposes, for an unlimited period, if the development is specifically targeted to be deployed to a web server that has a registered commercial version of the program installed.
One copy of the program must be purchased for each web server domain name that the program is installed on when used for other than evaluation purposes.
IMPORTANT! If a single physical computer has multiple web sites, a separate copy of Perfect Format MUST be purchased and installed for each web site where Perfect Format will be used.
The registration code supplied at time of purchase may NEVER be distributed to anyone!
DISTRIBUTION OF A REGISTRATION CODE TO ANYONE IS A VIOLATION OF THIS AGREEMENT!
You may not distribute the Program in any way not specified in this agreement.
Licensed "As Is" And Limitation Of Warranties: The Program and software subject to this Agreement are licensed to you "AS IS" and the Author disclaims any and all warranties, whether expressed or implied, including without limitation any implied warranties of merchantability or fitness for a particular use.
The Author and any of his associates shall not be liable or responsible for any damages resulting to you or others from the use or misuse of the Program. You assume full responsibility for determining what use(s) the Program serves, if any, and whether the Program meets your requirements. The Author makes no representations whatsoever concerning the performance, acceptability and/or compatibility with your equipment and operation of the Program provided.
You agree that in no event shall the Author be liable for any indirect, incidental, consequential, special, or exemplary damages or lost profits, even if the Author has been advised of the possibility of such damages. You further agree that if for any reason the Author is found to be liable to you as a result related to the use of the Program, that as partial consideration for the Author granting you this license, you agree that the Author's sole and exclusive cumulative liability to you or others shall be no greater than the amount paid by you to purchase the program.
The Author does not warrant that the Program will function without error or meet your requirements.
TERMINATION OF LICENSE: This license granted you is in effect until terminated. The license will terminate if you fail to comply with any terms or conditions of this agreement. You agree upon termination to destroy all Program copies in your possession and to complete a form, to be provided by the Author, testifying to the destruction of the Program. Upon termination the Author can enforce any rights provided by law. The provisions of this Agreement which protect the property rights of the Author shall remain in effect after termination.
GENERAL: If any portion of this agreement is deemed invalid by a court having jurisdiction, that particular provision shall be deemed deleted and will not affect the validity of any other provisions of this agreement.
Proprietary Protection: You shall devote your best efforts, consistent with the practices and procedures under which you protect your own proprietary information and materials, to protect the Program against any unauthorized or unlawful use or copying.
The Program may not be altered or decompiled.
The specifications of this product and the terms and conditions of its license are subject to change at any time upon the Author's discretion without prior or future notification to you.
Acceptance: You agree to all the terms, conditions and limitations of this agreement upon first use of the program covered hereby.
THIS PROGRAM IS THE CONFIDENTIAL AND PROPRIETARY PRODUCT OF THE AUTHOR. ANY UNAUTHORIZED USE, REPRODUCTION OR TRANSFER OF THIS PROGRAM IS STRICTLY PROHIBITED.
Perfect Format
(c) Copyright 2002 - 2004, Evans Programming
All Rights Reserved
Evans Programming
Web: http://www.EvansProgramming.com
Phone: 1-847-882-1378
Contacting Evans Programming
Evans Programming provides free upgrades and technical support to registered users.
Orders can be placed from the Evans Programming Web site.
If you need support, please visit our web site and try our Knowledge Base Search page. If you don’t find a solution there, please visit our Support page and enter and issue or ask a question there. This will help insure that you give us all the information that we need to provide a quick and accurate response.
We pride ourselves in our customer support, and we will do our best to help you if you ask.
IMPORTANT! When contacting Evans Programming, include an e-mail address where you can be contacted, if possible.
Web: http://www.EvansProgramming.com
Phone: 1-847-401-8450
What is Perfect Format?
Perfect Format is an HTML Component (HTC) that formats and validates web page input. Perfect Format decreases web page development time and increases web page useability. Phone numbers fields, numeric fields, date fields and many more input types can be masked so that input is controlled as data is entered, keystroke by keystroke.
Perfect Format is easy to use for web page designers, developers and users, requires little or no programming and does not have to be installed on the client browser.
IMPORTANT! Perfect Format is compatible with the Microsoft Internet Explorer Browser version 5.0 and higher only!
Perfect Format works on all web server platforms because it is 100% client-side code.
Web Server Installation
Perfect Format is an HTML Component (HTC). The Perfect_Format.htc contains the entire Perfect Format functionality. To install the Perfect_Format.htc, simply copy it to the web server where it will be used. Any location that can be accessed from a web browser is an acceptable location.
Perfect Format must be on the same web server and domain name as the pages that will use it. If you are developing on a local PC for later deployment to a web server, you will either need to purchase a second copy of Perfect Format, or use the Perfect Format trial version. See the End User License Agreement for complete details.
Adding Perfect Format Behavior to Web Pages
Perfect Format is implemented as one or more behavior(s). To add the Perfect Format behavior to a web page, add the following statement in the pages’ HEAD tag.
<STYLE>
.PerForm {behavior:url(/_include/lib/perfect_format.htc)}
</STYLE>
Change the url specification, as required, to match the actual location of the perfect_format.htc file on your web server. The class name of the first Perfect Format behavior added should be named "PerForm".
Additional class names that implement the Perfect Format behavior may also be added. This allows you to easily apply different styles.
IMPORTANT! While a class named 'PerForm' implementing the Perfect Format behavior is not specifically required, the trial version does require at least one textarea to reference a class name of 'Perform' (although the textarea may be hidden if desired).
<STYLE>
.PerForm
{
behavior:url(/_include/lib/perfect_format.htc);
}
.InputMask1
{
behavior:url(/_include/lib/perfect_format.htc);
font-family: Tahoma;
font-size: 11px;
height: 17px;
border: 1px solid #CCCCFF;
overflow: hidden;
}
.InputMask2
{
behavior:url(/_include/lib/perfect_format.htc);
font-family: Tahoma;
font-size: 9px;
height: 17px;
border: 1px solid #CCCCFF;
overflow: hidden;
}
</STYLE>
Adding The PerForm Class to TEXTAREA Tag(s)
Adding the Perfect Format behavior exposes a class named PerForm (other class names that implement the Perfect Format behavior may also be defined - refer to above section for details). Perfect Format class names are associated with a TEXTAREA whenever Perfect Format functionality is desired. To add Perfect Format functionality, define a TEXTAREA field and assign it a class name that implements the Perfect Format behavior as shown in the example below:
Perfect Format Example: <TEXTAREA name='txtInput'
Mask = 'mm/dd/yyyy' OnIncomplete='vbscript:txtInput_OnIncomplete'
cols='20' Class='PerForm' style='overflow:hidden' rows='1'></TEXTAREA>
Note: The properties in red should always be included without change. The OnIncomplete event handler is optional, but recommended, and may be implemented in jscript or vbscript as shown. Change cols to adjust the width of your text field as required (should be large enough to that the entire mask is visible when the field has the focus).
IMPORTANT! For pages with a large number of PerForm fields, you can greatly increase performance by dynamically loading the PerForm Class. For details please see Performance Tips - Tuning For Speed.
Adding Validations
Perfect Format validates each character as it is typed. However, if a user exits a partially completed field you may wish to display a message or take additional action.
When a PerForm field looses focus, the OnIncomplete event can be used to handle incomplete data entry validations. The OnIncomplete event fires whenever a partially completed PerForm field looses the focus. The following example uses the OnIncomplete event to display a message if txtInput looses the focus when if contains only partial data.
<script language='vbscript'>
sub txtInput_OnIncomplete()
alert "Invalid data entered"
txtInput.Clear
txtInput.Focus
End Sub
</script>
Using A Perfect Format Field
Date, time and numeric masks have shortcut keys and auto-fill features:
When you enter a Perfect Format field you are in overtype mode. Pressing the [Insert] key toggles between insert and overtype mode. Insert mode is ignored in date and time masks. This is because, for example, allowing 09/22/2002 to become 01/92/2200 is forbidden.
When deleting or backspacing in a field using a date or time mask, the data to the right of the edit cursor is also deleted. This is because, for example, allowing 09/22/2002 to become 92/22/002_ is forbidden.
Data must match the mask of a field when pasting. If the data does not match a field’s mask the paste will be ignored.
To select an entire field, press the [F2] function key.
Performance Tips - Tuning For Speed
For pages that have a large number of PerForm fields, it is recommended that each field be dynamically loaded. Dynamically loading the PerForm class greatly improves performance when a large number of fields are used. However, using Perfect Format in this manner requires a few extra lines of code.
<script language='vbscript'>
Sub LoadMask(object)
object.className="PerForm"
End Sub
</script>
Perfect Format Example: <TEXTAREA name='txtInput'
Mask = 'mm/dd/yyyy' OnIncomplete='vbscript:txtInput_OnIncomplete'
cols='20' onFocus='vbscript:LoadMask(me)' style='overflow:hidden' rows='1'></TEXTAREA>
Class='Perform'
...has been replaced with...
onFocus='vbscript:LoadMask(me)'.
Also a LoadMask method capable of working with all PerForm fields on the page has been added.
This change, from the standard way of Adding The PerForm Class to TEXTAREA Tag(s), causes each PerForm field to be initialized the first time it gets the focus. The standard method initializes all PerForm fields when the page first loads.
However, nothing is ever that easy. Now that the page load is faster, holding down the [Tab] key to quickly navigate between fields has been slowed. The following change will remedy that by only initializing a Perform field when the cursor comes to rest in a field.
<script language='vbscript'>
Sub LoadMask(object)
if window.event.keyCode=9 then ' If tab key pressed
object.className="PerForm"
end if
End Sub
Sub LoadMaskClick(object)
object.className="PerForm"
End Sub
</script>
Perfect Format Example: <TEXTAREA name='txtInput'
Mask = 'mm/dd/yyyy' OnIncomplete='vbscript:txtInput_OnIncomplete'
cols='20' onKeyUp='vbscript:LoadMask(me)'
onClick='vbscript:LoadMaskClick(me)' style='overflow:hidden' rows='1'></TEXTAREA>
Now the PerForm class is only initialized when the field is clicked, or when the [tab] key is released in a field.
Other Issues
When a page is refreshed, the dynamically loaded field's mask (the mask, not the value) that has the focus is left visible. Also, the first PerForm field will need to be initialized when the page loads. Adding something like the following in the window_onLoad() event will do the job.
<script language='vbscript'>
Sub window_onLoad()
with document
for x = 0 to (.all.length - 1)
if .all(x).tagName="TEXTAREA" then
.all(x).value=""
end if
next
end with
frmShow.txtFirstName.focus
frmShow.txtFirstName.className="PerForm"
End Sub
</script>
Other Sources of Information
See the Examples for a complete implementation of dynamically loaded Perform classes.
Escape Character
Perfect Format uses a backslash ("\") to represent an escape character. An escape character may be used in masks to indicate that another mask character is meant literally and not as a mask character.
For example, suppose you wanted a mask that appeared as #___ [___] and that allowed only numeric entry in the underscored positions. The #, [ and ] characters are mask characters with special meaning and cannot automatically be used literally. The MaskChars property could provide a partial solution, but using an escape character and specifying a mask of "\#### \[###\]" is the best solution in this case.
IMPORTANT! The escape character cannot be used with masks that have built-in logic. For instance escape characters cannot be used with the following masks...
So, while you cannot use the escape character to create masks like...
You can use escape characters to create masks like...
You can use the escape character to force mask characters to be taken literally then use those character(s) in masks to produce elaborate results as shown in the below example...
Furthermore, you can create custom masks using Perfect Formats' onPfKeyUp, onPfKeyDown and onPfKeyPress events in combination with the curPos, pfKeyCode, pfAltKey, pfCtrlKey, pfShiftKey and pfReturnValue properties.
Methods, Properties and Events
AfterBlur
An event that is raised after the standard onBlur event completes.
Remarks
Using the AfterBlur event allows you to override values in PerForm fields that are set by Perfect Format when the a fields' focus is lost.
If it is not handled at the element (TEXTAREA) level, the event does not bubble up to the document level.
CheckForComplete
A property that sets / gets if a mask is checked, during the onBlur and onPaste events, to insure that the data exactly matches a mask's requirements.
Syntax
Object.CheckForComplete = blnValue
| Parameter | Definition |
| Object | A TEXTAREA name that has the PerForm class applied. |
| blnValue | A boolean value equal to True or False. |
Remarks
Default value is true. A mask is generally checked during an onBlur event to insure that a field is completely filled. Also, a mask is generally checked during an onPaste event to insure that the data being pasted, including the mask characters, exactly match the target mask.
Setting this value to false allows a partial fill of a field during a paste operation. Setting this value to false also prevents the OnIncomplete event from firing.
Clear
A function that clears the data from a PerForm field, leaving the bare mask.
Syntax
Object.Clear()
| Parameter | Definition |
| Object | A TEXTAREA name that has the PerForm class applied. |
CommasOnFocus
A property that sets / gets if commas in a numeric field are visible when the field has the focus.
Syntax
Object.CommasOnFocus = blnValue
| Parameter | Definition |
| Object | A TEXTAREA name that has the PerForm class applied. |
| blnValue | A boolean value equal to True or False. |
Remarks
Default value is true (commas are normally visible when a numeric field has the focus).
This value is set false if the FlexMask property is set true.
CurPos
A property that sets / gets the cursor position within a PerForm field.
Syntax
Object.CurPos = intValue
| Parameter | Definition |
| Object | A TEXTAREA name that has the PerForm class applied. |
| intValue | An integer that is the cursor position. Position is one based. |
FlexMask
A property that sets / gets if a numeric field should dynamically expand as numbers are entered.
Syntax
Object.FlexMask = blnValue
| Parameter | Definition |
| Object | A TEXTAREA name that has the PerForm class applied. |
| blnValue | A boolean value equal to True or False. |
Remarks
Default value is false (numeric fields normally start out the size of their related masks).
If set true, CommasOnFocus is automatically set to false.
IsComplete
A function that returns true or false to indicate if a mask’s validation requirements have been met.
Syntax
Boolean = Object.IsComplete()
| Parameter | Definition |
| Object | A TEXTAREA name that has the PerForm class applied. |
| Boolean | The value returned from the function call. Boolean data type. |
Remarks
If the mask has no data entered, or the masks validation requirements have been met, this function returns true.
This function is similar to the logic that occurs during an OnIncomplete event.
Sometimes validations beyond the capabilities of the built-in validations are required. In such a case it may make more sense to use a standard onBlur event instead of Perfect Format’s onIncomplete event. The IsComplete() function can be used in an onBlur event to add the OnIncomplete functionality. Then you can add any additional validation that is required. Basically this function allows you to combine onBlur and onIncomplete functionality into one event.
IsEmpty
A function that returns true or false to indicate if any data has been entered in a PerForm field.
Syntax
Boolean = Object.IsEmpty()
| Parameter | Definition |
| Object | A TEXTAREA name that has the PerForm class applied. |
| Boolean | The value returned from the function call. Boolean data type. |
Mask
A property that sets / returns the format of the data that may be entered. Can be set from code or within a TEXTAREA tag.
Syntax
Object.mask = strMask
| Parameter | Definition |
| Object | A TEXTAREA name that has the PerForm class applied. |
| strMask | A string representing a mask (see below). |
Allowable Masks
| Mask | Definition |
| mm/dd/yyyy | Date |
| mm-dd-yyyy | Date |
| mm/dd/yy | Date |
| mm-dd-yy | Date |
| dd/mm/yyyy | Date |
| dd-mm-yyyy | Date |
| dd/mm/yy | Date |
| dd-mm-yy | Date |
| mm/yyyy | Period |
| mm-yyyy | Period |
| mm/yy | Period |
| mm-yy | Period |
| yyyy | Year |
| yy | Year |
| HH:MM | Time |
| # |
Numeric input only. May be used in any pattern. Example (###) ### - #### Displays (___) ___ - ____. |
| _ | Underscore. Any printable character. May be used in any pattern. |
| ~ | Tilde. Alpha a-z, A-Z and 0-9 only. May be used in any pattern. |
| & | Ampersand. Alpha a-z, A-Z only. May be used in any pattern. |
| ] | Right-bracket. Alpha a-z and A-Z only. May be used in any pattern. Lower case characters are converted to upper case. |
| [ | Left-bracket. Alpha a-z and A-Z only. May be used in any pattern. Upper case characters are converted to lower case. |
| } | Right-curly-bracket. Alpha a-z, A-Z and 0-9 only. May be used in any pattern. Lower case characters are converted to upper case. |
| { | Left-curly-bracket. Alpha a-z, A-Z and 0-9 only. May be used in any pattern. Upper case characters are converted to lower case. |
| n | Numeric only. Positive only unless the Negative sign mask symbol is used. Must be a valid number. |
| , |
Comma. Digit grouping. Valid only when used with the numeric mask char (n). Can only be used after every third numeric mask character. Example n,nnn,nnn |
| . |
Decimal point. Valid only when used with the numeric mask char (n). Example nnn.nn |
| - |
Negative sign. Valid only when used with the numeric mask char (n). Specifies that negative numbers are allowed. Example -nnn.nn |
| ( |
Left parenthesis. Negative Format. Valid only when used with the numeric mask char (n). Specifies that negative values will be displayed as (nnn.nn) instead of –nnn.nn. Example -(nn,nnn.nn |
| $ |
Currency symbol. Valid only when used with the numeric mask char. Example -($nn,nnn.nn |
| @ |
At-sign. Email symbol. Divides the user name from the domain name. Valid with any
character mask symbols. Note that length of each part; user name and extension; are
specified by the mask symbols used before and after the "@" symbol. Example _________________________@_____________________________ |
MaskChars
A property that sets / gets the allowable mask characters in a perform field.
Syntax
Object.MaskChars = strMaskChars
| Parameter | Definition |
| Object | A TEXTAREA name that has the PerForm class applied. |
| strMaskChars | A string of characters representing the mask characters that may be used in a Perform field. The default value for MaskChars is "_#mdyHMn~&{}[]". |
Remarks
There are times when you may want to include a character in a mask that would normally not be allowed. Changing the value of MaskChars, by removing these special character(s), will allow you to use those character(s) as a visible part of your mask.
Example
Lets say you want to have a mask like "###-###-SM-###". Normally this would not be allowed because the M character specifies minutes. Without using MaskChars the mask would display as "___-___-S_-___". Setting MaskChars to "#" disallows all mask characters, except "#", and therefore allows the mask to display as "___-___-SM-___".
MaskText
A read-only property that returns the masked text from a TEXTAREA field.
Syntax
strMaskText = Object.MaskText()
| Parameter | Definition |
| Object | A TEXTAREA name that has the PerForm class applied. |
| strMaskText | The value returned from the function call. String data type. |
Remarks
Using the value property of the TEXTAREA would return the “_” chars that are used to provide visual clues to the user. MaskText converts the “_” chars to spaces in the returned data.
MaxYear
A property that sets / returns the maximum allowable value for a yyyy or yy mask.
Syntax
Object.MaxYear = lngValue
| Parameter | Definition |
| Object | A TEXTAREA name that has the PerForm class applied. |
| lngValue | The maximum allowable value for a yyyy mask. Default is 2099. Long data type. |
MinYear
A property that sets / returns the minimum allowable value for a yyyy or yy mask.
Syntax
Object.MinYear = lngValue
| Parameter | Definition |
| Object | A TEXTAREA name that has the PerForm class applied. |
| lngValue | The minimum allowable value for a yyyy mask. Default is 1900. Long data type. |
NextField
A method that positions the cursor to the first position of the next subfield in a PerForm field.
Syntax
Object.NextField
| Parameter | Definition |
| Object | A TEXTAREA name that has the PerForm class applied. |
Remarks
A subfield is a division of a PerForm field. Normally a division is determined by a non-mask character within a PerForm field.
Pressing [Ctrl]+[Right Arrow] automatically calls the NextField method.
Example
function PF_OnKeyDown()
{
OnIncomplete
An event that fires whenever a PerForm field looses the focus with only a partially filled entry.
Remarks
If no data is entered in the PerForm field the event does not fire.
The OnIncomplete event must be implemented by specifying the handler within the associated TEXTAREA tag. See the section titled Adding The PerForm Class to TEXTAREA Tag(s).
If it is not handled at the element (TEXTAREA) level, the event does not bubble up to the document level.
OnPfKeyDown
An event that fires whenever a user presses a key in a PerForm field.
Remarks
When this event fires the windows.event object returns the following properties.
To cancel this event, set window.event.pfKeyCode = 0 and set window.event.pfReturnValue = false.
Example
OnPfKeyPress
An event that fires whenever a user presses an alpha-numeric key in a PerForm field.
Remarks
When this event fires the windows.event object returns the following properties.
To cancel this event, set window.event.pfKeyCode = 0 and set window.event.pfReturnValue = false.
Example
See OnPfKeyDown for an example.
OnPfKeyUp
An event that fires whenever a user releases a key in a PerForm field.
Remarks
When this event fires the windows.event object returns the following properties.
To cancel this event, set window.event.pfKeyCode = 0 and set window.event.pfReturnValue = false.
Example
OnPfPaste
An event that fires whenever a user selects Edit / Paste from the browser menu.
Remarks
Using this event allows manipulation of windows clipboard data prior to the time that it is actually pasted into a target PerForm field.
Usually, pressing the [Ctrl]+[v] or [Shift]+[Ins] are considered paste events. Using these keyboard keys to trap paste events requires additional code as shown in the below example.
Example
PriorField
A method that positions the cursor to the first position of the prior subfield in a PerForm field.
Syntax
Object.PriorField
| Parameter | Definition |
| Object | A TEXTAREA name that has the PerForm class applied. |
Remarks
A subfield is a division of a PerForm field. Normally a division is determined by a non-mask character within a PerForm field.
Pressing [Ctrl]+[Left Arrow] automatically calls the PriorField method.
Example
function PF_OnKeyDown()
{
Raw
A property that sets / gets if raw data (data with no mask characters included) will be pasted into a PerForm field.
Syntax
Object.Raw = blnValue
| Parameter | Definition |
| Object | A TEXTAREA name that has the PerForm class applied. |
| blnValue | A boolean value equal to True or False. |
Remarks
Default value is false. A paste operation generally requires the source data to contain mask characters that match the target mask character's position one-for-one.
Setting this value to true causes pasted data to be applied to a mask as it it were being typed directly from the keyboard. In other words, setting this value to true causes pasted data to be applied to a mask instead of attempting to match or overwrite a mask.
ResetClass
A method that clears all Perfect Format fields associated with the named class.
Syntax
Object.ResetClass(classname)
| Parameter | Definition |
| Object | A TEXTAREA name that has the PerForm class applied. |
| classname | The name of the class that is implementing the Perfect Format behavior. |
Remarks
Although you are required to reference one of the fields that implements the PerForm class, all textareas that use the specified class are cleared. To clear individual fields use the Clear method.
The HTML Form Reset method will not clear Perfect Format fields. Use the ResetClass method, along with Reset, as shown in the example below.
sub cmdClear_onclick
frmShow.txtFirstName.ResetClass("PerForm")
frmShow.reset
end sub
<form name='frmShow' method='post' action=cgi.asp'>
...
<input type='submit' name='cmdShow' value='Show'>
<input type='reset' name='cmdClear' value='Clear'>
</form>
Examples
The examples provided are stored on our web site so that they may be used immediately. You may copy the examples to your web site and use or modify without restriction.
Perfect Format
(c) Copyright 2002 - 2004, Evans Programming
All Rights Reserved