Creating an Appointment Calendar - Part 02 - Appointment Calendar package blog

By Michael J. Fuhrman

enetarch.net

<email contact>

Welcome back to the second part of "Creating an Appointment Calendar". The previous post provided a general understanding of how Ladder works within an application framework. It then provide d the application requirements and design guides for an Appointment Calendar. It also covered the Data Class design for the Appointment Calendar.

This post will discuss an installation script that allows Ladder know about new data class. It will describe two classes that will be used throughout the rest of the series that extend ldrItem and ldrFolder respectively. It will then demonstrate how to create a new Appointments folder so that Appointments can be stored in it.


7. Create the class install script:
===================================

This section will list the scripts needed to create the Appointment data classes. Following the scripts is a line by line description. In addition, checks for file updates are provided to make this script work.

Just as a class has to be created in PHP before an instance can be created, so must a class be defined in Ladder before an instance can be stored. To that end, the scripts that follow describe to Ladder what each class’s base type is: [ Folder | Item | Reference ] and if it is an Item Class, then what properties that Item Class contains.

[... Install.php ...]

01.. function dirPath() { return ("../"); }
02..
03.. Include_Once (dirPath() . "Shared/Install_Functions.inc");
04.. Include_Once (dirPath() . "Shared/_app.inc");
05..
06.. Function php_Main ()
07.. {
08.. $szStr =
09.. " dTarget DateTime, " .
10.. " nTime Integer, " .
11.. " nLength Integer, " .
12.. " szMemo varChar(250) " ;
13..
14.. CreateClass ("Common_Appointment", ldrGlobals::cisItem(), 0 , true, $szStr);
15..
16.. CreateClass ("Common_Appointments", ldrGlobals::cisFolder(), 0 , true);
17.. }

----------

Line 1 .. creates a global function dirPath that abstracts the location of shared libraries located elsewhere in the web server’s directory path.

Line 3 .. includes a general set of functions used to install classes. This library basically abstracts Ladder's create class function.

Line 4 .. includes the _app.inc file which loads a general set of functions and the Ladder PHP classes.

Line 6 .. is called from _app.inc. php_Main() was created to insure that all database objects are initialized and uninitialized as each page is executed to conserve database connections.

Line 8 - 12 .. create a SQL structure statement based on the Appointment Item class's data model.

Line 14 .. adds the Appointment Item data class to Ladder's list of classes and creates a corresponding table in Ladder's database space called "Common_Appointment".

Line 16 .. adds the Appointments Folder data class to Ladder's list of classes.

At this point Ladder can create and manage instances of the Appointment and Appiontments data classes.

----------

Note: the following code may or may not be present in the Ladder Class Package available through PHP Classes and is provided here, for your convenience:

[… Install_Functions.inc …]
1.. function CreateClass ($thsName, $nBaseType, $ofClass, $bAcceptsAll, $szStr)
2.. {
3.. print ("Adding Class .. " . $thsName . "<BR>");
4.. gblLadder()->CreateClass ($thsName, $nBaseType, $ofClass, $bAcceptsAll, $szStr);
5.. }

Note: if gblLadder() is not found, add the following code to “_app.inc“ before "Main ();"

1.. function gblLadder() { global $gblLadder; return ($gblLadder); }

----------

8. Create an Appointments Folder in Ladder:
===========================================

This section lists the script responsible for creating a folder in Ladder. This folder “Appointments” will contain all the Appointment Items to be created. This folder can be retrieve either via the instance ID or via Name. For the purposes of this example, the folder will be referred to by ID.

Note: CreateFolder.php can be executed multiple times to create multiple Appointment folders.

[... CreateFolder.php ...]

