VBSdb is an open source VBScript object for fast development of
complete database driven web applications, to be invoked within
Active Server Pages.
Overview
There are many components for developing database based web applications.
But these tools require a dll installation on the server side:
once the installation is performed,
a new object can be instantiated, allowing the developer to define some properties
and then call some methods, to display database data and to edit such data.
Such approach has some clear drawbacks. Firs of all, a new software component
(the COM object) is to be installed on the server. This is not always an easy
operation and, more important, most hosting
services don't allow the single developer to install custom software.
Furthermore, such a component is delivered "as is": no source code is available,
and then, customization is impossible.
VBSdb solves these (and other) problems. VBSdb consists of a single folder,
containing a set of pure vbscript code files, which can be run with both ASP 2.0
and ASP 3.0. Nothing has to be installed! Just copy the VBSdb folder in your
site!! Then, in each file where you want to use VBSdb, you need just
a single include statement, and all VBSdb properties and methods are available!!!
We decided to use the VBScript version supported by ASP 2.0. This language is not
object oriented (from this point of view, VBScript for ASP 3.0 is definetely better),
but we succeded in simulating an object oriented framework, by means of extensive
use of the dictionary object datatype (fully supported in ASP 2.0).
As a result, a VBSdb user simply assigns properties (values associated
to a VBSdb dictionary object) and then calls a method of the VBSdb object (a VBScript
procedure, passing the dictionary object as a parameter).
So, VBSdb can be used both with Microsoft Internet Information Server 4.0 and with IIS 5.0.
Even if many hosting service have not yet updated their servers to IIS 5.0, we are giving
virtually all ASP developers the chance to use an object oriented tool, for fast
database based web development.
Furthermore, VBSdb's code is open source.
We believe our software is higly customizable, and it will be more in the near
future, but users can freely modify the code to fit their needs. Consider that
you can make a full copy of the VBSdb directory, customize the copy's VBScript
and then, in some pages use the customized copy, while in the other pages, keep
using the official VBSdb version.
Screen Modes
Accessing to a VBSdb web page, the user can navigate among many different screens.
We can divide such screens in two main categories: view screens and
input screens.
View screens display recordset data. The developer choses if such data are to be shown in a grid
or they must be accessed one single record in each screen, in a (read only) form like layout.
Furthermore, mixed view screens are supported.
When each record structure contains many fields, it would
be impractical to show all fields in each grid row. In such cases, the best solution may be to
dispaly a subset of key fields in grid mode, giving the user the chance to click on a row, and see
the corresponding record in a detailed form view, thus allowing the user to access, in a single screen,
both to a record set grid and to a single record detail.
Input screens wait for input from the user. They can be further categorized, distinguishing them in
a single search screen and three different edit screens: the add screen, the update screen and the
delete screen.
This chart shows the screen type hierarchy. Note that View Screens can be further subdivided in Grid screens,
Form Screens and Mixed View Screens (showing both the grid and the form objects).
In order to help the developer to find the proper
property to get a wanted effect, property names have been properly prefixed. If
a property name begins with Grid, then the property value affects the behaviour
of the grid in the view screen. The following table summarizes, for each
property group, the scope of the properties belonging to the group.
Properties beginning with:
Influence:
Grid
Grid in view screen mode
Form
Form in view screen mode
View
View screen mode, neither just to the grid, nor just to the form
Search
Search screen mode
Edit
Both Add screen and Update screen and Delete screen
Input
Both the Search screen and the Add screen and the Update screen and
the Delete screen
Global
Every screen
Note: MdbPath and Sql properties have not been prefixed, in order to distinguish them from
the others, as they are the only two required properties (Dsn may be used instead of MdbPath).
Installation.
To install VBSdb, you just have to unzip a zip file and to copy a folder in your
web application. That's all.
You should have downloaded a VBSdb zip file. Its name should look
something like VBSdb-mainVersionNumber-subVersionNumber.zip
It contains three files and and two folders. The three files are test.asp, test.mdb and documentation.htm.
test.asp and test.mdb will be used to check your installation is correct, documentation.htm is the file
you are reading now, if you are off line.
The first folder, named documentation, contains all the layout files and images needed
to build the documentation you are reading now. Do not consider it at all.
The second folder called VBSdb, contains a number
of asp files:
it is the VBSdb module, implementing VBSdb properties and methods. This is the folder
you will have to copy in your web application.
You have to unzip the VBSdb zip file on your PC. We suggest to chose an empty folder. If
not available, you should create it. Let's assume your empty folder complete path is
c:\unzipVBSdb\
Extract all the files in c:\unzipVBSdb\ (or chose the empty folder you have previously
decided). Now, two new folders should have been created, c:\unzipVBSdb\VBSdb\ and
c:\unzipVBSdb\documentation\. Furthermore, you have the files c:\unzipVBSdb\test.asp,
c:\unzipVBSdb\test.mdb and c:\unzipVBSdb\documentation.htm.
Copy The Folder
Now, you have to copy the c:\unzipVBSdb\VBSdb\ folder in the site where you want
to use VBSdb. Let's assume you have defined a TestVBSdb site, whose home directory
is c:\inetpub\testVBSdb\
Copy the c:\unzipVBSdb\VBSdb\ folder under c:\inetpub\testVBSdb\. You now have
a new c:\inetpub\testVBSdb\VBSdb\ folder and the installation can be considered
completed.
Test your installation
Copy c:\unzipVBSdb\test.asp and c:\unzipVBSdb\test.mdb in the c:\inetpub\testVBSdb\ folder.
Now, connect to your testVBSdb site and open in your browser the test.asp file
(depending on your system, and your site configuration, your browser address may vary:
an address example may be http://testVBSdb/test.asp; an other example may
be http://localhost/testVBSdb/test.asp or http://127.0.0.1/test.asp).
If the browser shows a page allowing the user to browse data, installation
is correct.
Methods
In this section, VBSdb methods are described. For each method a short
description is presented. Then syntax is
defined and usage examples are provided. An extensive description
follows and, finally, a complete working program illustrates how to use
the method. If not otherwise stated, such programs connect to the
Microsoft sample nwind.mdb database (the names of companies, products, people,
characters, and/or data mentioned herein are fictious and are in no way
intended to represent any real individual, company, product, or event).
On the contrary, syntax examples, are not related to any real database.
Method List
VbsDbNew
Creates a new VBSdb object.
Syntax
VbsDbNew variable name
Examples:
VbsDbNew objVbsDb
VbsDbNew VBSdbObject
Description
Use VbsDbNew to create a new VBSdb object. This procedure call acts as an
object constructor: it returns a VBSdb object with assigned default values.
A live example of this property can be found here.
VbsDb
Execute the VBSdb object.
Syntax
VbsDb variable name
Examples:
VbsDb objVbsDb
VbsDb VBSdbObject
Description
Use VbsDb to perform each action associated to the VBSdb object. This procedure call acts as an
object method applied to the object that is passed as a parameter. The type of actions
actually performed, depends on the last user command. If it is the first time
the method is called, then the view screen is displayed. If we are coming back to the
page after a VBSdb command has been executed, then the action performed depends upon the
last command given by the site user:
assume current screen is in view mode
if a grid index was pressed, then the next screen is still the view screen, and the
selected record will be displayed in the form (database is left unchanged)
if a navigation button is pressed, then the the next screen is still the view screen,
and the
displayed screen mode will be the selected one. If first, prev,
next or last is selected, then the selected page of grid data is
displayed (database is left unchanged)
if a grid update button is pressed, then the next screen will be an update screen
and the record to be update will be that associated to the update button that was
clicked (database is left unchanged)
if a grid update button is pressed, then the next screen will be an update screen
and the record to be updated will be that associated to the update button that was
clicked (database is left unchanged)
if a grid delete button is pressed, then the next screen will be an delete screen
and the record to be deleted will be that associated to the delete button that was
clicked (database is left unchanged)
assume current screen is in input mode
if the screen is of search type and the form is submitted, then
the next screen will be in view mode (database is left unchanged)
if the screen is of update type and the form is submitted, then the database
record is updated and the next screen will be in view mode
if the screen is of delete type and the form is submitted, then the database
record is deleted and the next screen will be in view mode
if the screen is of add type and the form is submitted, then the new database
record is added and the next screen will be in view mode
whenever a cancel button is pressed, the next screen will be in view mode
(database is left unchanged)
A live example of this property can be found here.
VbsDbClose
Releases a VBSdb object.
Syntax
VbsDbClose variable name
Examples:
VbsDbClose objVbsDb
VbsDbClose VBSdbObject
Description
Use VbsDbClose to destroy a VBSdb object and to collect garbage data. In following examples,
VbsDbClose call is omitted for clarity, but its use is strongly recommended, since it
gives the server more available memory space.
Use VbsDbGetOutputFieldValue to get a fiel value for the selected grid record.
It must be used after the VbsDb method is called and before the VbsDbClose
method is called.
It is extremely useful to build table/subtable scenarios.
A live example of this property can be found here.
VbsDbGetDateFormat
Returns the current recognized date format.
Syntax
variable name = VbsDbGetDateFormat( VBSdb object ) (returns a string value)
Example:
strFirstName = VbsDbGetDateFormat( objVbsDb )
Description
VbsDbGetDateFormat returns a string, containing a description of the correct date format
according to the current session.lcid value. You can use this method to display it to your site
user, giving an hint about how to insert date field values. Of course, you can decide
the accepted format, by properly setting the session.lcid value.
Use VbsDbGetLastAction to know which was the last action asked by the
site visitor.
Possible return values are:
NonVbsDb: the last visitor action was not related to the VBSdb object
GoToGridRow: the visitor asked to go to a specific Grid row
GoToFirstGridPage: the visitor asked to go to the first page in the Grid
GoToLastGridPage: the visitor asked to go to the last page in the Grid
GoToPrevGridPage: the visitor asked to go to the previous page in the Grid
GoToNextGridPage: the visitor asked to go to the next page in the Grid
GoToSearch: the visitor asked to go to the Search screen
RemoveFilter: the visitor asked to clear the applied filter
GoToAdd: the visitor asked to go to the Add screen
GoToUpdate: the visitor asked to go to the Update screen
GoToDelete: the visitor asked to go to the Delete screen
Cancel: the visitor asked to cancel the input task
SubmitSearch: the visitor submitted a new filter condition
SubmitAdd: the visitor submitted a new record to be inserted
SubmitUpdate: the visitor submitted new values to update the current record with
SubmitDelete: the visitor confirmed to delete the current record
Use this method, for example, to perform some task when a new record is added.
VbsDbGetLastAction can be invoked after having called the VbsDbNew method.
If you assign a custom value to the GlobalId property,
VbsDbGetLastAction must be called after the GlobalId assignment.
A live example of this property can be found here.
Properties
In this section, VBSdb properties are described. For each property a short
description is presented. Then syntax is
defined and assignment examples are provided. An extensive description
follows and, finally, a complete working program illustrates how to use
the property. If not otherwise stated, such programs connect to the
Microsoft sample nwind.mdb database (the names of companies, products, people,
characters, and/or data mentioned herein are fictious and are in no way
intended to represent any real individual, company, product, or event).
On the contrary, syntax examples, are not related to any real database.
You have to assign the virtual path, from the asp page where you are using VBSdb, to
the mdb database. Both absolute and relative path can be used. VBSdb translates
your virtual path to the physical path of your database.
If you use two or more VBSdb objects in a page, you have to assign an identifier to
each object. It allows VBSdb modules to discriminate among different input
requests and different session variables.
This property is used to handle ado related
database peculiarities.
For example, it determines date constant formats ('#' delimiter is used for Access,
while '{' and '}' is used for Fox Pro).
If you want the user to begin filtering the data do be shown,
then you can set GlobalStartScreen to 'search'.
In many application it is typical to provide the user with an 'Add New' menu item:
if the user wants to add a new record, it is better to directly display
an add new record form. To get such result, you have simply to set GlobalStartScreen
to 'add'. When you set GlobalStartScreen to 'add', often you will also
set EditAddScreenRepeat to true, in order to let the user keep on adding
new records.
Use this property if you want the user to see more readable field headers. It can
be useful, for example, to add blanks in field Headers.
If a field name contains spaces, write it without brackets.
If you want an Header to be completely blank, use a single blank space as the header value.
This property allows the developer to customize various VBSdb images. In the VBSdb distribution,
the folder VBSdb/images/ contains default images, you can freely use on your sites.
If you want to change VBSdb layout for your needs, build a new folder, where you change images,
while keeping image names.
You have to assign the virtual path, from the asp page where you are using VBSdb, to
the folder where images are contained. Both absolute and relative path can be used.
This property is used implement internationalization. It allows to set
the standard language 'spoken' by the current VBSdb object. Then, each standard
text string can be further customized by means of the GlobalCustomText property.
Note that, thanks of VBSdb object orientness, two or more objects can be displayed
on the same page, each with its own language.
Up to date, the supported languages are English, French, German, Italian, Portuguese and Spanish. Adding a
new language is trivial: take a look at the VBSdb/languages/ subfolder.
We are committed to add many more languages in the next future.
objVBSdb("GlobalCustomText") = "searchScreenTitle|Search for products;searchScreenTitle|Add a new Product"
objVBSdb("GlobalCustomText") = "updateFormRightHeader|Current Employee"
Description
Use this property if you want to customize the standard text VBSdb displays to the user.
The default text is determined by the GlobalLanguage property (English is
the default language).
For example, assume you want to show english messages and you want to customize
the Delete Screen title to "Delete current Product" (default title would be
a more general "Delete current record"). Take a look at VBSdb/languages/ subfolder:
the file inc_english.asp is present. Open inc_english.asp and search for
"Delete current record". You can see that the corresponding dictionary item name is
english_deleteScreenTitle. Well, deleteScreenTitle is the text item name
and it is invariant in all languages. The english_ prefix determines the
language for which the text is specified. So,
what you have to do is simply to instruct VBSdb that you want to change the
text value for deleteScreenTitle and you can do it by including the definition
"deleteScreenTitle|Delete current Product" in the GlobalCustomText assignment.
When GlobalReset is set to true (false is the default), VBSdb behaves as if
the site visitor has just arrived to the current page from an external page.
Thus, the VBSdb session variables are reset. Please, note that VBSdb uses
just three light session variables, to remember the following pieces of information:
the absolute position of the displayed Form, with respect to the Grid
the order by clause (if) set by the site visitor by clicking on
a Grid column header
the filter where clause, if a filtering condition is set
The GlobalReset property is useful when the developer wants to force VBSdb to be reset, even if
the containing page calls itself (in this case, by default, VBSdb would assume it has
to keep its state unchanged).
Code example
<!--#include file="VBSdb/inc.asp"-->
<%
VbsDbNew objVbsDb
objVbsDb( "MdbPath" ) = "data/nwind.mdb"
objVbsDb( "Sql" ) = "select ProductName,QuantityPerUnit,UnitPrice from Products"
if Request.QueryString( "search" ) = "yes" then objVbsDb( "GlobalReset" ) = true
objVbsDb( "GlobalStartScreen" ) = "search"
end if
VbsDb objVbsDb
%>
On Line Example
A live example of this property can be found here.
GlobalCSS
Path to the style sheet .css file.
Syntax
objVBSdb("GlobalCSS") = "virtual path to the .css file" (default is the empty string)
This property allows the developer to customize the VBSdb object layouts. By default, GlobalCSS
is the empty string. In this case:
a STYLE element is output within the generated html code
some standard style features can be overridden by setting color properties like, for
example, the GlobalTableBGColor property
On the contrary, if the GlobalCSS property is set to a CSS style sheet file, then
no STYLE element is output within the generated html code
a link element to the external CSS file is output within the generated html code
color properties like, for example, the GlobalTableBGColor property, have no
effect on the VBSdb layout. Customize the CSS file to change VBSdb object layouts
VBSdb is distributed along with the standard style sheet file VbsDb.css (you can find it
in the VBSdb folder).
The best way to build a custom layout is to make a personal copy of the VbsDb.css file and
to change some property assignments. Comments are provided within the VbsDb.css file,
in order to suggest the developer how to achieve a particular result.
For the sake of simplicity, the style sheet elements (classes and unique IDs) have been
clearly divided into four sections:
Default separators for properties are the semicolon ';' and the pipe '|'.
Sometimes, such separators limit the developer: for instance if you want to
insert some javascript within your ViewFieldFormats cell formatting,
you have to use semicolons within the ViewFieldFormats values.
If you had to use the default separators, VBSdb would not be able to
understand which semicolons are to be considered a separator and which ones
are to be considered javascript semicolons. Using the GlobalSeparators
property you will instruct VBSdb that, for the ViewFieldFormats property,
a new character has to be considered a separator, instead of the semicolon.
This way, you will be able to get semicolons in the resulting formatted cell.
This property is used to build the DSN-Less connection to the Microsoft Access databases.
JET.4.0 is the best choice for Microsoft Access 2000, while JET.3.51 is the best choice
for Microsoft Access 97. You can also decide to use an Ole Db over ODBC provider.
If you assign the "Automatic" value, VBSdb automatically tries to find the
best Ole Db provider available on the system.
Attention: using the Jet provider
you can (and have to) disambiguate field names using the "tableName.fieldName"
notation. Of course, you have to do it only
when an ambiguity arises (that is,
when a join involves different tables containing fields with the same name) and
you have to do it only for those properties that refer to the Sql fields,
not for those properties that refer to the edit table (that are those properties
whose name begins with Edit).
This property is used to instruct the Browser where to point when the
site visitor clicks on a VBSdb button or link and the page is reloaded.
By default, the browser will point to the top of the next reloaded page.
If you assign "VBSdb" to the GlobalPagePositioning porperty, then the
browser will point to the html zone created by VBSdb.
You may wish to set this property value when you have a VBSdb object
that displays beyond the bottom of your page (it often happens for subtable's
VBSdb objects). In such a case, having the browser to point back to the VBSdb object
itself, will probably offer a better experience to the site visitor.
Use this property to decide what to display and how to display it, in view screen mode.
If you set this property to "grid", then only the grid is shown. "form" displays only the
form. "grid-form" (the default) displays the grid on the left and the current record
form on the left. Finally, "grid|form" displays the grid at the top and the detailed
form at the bottom.
This property determines which navigation buttons are to be displayed.
Use semicolon as separator (this is the standard syntax, but you can
use also colons and pipes: VBSdb will translate them into semicolons).
This property determines where the navigation bar(s) will be displayed.
If "top" is assigned, then the bar will be centered over the grid and the
form. If "bottom" is assigned, then the bar will be under such two objects.
If "both" is the property value, then two identical navigation bar will
be displayed: one at the top and one at the bottom. This is particularly
useful when GridPageSize is set to an high value, such that the browser
have to be heavely scrolled to get to the bottom of the Grid.
Finally, "none" means that no navigation bar has to be shown. This option
can be used, coupled with ViewFieldFormats, to easily build an update grid,
allowing the site user to change many recordset rows in a single screen.
Use this property to change navigation buttons background,
when GlobalImageDir is not set and buttons are displayed
as simple text. Default is #d3d3d3.
Use this property to change disabled navigation buttons foreground,
when GlobalImageDir is not set and buttons are displayed
as simple text (disabled link). Default is #9C9A9C.
This property determines if paging informations will be displayed.
If set, the site visitor will be provided with the following (customizable)
pieces of information:
