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

<STYLE>
BODY, TD {
	font-size:9pt;
	font-family:Tahoma;
	color:#050A39;
}
.textbox {
	padding:20px
}
.codeBlock {
	font-family:courier;
	padding:5px;
	margin:15px;
	font:10pt/17px;
	background-color:#EEE;
	color:#000080;
}
.code {
	font-family:courier;
	color:#000080;
}
.comment {
	color:#008000;
}
.HL2 {
	 background-color:#D2D2D2;
	 padding:10px;
	 font-weight:bold;
}
</STYLE>
<TABLE border="0" cellpadding="0" cellspacing="0" width="100%">
<TR>
	<TD class="HL2">Lets get started - Beginners tutorial GabLib</TD>
</TR>
<TR>
	<TD class="textbox">
		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.
		<P>
		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 ;)
		<P>
		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. 
		<P>
		<strong>A quick note:</strong> 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).
	</TD>
</TR>
<TR>
	<TD class="HL2"><strong>1. What should you know after this tutorial?</strong></TD>
</TR>
<TR>
	<TD class="textbox">
		<UL>
			<LI>Introduction to the GabLib. How to work with it? Pros, Problems, etc.</LI>
			<LI>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.</LI>
			<LI>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.</LI>
			<LI>You will see some examples how to use classes of the basic-package.</LI>
			<LI>and a lot more.</LI>
		</UL>
	</TD>
</TR>
<TR>
	<TD class="HL2"><strong>2. Download the basic-package</strong></TD>
</TR>
<TR>
	<TD class="textbox">
		<div style="padding:4px;">&nbsp;Download Basic-package (included in zipfile)</div>
		Extract the ZIP-file and keep the file/folder structure. Copy the whole <span class="code">gab_Library</span> - 
		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:
		
		<DIV class="codeBlock">
			/gab_Library/<br>
			<div style="padding-left:40px;">
				class_constants/<br>
				class_CreateDropdown/<br>
				class_debuggingConsole/<br>
				class_errorHandler/<br>
				class_lib/<br>
				<div style="padding-left:40px;">
					images/
				</div>
				class_customLib/<br>
				class_customMailSend<br>
				class_page/<br>
				class_string/
			</div>
		</DIV>
		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.
	</TD>
</TR>
<TR>
	<TD class="HL2"><strong>3. Implementation of custom-methods - &nbsp;CustomLib-Class</strong></TD>
</TR>
<TR>
	<TD class="textbox">
		&nbsp;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 &nbsp;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 
		&nbsp;CustomLib-Class. Nothing else!
		Now I want to decribe which methods ("interfaces") must be/or should be present in the 
		&nbsp;CustomLib-Class:<br>
		<OL>
			<LI>
				<span class="code">sub establishDatabaseConnection(parameter)</span> - 
				This method should establish a database connection using an object called <span class="code">cnn</span>.
				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:
				<div class="codeBlock">
					cnn.Provider = "Microsoft.Jet.OLEDB.4.0"<br>
					<span class="comment">'FILENAME.MDB should be replaced by the filename of your database.</span>
					cnn.ConnectionString = "Data Source=" & Server.MapPath ("FILENAME.MDB")<br>
					cnn.open
				</div>
				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 
				<span class="code">establishDatabaseConnection(Parameter)</span> is called by the
				&nbsp;Page-Class. 
				&nbsp;Page-Class has a method called
				<span class="code">makeDbConnection(Parameter)</span> which calls the 
				<span class="code">establishDatabaseConnection(Parameter)</span> method. You will only need it
				to establish database-connection manually.
			</LI>
			<br><br>
			<LI>
				<span class="code">function userLoggedIn()</span> - 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 
				<span class="code">True</span> (User is logged in) or if the session-var has a different value or
				even does not exist we return <span class="code">False</span> (user not logged in). This method should also
				NEVER be called directly. It is something like an "interface" which is used by 
				&nbsp;Page-Class.
			</LI>
			<br><br>
			<LI>
				<span class="code">logError(errorDuring, errorDesc, errorSource, debuggingVar, requestedUrl, referrer, sessionVars)</span> - 
				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 
				<span class="code">True</span> and if the error-log failed you should return <span class="code">False</span>.
				This method is exclusively used by &nbsp;ErrorHandler-Class.
				You will find a detailed information in the documentation of the class 
				&nbsp;ErrorHandler-Class.
			</LI>
			<br><br>
			<LI>
				<span class="code">accessDuringMaintenance()</span> - This "interface" should return <span class="code">True</span> 
				(user has access during maintenance) or <span class="code">False</span> (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 &nbsp;Page-Class.
				IP-Check is implemented by default.
			</LI>
		</OL>
		Okay now the &nbsp;CustomLib-Class should be customized enough. Again i want to
		inform you to never call these "interfaces" directly from &nbsp;CustomLib-Class.
		Only call your "custom" methods. The &nbsp;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 &nbsp;Page-Class):<br>
		<div class="codeblock">
			<span class="comment">'Custom-Method call</span><br>
			lib.custom.myMethod("OneParameter")<br>
			<span class="comment">'Library-Method call. (global methods)</span><br>
			lib.getRecordset("UPDATE users SET vorname = 'John'")
		</div>
	</TD>