01.. function dirPath() { return ("../"); }
02..
03.. Include_Once (dirPath() . "Shared/_app.inc");
04..
05.. Function php_Main ()
06.. {
07.. $aryRoots = gblLadder()->getRoots();
08.. $fldrRoot= gblLadder()->getItem ($aryRoots [1]);
09..
10.. $clsCommon_Appointments = gblLadder()->getClass ("Common_Appointments")->ID();
11..
12.. $fldrAppoinments = $fldrRoot->Create_Folder ("Appointments", "Appointments are stored here", $clsCommon_Appointments);
13..
14.. $fldrAppoinments ->Store();
15..
16.. print ("The Appointments Folder ID is " . fldrAppoinments->ID() . "<BR>");
17.. }

------------

Line 07 .. retrieves a list of the ID's associated with the Root Folders. The first ID listed in the Array is always the RootFolder.

Line 08 .. retrieves the RootFolder into fldrRoot. fldrRoot is now an instance of ldrFolder.

Line 10 .. retrieves the class "Common_Appointments" into clsCommon_Appointments. clsCommon_Appointments is an instance of Folder which extends ldrProperties, which is why the function ID() is now available. The ID is used in Line 12 when an instance of Common_Appointment is created.

Line 12 .. Creates a new instance of class Common_Appointment based on its ID value. Each instance that is created in Ladder has several properties: Name, Description, Class. Ladders helps you differentiate between a Folder, Item and Reference through unique Create Statements.

Line 14 .. Each instance created through Ladder is not stored until you call Store().

Line 16 .. Displays what ID the new instance of Common_Appointments has been assigned.

9. Create the Appointment data classes:
==============================

[ Common_Appointment.cls ]
01.. Class Common_Appointment extends ldrItem
02.. {
03.. public $dTarget = "";
04.. public $nTime = 17;
05.. public $nLength = 2;
06.. public $szMemo = "";
07..
08.. Function Create (ldrFolder $thsParent, $thsName, $thsDescription, $thsClass=0)
09.. {
10.. if ($thsParent == null) return;
11.. if ($thsClass == "") thsClass = $this->getClass();
12..
13.. parent::Create ($thsParent, $thsName, $thsDescription, $thsClass);
14.. }
15..
16.. // ====================================
17..
18.. Function getClass ()
19.. { return ( gblLadder()->getClass("Common_Appointment"))->ID(); }
20..
21.. Function setState ($objFolder)
22.. {
23.. parent::setState ($objFolder->getState());
24.. parent::Connect ($objFolder->cn);
25..
26.. $this->dTarget = parent::Field ("dTarget");
27.. $this->nTime = parent::Field ("nTime");
28.. $this->nLength = parent::Field ("nLength");
29.. $this->szMemo = parent::Field ("szMemo");
30.. }
31..
32.. Function Store ()
33.. {
34.. parent::setField ("dTarget", $this->dTarget);
35.. parent::setField ("nTime", $this->nTime);
36.. parent::setField ("nLength", $this->nLength);
37.. parent::setField ("szMemo", $this->szMemo);
38..
39.. parent::Store();
40.. }
41..
42.. // ====================================
43..
44.. // Add class specific functions here to encapsulate how data is massaged.
45.. // These functions are used when data is encrypted, or complex values are a
46.. // stored in field. Avoid using these fields to point to another object's instance
47.. // stored in or outside of Ladder.
48
49.. }

------------

Line 1 .. creates the class definition for Common_Class and extends the ldrItem class.

Lines 3 - 6 .. lists the variables that the class stores. These are made publicly available for this class, but may not be publicly available for other classes. The determinant is whether or not the variables require special handling in order to be properly maintained. Stronger requirements would force all the variables to be checked for proper data type, min and max limits .. in other words, there are only so many 15 minute increments in a day. Plus since the max length of a Memo field is 250 characters, that field should not be exceeded without generating a nice error message.

Lines 8 - 14 .. provides the programmer with a way to create an instance of the Common_Appointment class in Ladder without using Ladder's constructs.

Lines 18-19 .. encapsulate and override the process of returning the Class ID for the class. This is so that future classes don't have to rely on gblLadder()->getClass ($szClassName) where the name in $szClassName can be misspelled. However creating a new instance of Common_Class will add over head to the process.

