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

				


	
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:

		

			

				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.
			
			


			

				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.
			
			


			

				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.
			
			


			

				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:
		

			

				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")
			
			

				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. 
			
			


			

				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:
		

			

				consts.webadmin - This two-dimensional array stores the webmaster(s) of the project.
				Is used for example in  ErrorHandler-Class for error-reporting.
			
			


			

				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. 
			
			


			

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


			

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


			

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


			

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


			

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


			

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


			

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


			

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


			

				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.
			
			


			

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


			

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


			

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


			

				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