article

Tutorial on how to get started with the first opensource ASP Library called GabLib

Email
Submitted on: 1/7/2015 12:24:00 AM
By: Michal Gabrukiewicz (from psc cd)  
Level: Advanced
User Rating: By 6 Users
Compatibility: ASP (Active Server Pages), HTML, VbScript (browser/client side)
Views: 1788
 
     I have programmed my own ASP Class Library and this tutorial demonstrates how to get started using the library. It is a large opensource library for ASP. The basic-classes lets you to create debug, createdropdowns, etc. The tutorial is taken from my website http://gablib.grafix.at

This article has accompanying files

 
				
Lets get started - Beginners tutorial GabLib
This tutorial is taken from my website and a little bit rewrite so it fit here to PSC. It is just the basis for the GabLib. You will know how to use it. The whole updates and all classes can be found at http://gablib.grafix.at - site is complete in english. there are documentations, tutorials, etc.

For sure everyone wants to know how to use the GabLib now for his/her own projects. Hmm, it's not so difficult as it might look like. If you have enough practice in Web-development and know how to programm in object-oriented way (dont worry asp is not 100% OOP and so it is not necessary to know everything about it) then it should be no problem to use the library. Maybe even without continue reading ;)

The library was created to give developers a possibility to easy create large web-application with common used controls, methods, etc. The most important point is that the library enables you to write easy-to-read and re-useable code for easy maintenance. In addition not everyone should invent the wheel again and so the library should be a good basis for every project. It should solve all the common problems. The following tutorial should let you easily start working with GabLibrary. This tutorial is a basis for the use of all other classes which are part of GabLib. There are a lot of classes which need the Basic-classes to work correctly. Reading this tutorial you will know how to build the basis for all those classes.

A quick note: I am not a writer and nor i am an english native so it could (or will, or already happen) happen that there will be some (more) spelling mistakes, grammer mistakes, etc. Sorry for that. I hope some of you will understand (at least the code).

1. What should you know after this tutorial?
  • Introduction to the GabLib. How to work with it? Pros, Problems, etc.
  • We create a basis for every site of your web-project. Just imagine: You create a new site and everything is ready to use. You have a database-connection if you need one, connection closed automatically, you decide wheather the visitor should be logged in or not to view the page, global header and footer if you want, loading all the global functions and constants, etc. etc.
  • We create a possibility to debug our pages like in ASP.Net. We do it with a Debugging-console which can be turned on and off.
  • You will see some examples how to use classes of the basic-package.
  • and a lot more.
2. Download the basic-package
 Download Basic-package (included in zipfile)