Lines 21 - 30 .. override the setState function provided by ldrProperties. This function insures that the state of ldrItem and ldrProperties is configured properly. It also transfers the state of the fields for this particular instance into the class public variables.

Lines 32 .. 40 .. override the Store function provided by ldrItem. This insures that the public fields are copied to ldrItem prior to actually storing the object.

------------

[ Common_Appointments.cls ]
01.. Class Common_Appointments extends ldrFolder
02.. {
03.. Function Create (ldrFolder $thsParent, $thsName, $thsDescription, $thsClass=0)
04.. {
05.. if ($thsParent == null) return;
06.. if ($thsClass == "") thsClass = $this->getClass();
07..
08.. parent::Create ($thsParent, $thsName, $thsDescription, $thsClass);
09.. }
10..
11.. // ====================================
12..
13.. Function getClass ()
14.. { return ( gblLadder()->getClass(""))->ID(); }
15..
16.. Function setState ($objFolder)
17.. {
18.. parent::setState ($objFolder->getState());
19.. parent::Connect ($objFolder->cn);
20.. }
21..
22.. // ====================================
23..
24.. Function Create_Appointment ($thsName, $thsDescription, $thsClass=0)
25.. {
26.. $itmAppointment = new Common_Appointment ();
27.. $itmAppiontment->Create ($this, $thsName, $thsDescription, $thsClass);
28.. return ($itmAppointment);
29.. }
30..
31.. Function Count_Appointments ()
32.. {
33.. $clsCommon_Appointment = $gblLadder->getClass ("Common_Appointment")->ID();
34.. return (parent::Count ("", Array (1=>$clsCommon_Appointment)));
35.. }
36..
37.. Function get_Appointment ($nPos) {}
38.. {
39.. $clsCommon_Appointment = $gblLadder->getClass ("Common_Appointment")->ID();
40.. return (parent::Item ($nPos, Array (1=>$clsCommon_Appointment)));
41.. }
42..
43.. // ====================================
44..
45.. }

------------

Line 3 .. 9 .. provides the programmer with a way to create an instance of the Common_Appointments class in Ladder without using Ladder's constructs.

Line 13 - 14 .. encapsulate and override the process of returning the Class ID for the class. This is so that future classes don't have to rely on gblLadder()->getClass ($szClassName) where the name in $szClassName can be misspelled. However creating a new instance of Common_Class will add over head to the process.

Line 16 - 20 .. override the setState function provided by ldrProperties. This function insures that the state of ldrItem and ldrProperties is configured properly. It also transfers the state of the fields for this particular instance into the class public variables.

Line 24 - 29 .. creates an Appointment instance in the Appiontments Folder.

Line 31 - 35 .. counts the number of Appointments in the Appointments Folder. Additional options can be added to filter out the types of appointments needed.

Line 37 - 41 .. retrieves an appointment based on its ID position in the Appointments Folder. Additional options could be provided to allow the programmer to filter and order the appointments.

------------

Some design considerations:

While Common_Appointment Item data class extends ldrItem, Ladder is not aware of classes that have been created in PHP and therefore it cannot return this class, Ladder instead returns ldrItem. To assist the programmer, the setState function is provided.

To avoid the max memory limit for running a PHP page, the class is kept as small as possible. Thus the class does not carry with it any installation functions that would encapsulate the creation and destruction of the class from Ladder.

Wrap Up
=============================

This post created two new classes for Ladder to manage, and created a folder for the Appointment Items to be stored in. It also implemented the Appointment and Appointments classes by extending an Item and Folder class respectively. In post 6, section 12, the Appointments Data Class will be extended to sort Appointments by date.

Next Post
======================================

The next post will describe how to extend the ldrFolder and ldrItem classes so that PHP classes for Common_Appointment and Common_Appointments can be created.


/* =======================================
Copyright 1998 - 2010 - E Net Arch
This program is distributed under the terms of the GNU
General Public License (or the Lesser GPL).
======================================= */