</TR>
<TR>
	<TD class="HL2"><strong>4. Custom Email-class - &nbsp;CustomSendMail-Class </strong></TD>
</TR>
<TR>
	<TD class="textbox">
		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.
		<P>
		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
		&nbsp;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):
		<div class="codeblock">
			<div class="comment">'No include necessary. The class is loaded automatically.</div>
			set myMail = new customSendMail<br>
			with myMail<br>
			<div style="padding-left:40px;">
				.subject = "My first mail"<br>
				.fromEmail = "jonh@connor.com"<br>
				.fromName = "John Connor"<br>
				.body = "Hand on buddy!"<br>
				.addRecipient("TO", "arnold@schwarzenegg.er", "Arnie")<br>
				.send(stmp.mail.com)<br>
			</div>
			end with
		</div>
	</TD>
</TR>
<TR>
	<TD class="HL2"><strong>5. Custom-pages implementation - nologin.asp, maintanance.asp, frameSetter.asp</strong></TD>
</TR>
<TR>
	<TD class="textbox">
		These files are located in the folder of &nbsp;CustomLib-Class 
		and should be implemented with your own functionality and design. Just some sentences:
		<OL>
			<LI>
				<span class="code">nologin.asp</span> - 
				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 <span class="code">loginRequired = true</span> of 
				&nbsp;Page-Class. The <span class="code">noLogin.asp</span> 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:
				<div class="codeblock">angeforderteSeite = request.serverVariables("SCRIPT_NAME")</div>
			</LI>
			<LI>
				<span class="code">maintanance.asp</span> - This page will be displayed if maintenance-work is on. Pre-requisite
				is that the site has been built with &nbsp;Page-Class.
				You can turn on maintenance-work setting the <span class="code">MAINTENANCE_WORK</span> readonly property 
				of &nbsp;Constants-Class to <span class="code">true</span>. 
			</LI>
			<br><br>
			<LI>
				<span class="code">frameSetter.asp</span> - 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 <span class="code">framesetter</span>
				property of &nbsp;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.
			</LI>
		</OL>
	</TD>
</TR>
<TR>
	<TD class="HL2"><strong>6. Configure global constants - &nbsp;Constants-Class</strong></TD>
</TR>
<TR>
	<TD class="textbox">
		This class is loaded automatically within the &nbsp;Page-Class and
		is available in every page. Because of this an object called <span class="code">consts</span> is available in every page.
		Till now we can get every global-var (project-constant) using the following code <span class="code">consts.myConstantName</span>. 
		Constants are readonly. If you need further information please read the &nbsp;Constants-Class
		documentation. I want to do a short introduction to every constant. Just change the values in the constructor:
		<OL>
			<LI>
				<span class="code">consts.webadmin</span> - This two-dimensional array stores the webmaster(s) of the project.
				Is used for example in &nbsp;ErrorHandler-Class for error-reporting.
			</LI>
			<br><br>
			<LI>
				<span class="code">consts.allowed_on_maintenance</span> - 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. 
			</LI>
			<br><br>
			<LI>
				<span class="code">consts.company_name</span> - Company-name, Project-name, etc.
			</LI>
			<br><br>
			<LI>
				<span class="code">consts.domain</span> - The domainname. e.g. http://www.myDomain.com/
			</LI>
			<br><br>
			<LI>
				<span class="code">consts.hostIP</span> - IP of the host. z.b. 192.168.0.1
			</LI>
			<br><br>
			<LI>
				<span class="code">consts.smtp_server</span> - Smtp-server for email-sending.
			</LI>
			<br><br>
			<LI>
				<span class="code">consts.logo</span> - Stores the path to the site-logo e.g. /images/logo.gif
			</LI>
			<br><br>
			<LI>
				<span class="code">consts.logoSmall</span> - Stores the path to the small site-logo e.g. /images/logosmall.gif
			</LI>
			<br><br>
			<LI>
				<span class="code">consts.bgColor</span> - Default background-color for all pages. e.g. #FFFFFF
			</LI>
			<br><br>
			<LI>
				<span class="code">consts.page_stylesheet</span> - Path to the stylesheet-file e.g.. /style.css
			</LI>
			<BR><BR>
			<LI>
				<span class="code">consts.tablerowcolor1, consts.tablerowcolor2</span> - 
				These constants need a css-class name. These should be 2 different colors because these
				css-classes will be used by <span class="code">showMouseover()</span> - 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 
				<span class="code">showMouseover()</span> of &nbsp;Lib-Class.
				The detailed functionality of the method can be found in the documentation of 
				&nbsp;Lib-Class.
			</LI>
			<br><br>
			<LI>
				<span class="code">consts.tablemouseover</span> - Css-class-name for a css-class which formats
				a mouseover-effect of <span class="code">showMouseover()</span> - method.
			</LI>
			<br><br>
			<LI>
				<span class="code">consts.automated_bot_email, consts.automated_bot_name</span> - Name and email
				which should be used as send in all automated emails.
			</LI>
			<br><br>
			<LI>
				<span class="code">consts.email_send_on_error</span> - If you want to enable sending emails on
				error (true) else put a false.
			</LI>
			<br><br>
			<LI>
				<span class="code">consts.maintenance_work</span> - true/false. Turn on/off maintenance-work with
				this constant.
			</LI>
		</OL>
		<div class="codeblock">
			<span class="comment">
				'Display the value of a constant-var:<br>
				'In this example we use domain-variable.
			</span><br>
			response.write consts.domain
		</div>
	</TD>
</TR>
<TR>
	<TD class="HL2"><strong>7. Now we start and create our first page</strong></TD>
</TR>
<TR>
	<TD class="textbox">
		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:
		
		<div style="padding:4px;">&nbsp;Default-Page-Template (included in the zipfile)</div>
		<P>
		Lets take a look at the template and explain some points:
		<div class="codeblock">
			<code><</code>!--#include virtual="/gab_Library/class_page/generatepage.asp"--<code>></code><br>
			<code><</code>%<br>
			set page = new generatePage<br>
			with page<br>
				<div style="padding-left:40px;">
				.DBConnection 	= false<br>
				.title 			= "My Page"<br>
				.contentSub		= "main"<br>
				.debugMode		= false<br>
				.loginRequired	= false<br>
				.draw()<br>
				</div>
			end with<br>
			set page = nothing<br>
			<br>
			<span class="comment">
			'********************************************************************<br>
			'* main - we start . DONT FORGET TO KILL ALL OBJECTS!! <br>
			'********************************************************************<br>
			</span>
			sub main()<br>
				<br>
			end sub<br>
			%<code>></code>
		</div>
		You see that first we need to include the &nbsp;Page-Class.
		Now it is possible to create a new object called <span class="code">page</span> 
		using <span class="code">set page = new generatePage</span>. Then just set some properties and draw the page using
		<span class="code">draw()</span> - method. In this case the page-content should be implemented to the 
		<span class="code">main()</span> - procedure. The <span class="code">contentSub</span> - property
		set the name of the procedure which will be called on pageload.
	</TD>
</TR>
<TR>
	<TD class="HL2"><strong>8. Some short examples of use</strong></TD>