Extract the ZIP-file and keep the file/folder structure. Copy the whole gab_Library - folder including the contents into the root of a virtual directory on your ISS (Internet Information Server). If you dont have direct access to the server you should copy the directory to the root-folder. It should be fine. Your file-structure should look like the following:
/gab_Library/
class_constants/
class_CreateDropdown/
class_debuggingConsole/
class_errorHandler/
class_lib/
images/
class_customLib/
class_customMailSend
class_page/
class_string/
Now the Basic-package of GabLib is ready for use. I recommend you not to change the files, etc. so you can easily update all the files if there will be new updates. And now we need to do some custom-settings before we start with our first page.
3. Implementation of custom-methods -  CustomLib-Class
 CustomLib-Class is one of the most important classes for custom modifications. All your own global functions (methods) should go in there. This class will differ from project to project because every project has its own global methods (global methods for every project are in the  Lib-Class). You also need to implement all necessary methods in this class before starting with your project. All the methods below should be implemented to ensure smooth operation. Every method is like an interface and you should NEVER call it directly! These "interfaces" are used by other methods of other classes. You should only call your own custom methods from  CustomLib-Class. Nothing else! Now I want to decribe which methods ("interfaces") must be/or should be present in the  CustomLib-Class:
  1. sub establishDatabaseConnection(parameter) - This method should establish a database connection using an object called cnn. The functionality should be implemented by everyone himself. Why? Its easy! Just imagine you start a new project and want to use the GabLib. Do you think we know what database you are using? Access, Oracle, etc. No. And thats why everyone can implement his/her own connection which is needed for the project. Here is an example how an implementation for access-database could look like:
    cnn.Provider = "Microsoft.Jet.OLEDB.4.0"
    'FILENAME.MDB should be replaced by the filename of your database. cnn.ConnectionString = "Data Source=" & Server.MapPath ("FILENAME.MDB")
    cnn.open
    Ready. Our database-connection is ready and can be used later without any problems. You dont need to waste your time with opening, closing or even handling the errors. GabLib is doing these jobs! I am sure some of you want to know what the parameter is for. It is for free use. Just if you need a parameter for database-connection. e.g: if you want to connect to different connections-string within one project. The method establishDatabaseConnection(Parameter) is called by the  Page-Class.  Page-Class has a method called makeDbConnection(Parameter) which calls the establishDatabaseConnection(Parameter) method. You will only need it to establish database-connection manually.


  2. function userLoggedIn() - This function should tell us if a user is logged in or not. How you want to implement this depends on you and your project. Example: In most cases we check a session-var for a certain value. If the session-var has this value we return True (User is logged in) or if the session-var has a different value or even does not exist we return False (user not logged in). This method should also NEVER be called directly. It is something like an "interface" which is used by  Page-Class.


  3. logError(errorDuring, errorDesc, errorSource, debuggingVar, requestedUrl, referrer, sessionVars) - This method is also an "interface" and never used directly. Implement the error-logging in this method. e.g. log the error to a database a file, etc. If the error was logged successfully you should return True and if the error-log failed you should return False. This method is exclusively used by  ErrorHandler-Class. You will find a detailed information in the documentation of the class  ErrorHandler-Class.


  4. accessDuringMaintenance() - This "interface" should return True (user has access during maintenance) or False (user has no access during maintenance). You can implement an IP-check for example. If maintenance is turned on only persons with a special IP will have access to the site. Detailed information can be read in the  Page-Class. IP-Check is implemented by default.
Okay now the  CustomLib-Class should be customized enough. Again i want to inform you to never call these "interfaces" directly from  CustomLib-Class. Only call your "custom" methods. The  CustomLib-Class offers you place for your own custom-methods. This methods should be called directly for sure! The following lines shows you how to call your custom-methods within every page (page must be created with  Page-Class):
'Custom-Method call
lib.custom.myMethod("OneParameter")
'Library-Method call. (global methods)
lib.getRecordset("UPDATE users SET vorname = 'John'")
4. Custom Email-class -  CustomSendMail-Class
This class is quasi an interface between your email-component (like Jmail, ASPMail, etc.) and the GabLibrary. This step has some advantages: 1) should you change your email-component (sometimes it happen) then we only rewrite the interface and not 1000 differnt sites where we use email-sending. 2) It is real easy to implement more functionality to your Email-class on-the-fly.

It is not necessary to implement this class immediately but you should do it soon if you want to use email-functionality in your project(s). You also should implement it if you want to use automatic "email notification on errors". If you use JMail as your component then its an easy job. JMail is implemented as example in  CustomSendMail-Class to demonstrate which methods and properties should be available within the class. It is a basic structure. Here we go with a short example on how to send an email using our new class (interface):

'No include necessary. The class is loaded automatically.
set myMail = new customSendMail
with myMail
.subject = "My first mail"
.fromEmail = "jonh@connor.com"
.fromName = "John Connor"
.body = "Hand on buddy!"
.addRecipient("TO", "arnold@schwarzenegg.er", "Arnie")
.send(stmp.mail.com)
end with
5. Custom-pages implementation - nologin.asp, maintanance.asp, frameSetter.asp
These files are located in the folder of  CustomLib-Class and should be implemented with your own functionality and design. Just some sentences:
  1. nologin.asp - This page will be automatically displayed if a page need a logged-in-user but the visitor isnt. You can enable this functionality with the property loginRequired = true of  Page-Class. The noLogin.asp file should be a site with a form including login and passwort fields and also a login-procedure which handles the login of the user (sets a session-var, etc.). You could also implement a redirect to the requested page. You will get the requested page with the following line of code:
    angeforderteSeite = request.serverVariables("SCRIPT_NAME")
  2. maintanance.asp - This page will be displayed if maintenance-work is on. Pre-requisite is that the site has been built with  Page-Class. You can turn on maintenance-work setting the MAINTENANCE_WORK readonly property of  Constants-Class to true.


  3. frameSetter.asp - In this file you should implement a short javascript routine which checks if a special frame is present. If not then load frames afterwards. Implementation should be done by everyone himself. Implementation only needed if you want to use framesetter property of  Page-Class. This property enables loading of the whole frameset. If the requested page will be be called directly without framset then frames will be loaded.
