==========
ScriptData
==========

May 2012

A demonstration of the Microsoft Script Control used in Visual
Basic 6.0.

This demo allows you to create, edit, save, and load a script
written in VBScript that defines a record's layout and field
validation for data entry.  In Data Entry ("Run") mode the
defined fields are used to create a scrolling data entry user
interface that applies the validation during entry.

-----------
Just a Demo
-----------

Data is simply saved as a CSV format text file where the field
delimiter is always comma and the decimal point is always
period.  String values are written out with quotes (") to
permit the use of commas within them.  No attempt is made to
deal with quotes within String values however.

This is just meant as a scripting demo.  For real use you'd do
more elaborate things like letting the user "scroll through"
and edit existing records, etc.  You might replace the CSV
file by a Jet MDB, or an XML file, or something else.

As it is the output data file name is just a single hard-coded
value.


-------------------
Purpose of the Demo
-------------------

The intent here is to show how the Script Control can be useful
in allowing users to apply scripting to extend a hard-coded
application.  One aspect of these scripts is fairly simplistic:
defining some data entry fields and associated validation
criteria.

However I wanted to show more exciting things you can do too.
like: define Classes and instances of them in your script that
CAN BE USED BY THE VB6 HOST APPLICATION!


--------------------
Building the Project
--------------------

There are no special build instructions for ScriptData.

You can just open the .VBP file in VB6 and Make to compile
or just try it by running it within the IDE.


--------------------------------
Down to Basics: The Object Model
--------------------------------

ScriptData exposes an object called Fields and its members to
your VBScript.  It also exposes instances of the Field Class
either through the Add() method and the Item() property.


*FIELDS OBJECT*

CaptionWidth property

    Here you set the width in Twips for the data entry field
    labels.  Since the field Labels and Textboxes are
    presented in one column only a single width is needed.

Count property

    Number of Field objects in the Fields collection.

Item(KeyOrIndex) property

    This retrieves a reference to an individual Field object
    by key (Name) or by index (1-based number).

Title property

    This is the title displayed in the user interface during
    data entry mode.

Add(Name, VarType, Caption, TextWidth, [MaxLength],
    [DefaultValue]) method

    This method adds a new Field to the collection and returns
    a reference to the new Field object.

LikePattern(Text, Pattern) method

    Provides VB's Like operation to a custom validation Class.
    Returns True on pattern match.

Each Field object added has a number of properties.  Some of
them are optional and have default values.


*FIELD OBJECT*

Name property

    String valued unique field ID value.  This is used as the
    collection key and is written to the CSV data file's
    header row.

VarType property

    Type of the data in this Field.  Values are those of the
    VbVarType enum (which are also defined in VBScript).  All
    simple non-array and non-object types are supported.

Caption property

    String valued Label caption used in the data entry user
    interface.

TextWidth property

    Single value in Twips.  Width of the Field's Textbox in
    the data entry user interface.

DefaultValue property (default = "")

    String value placed in the Field's Textbox whenever a
    clear operation is done (a save also clears the fields in
    the user interface.

TrimBlanks property (default = True)

    Boolean value, if True a Trim$() is done on the Textbox
    as part of the validation process.

MinLength property (default = 1)

    Integer value, minimum number of characters that must be
    entered to pass validation.  If zero this check is
    skipped.

MaxLength property (default = 0)

    Integer value, maximum number of characters.  If zero
    this check is skipped.

MinValue property (default = Empty)

    Variant value, minimum value to pass validation.  Usually
    for numeric types but can be successfully used for String
    fields as well.  If Empty this check is skipped.

MaxValue property (default = Empty)

    Variant value, maximum to pass validation.  If Empty this
    check is skipped.

Format property (default = "")

    String value.  If not "" the last step in validation is
    to reformat the Textbox input (converted to its type) by
    calling Format$() using this Format string value.

    This might be handy for things like SSNs, phone numbers,
    dates and times, etc.

CustomValidate property

    Object reference value.  To be set to an instance of a
    VBScript Class that has a Validate() method with the
    correct method signature (see below).

Text property

    This may be used within a custom validation Class in
    order to get and change the Textbox contents of other
    fields via Item(x).Text where x is an index or key.  It
    may be useful in inter-field validation or even in some
    special cases (e.g. Zip Code validation that returns
    City and State values).


-----------------
Custom Validation
-----------------

This is accomplished by setting the .CustomValidation property
of a Field to an instance of a VBScript Class that has a
method:

    Public Function Validate(ByVal Index, ByRef Text)

The code in this method can use the Index value to get at the
Item() or Field object.  It can also just examine the Text
parameter and even modify it!

Text is the contents of the Textbox for this Field after any
TrimBlanks has been done and after any MinLength and
MaxLength checks have been done.

If your validation logic determines that the value is valid,
the return value should be either Empty (not set) or an empty
String ("") value.  Otherwise it should be set to a validation
error message for the user.

Min/Max value checks are done after custom valdiation if
defined.


---------------
Editing Scripts
---------------

There is a rough "template" that can be loaded as your script
via the File|Import Template script menu selection.  You can
use this as a guide to write a custom script.

Editing is via a simple multiline Textbox.

Scripts generally use the extension .vbs since they are
VBScript.  You can use the File menu to Save and Load edited
scripts.

In addition to the rough template there is a simple sample.vbs
file included that you can Load and try.

There is also a fancier version sample-fancy.vbs that makes a
REST Web Service call to validate the Zip Code and
 fill in the
City and State when they're returned!

You can also edit scripts in Notepad, etc.


----------
Data Entry
----------

You can use:

    Mode|Data Entry (Run)

or press F5 to enter the data entry mode.

This loads the script, building the Fields collection and
validation objects and if successful "hides" the editing
Textbox and "paints" and shows the data entry user
interface.

If the script fails to load (syntax error) a message about
the problem is shown in the status bar.  If errors occur
at runtime these are also shown in the status bar.

During data entry you'll have a list of Field Labels and
Textboxes, and a Clear and Save button.  You can enter
data and Tab/Shift-Tab between fields, use Ctrl-Home and
Ctrl-End or PgUp and PgDown, or use the scrollbar which
appears if there are too many fields to show in the Form.

Clicking Save stores the current row to disk, clears the
Textboxes, and moves focus to the first Textbox.  Clicking
Clear clears the Textboxes, etc.

You can exit data entry via:

    Mode|Edit script

or press F6 to leave data entry and return to edit mode.