</TR>
<TR>
	<TD class="textbox">
		Now its beginning to be real funny. We have our own page created with &nbsp;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 <span class="code">main()</span> - procedure:
	
		<div class="codeblock">
			response.write consts.hostIP
		</div>
		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 &nbsp;Lib-Class without creating an
		instance of the class. Try the following code (again put the cut into the <span class="code">main()</span> - procedure):
		<div class="codeblock">
			<code><</code>TABLE width="100%"<code>></code><br>
			<span class="comment">'alternating mouseover-effect</span><br>
			<code><</code>% for i = 0 to 9 %<code>></code><br>
				<div style="padding-left:40px;">
					<code><</code>TR<code><</code>%= lib.showMouseover(i,true) %<code>></code><code>></code><br>
						<div style="padding-left:40px;">
							<code><</code>TD<code>></code>Mouse is no cat<code><</code>/TD<code>></code><br>
						</div>
					<code><</code>/TR<code>></code><br>
				</div>
			<code><</code>% next %<code>></code><br>
			<code><</code>/TABLE<code>></code>
		</div>
		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 &nbsp;DebuggingConsole-Class
		to get as much debug-information as we can. First we need to turn on debugging-mode. We do this within
		the &nbsp;Page-Class:
		<div class="codeblock">
			<div class="comment">
				'we use the page-object that we created before
			</div>
			page.debugMode = true
		</div>
		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 <span class="code">response.write varName</span> 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 <span class="code">debugVar-Collection</span>
		of the &nbsp;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 <span class="code">debugVar-Collection</span>:
		<div class="codeblock">
			<div class="comment">
				'First we create a variable called X<br>
				'I have choosen a constant of constants-class as value<br>
				'to demonstrate again how to get global constant-values.<br>
				'Now we add the variable to the debugVar-Collection of page-class.<br>
				'We do this using the addDebugVar - method.<br>
				'First parameter is description of the variable and second is the var itself.
			</div><br>
			x = consts.company_name<br>
			page.addDebugVar("My variable X", x)<br><br>
			<div class="comment">
				'We turn on the debug-Mode and our variable<br>
				'appears in the debugging-console.
			</div><br>
			page.debugMode = true
		</div>
		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
		<span class="code">lib.getRecordset</span> - method. With the help of this method it is much easier to get
		recordsets of the database. Following example:
		<div class="codeblock">
			<div class="comment">
				'first we activate database-connection.<br>
				'pre-requisite is that the establishDatabaseConnection-Method<br>
				'has been implemented in the customLib-class.
			</div>
			<br>
			page.DBConnection = true
			<br><br>
			<div class="comment">
				'SQL-Query should be written by everyone himself,<br>
				'so the tables, etc. are available ;)
			</div>
			<br>
			sql = "SELECT name FROM users"<br>
			set rs = lib.getRecordset(sql)<br>
			response.write rs("name")
		</div>
		If you have entered a bad sql-statement you will get an error-message created by
		&nbsp;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. 
		<P>
		At the end i want to present a short example for the use of 
		&nbsp;String-Class. This class is loaded automatically
		within every page and makes an object called <span class="code">str</span> 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 &nbsp;String-Class.
		 <div class="codeblock">
		 	<div class="comment">'Clone a string n-times</div>
			response.write "Cloned string: "<br>
			response.write str.clone("abc", 10)<br><br>
			
			<div class="comment">'Every letter of every word upper-case</div>
			response.write "capitalize: "<br>
			response.write str.capitalize("tom hanks")
		 </div>
	</TD>
</TR>
<TR>
	<TD class="HL2"><strong>9. Resumeé</strong></TD>
</TR>
<TR>
	<TD class="textbox">
		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.
		<P>
		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.
		<UL>
			<LI>The library is a basis for re-useable programming.</LI>
			<LI>Source-code is much simpler and clearly arranged.</LI>
			<LI>You can update the classes every time and use the new functionality</LI>
			<LI>and a lot more :)</LI>
		</UL>
		Michal<br>
		To get all the classes and updates visit http://gablib.grafix.at
	</TD>
</TR>
</TABLE>