6. Configure global constants -  Constants-Class
This class is loaded automatically within the  Page-Class and is available in every page. Because of this an object called consts is available in every page. Till now we can get every global-var (project-constant) using the following code consts.myConstantName. Constants are readonly. If you need further information please read the  Constants-Class documentation. I want to do a short introduction to every constant. Just change the values in the constructor:
  1. consts.webadmin - This two-dimensional array stores the webmaster(s) of the project. Is used for example in  ErrorHandler-Class for error-reporting.


  2. consts.allowed_on_maintenance - This array stores the IP's of the persons who has still access to the pages during maintenance. Just drop in your own ip and thats it.


  3. consts.company_name - Company-name, Project-name, etc.


  4. consts.domain - The domainname. e.g. http://www.myDomain.com/


  5. consts.hostIP - IP of the host. z.b. 192.168.0.1


  6. consts.smtp_server - Smtp-server for email-sending.


  7. consts.logo - Stores the path to the site-logo e.g. /images/logo.gif


  8. consts.logoSmall - Stores the path to the small site-logo e.g. /images/logosmall.gif


  9. consts.bgColor - Default background-color for all pages. e.g. #FFFFFF


  10. consts.page_stylesheet - Path to the stylesheet-file e.g.. /style.css


  11. consts.tablerowcolor1, consts.tablerowcolor2 - These constants need a css-class name. These should be 2 different colors because these css-classes will be used by showMouseover() - method which helps you to display every line in an alternating color. e.g. white and gray. For best result the css-classes should only implement background-color. These and the next constants are mainly used by showMouseover() of  Lib-Class. The detailed functionality of the method can be found in the documentation of  Lib-Class.


  12. consts.tablemouseover - Css-class-name for a css-class which formats a mouseover-effect of showMouseover() - method.


  13. consts.automated_bot_email, consts.automated_bot_name - Name and email which should be used as send in all automated emails.


  14. consts.email_send_on_error - If you want to enable sending emails on error (true) else put a false.


  15. consts.maintenance_work - true/false. Turn on/off maintenance-work with this constant.
'Display the value of a constant-var:
'In this example we use domain-variable.

response.write consts.domain
7. Now we start and create our first page
Everyone who managed the tutorial till now has managed the biggest part of it and now lets work with this basis of GabLib. First we create our first page with the help of GabLib. We need the default-page-template:
 Default-Page-Template (included in the zipfile)

Lets take a look at the template and explain some points:

<!--#include virtual="/gab_Library/class_page/generatepage.asp"-->
<%
set page = new generatePage
with page
.DBConnection = false
.title = "My Page"
.contentSub = "main"
.debugMode = false
.loginRequired = false
.draw()
end with
set page = nothing

'********************************************************************
'* main - we start . DONT FORGET TO KILL ALL OBJECTS!!
'********************************************************************
sub main()

end sub
%>
You see that first we need to include the  Page-Class. Now it is possible to create a new object called page using set page = new generatePage. Then just set some properties and draw the page using draw() - method. In this case the page-content should be implemented to the main() - procedure. The contentSub - property set the name of the procedure which will be called on pageload.
8. Some short examples of use
Now its beginning to be real funny. We have our own page created with  Page-Class and so we can use all the other classes. Lets give it a try and lets write a constant-var to the screen. Write the following into the main() - procedure:
response.write consts.hostIP
The IP of your Host should appear in the browser. If not you should check back to the top ;) Till now we also can call all the methods of  Lib-Class without creating an instance of the class. Try the following code (again put the cut into the main() - procedure):
<TABLE width="100%">
'alternating mouseover-effect
<% for i = 0 to 9 %>
<TR<%= lib.showMouseover(i,true) %>>
<TD>Mouse is no cat</TD>
</TR>
<% next %>
</TABLE>
This example should create a table with 10 rows. Every second row should be coloured different. Then you also should recognize a mouseover-effect if you move your mouse over a row. Okay and now lets try another example. Lets try out our new  DebuggingConsole-Class to get as much debug-information as we can. First we need to turn on debugging-mode. We do this within the  Page-Class:
'we use the page-object that we created before
page.debugMode = true
Now a debugging-console should appear at the bottom of the page. By clicking on a headline you can open or close the part of the console. Parts without content cannot be opened. I am sure you often debug your variables with response.write varName to get the value of the variable. This step is history. Now we add every variable we want to appear in the debugging-console to the debugVar-Collection of the  Page-Class. If debugging-mode is turned on we will immediately see all values of all variables. If we turn debugging-mode off the variables are gone. Isnt that great? Now I'll show you how to add a variable to the debugVar-Collection:
'First we create a variable called X
'I have choosen a constant of constants-class as value
'to demonstrate again how to get global constant-values.
'Now we add the variable to the debugVar-Collection of page-class.
'We do this using the addDebugVar - method.
'First parameter is description of the variable and second is the var itself.

x = consts.company_name
page.addDebugVar("My variable X", x)

'We turn on the debug-Mode and our variable
'appears in the debugging-console.

page.debugMode = true
And? Did it work? I hope so. If not then dont hasitate to ask in our forum for help. You will get help fast. I want to demonstrate a further example. An example on how to use the lib.getRecordset - method. With the help of this method it is much easier to get recordsets of the database. Following example:
'first we activate database-connection.
'pre-requisite is that the establishDatabaseConnection-Method
'has been implemented in the customLib-class.

page.DBConnection = true

'SQL-Query should be written by everyone himself,
'so the tables, etc. are available ;)

sql = "SELECT name FROM users"
set rs = lib.getRecordset(sql)
response.write rs("name")
If you have entered a bad sql-statement you will get an error-message created by  ErrorHandler-Class which includes a help-variable. In this case you will immediately see the sql-Query. If error-logging has been implemented then the error also has been logged.

At the end i want to present a short example for the use of  String-Class. This class is loaded automatically within every page and makes an object called str available. This is quasi a static class and so it can be used immediately without creating an instance of it. Now a short example. I just want to demonstrate 2 methods. You can read the functionality of all the other methods in the documentation of  String-Class.

'Clone a string n-times
response.write "Cloned string: "
response.write str.clone("abc", 10)

'Every letter of every word upper-case
response.write "capitalize: "
response.write str.capitalize("tom hanks")
9. Resumeé
If you have read the whole tutorial and tried out all the examples you should see now how easy it can be to create web-applications. You see all the advantages of using a public library. With this tutorial you have the basic-skills to use the GabLib. Now it shouldnt be a problem to use other classes. You will see the library will grow from day to day and we appreciate every help and every comment for this project.

The goal of this library is to motivate the people out there to try out the library and maybe to use it. But a very important point is to get feedback about it and maybe to find some persons who has fun with it and maybe also wants to help us on improving the library.

  • The library is a basis for re-useable programming.
  • Source-code is much simpler and clearly arranged.
  • You can update the classes every time and use the new functionality
  • and a lot more :)
Michal
To get all the classes and updates visit http://gablib.grafix.at

winzip iconDownload article

Note: Due to the size or complexity of this submission, the author has submitted it as a .zip file to shorten your download time. Afterdownloading it, you will need a program like Winzip to decompress it.Virus note:All files are scanned once-a-day by Planet Source Code for viruses, but new viruses come out every day, so no prevention program can catch 100% of them. For your own safety, please:
  1. Re-scan downloaded files using your personal virus checker before using it.
  2. NEVER, EVER run compiled files (.exe's, .ocx's, .dll's etc.)--only run source code.

If you don't have a virus scanner, you can get one at many places on the net including:McAfee.com


Other 2 submission(s) by this author

 


Report Bad Submission
Use this form to tell us if this entry should be deleted (i.e contains no code, is a virus, etc.).
This submission should be removed because:

Your Vote

What do you think of this article (in the Advanced category)?
(The article with your highest vote will win this month's coding contest!)
Excellent  Good  Average  Below Average  Poor (See voting log ...)
 

Other User Comments


 There are no comments on this submission.
 

Add Your Feedback
Your feedback will be posted below and an email sent to the author. Please remember that the author was kind enough to share this with you, so any criticisms must be stated politely, or they will be deleted. (For feedback not related to this particular article, please click here instead.)
 

To post feedback, first please login.