USC Class Manual By Shadi Ali

MySQL Table:

This class uses a MySQL table to store the categories data, look below for the default table structure:

CREATE TABLE `categories` (
`id` BIGINT NOT NULL AUTO_INCREMENT ,
`position` VARCHAR( 255 ) NOT NULL ,
`c_name` VARCHAR( 255 ) NOT NULL ,
`c_desc` TINYTEXT NOT NULL ,
`c_icon` VARCHAR( 255 ) NOT NULL ,
`c_group` VARCHAR( 255 ) NOT NULL default '0' ,
PRIMARY KEY ( `id` )
);

Class Variables:

Here I'm going to explain the class variables

$HtmlTree

This varialbe holds the default HTML template for the HTML list, It is used only when you call the html_output() function ... its an array and contains 4 elements as the following

$HtmlTree['header'] This element holds the head of the HTML list template which will be printed only once before the categories list.

$HtmlTree['BodySelected'] This template will be used for the current(selected) category item, it will be displayed once for the selected category ( defined by $id ).

$HtmlTree['BodyUnselected'] This template will be used for the normal category list items, it will be repeated with every category in the list.

$HtmlTree['footer'] And this one will be printed once at the end of the list.

default value for the $HtmlTree Variable:

var $HtmlTree     = array(
                            "header"            => '<table width=300px border=0 cellpadding=2 cellspacing=2>',
                            "BodyUnselected"   =>    '<tr>
                                                        <td>
                                                            [prefix]&raquo;<a href="?id=[id]">[name]</a>
                                                         </td>
                                                     </tr>',
                            "BodySelected"       =>    '<tr>
                                                        <td>
                                                            [prefix]&raquo;<a href="?id=[id]"><strong>[name]</strong></a>
                                                         </td>
                                                     </tr>',                                                    
                                                    
                                        
                            "footer"            => '</table>',
                          );


$name_prefix  this variable will be printed before the category name depening on its position, i.e: if category position level is 5, the $name_prefix will be printed 5 times before the category name ... default value is a space

$table_name this is the categories MySQL table name, if you are using the default structure it should be 'categories'

$itemsTable in case you want to associate items table to be used with this class, this variable should hold the items table name.

$CID_FieldName and this one should hold the field name which refere to the category ID. ( check associating example at the end of this manual for more explanasion. )

Main Functions/Methods:

add_new:

this method is used to insert new category to the structure , it takes 4 params as the following:

$parent : every category should have a parent category, if it doesn't then it will be a root category ... this variable holds the parent category ID otherwise assign zero.

$name,$desc and $icon ( category name , description and icon image url/path )

example on method usage:

add_new($parent , $name , $desc , $icon );

update:

this method is used to update existing category , it takes 5 params as the following:

$id: the ID of category which you want to update.

$parent : every category should have a parent category, if it doesn't then it will be a root category ... this variable holds the parent category ID otherwise assign zero.

$name,$desc and $icon ( category name , description and icon image url/path )

example on method usage:

update($id , $parent , $name , $desc , $icon ) ;

delete:

this method is used to delete existing category and all sub-categories below it, needs 2 params as the following:

$id: the ID of category which you want to delete.

$items: if you are associating items to the categories, assign 1 to delete all associated items otherwise it will delete the categories only. ( look below for more information about associating ).

example on method usage:

delete($id,$items)

build_list:

this method is used to return an array with the categories,it takes 2 params as the following:

$id: if you want to display an expanded list below a specific category fill its ID , otherwise the list will be expanded from the roots.

$collapesd: determine if the expanding level to be one-level only or unlimited.

examples on method usage:

General Usage

build_list($id , $collapsed)

I'm going to explain some ways to use this method based on the following list example Category_Name(ID)

-Root1 (1)

-Sub1-1 (2)

-Sub1-1-1 (3)

-Sub1-1-2 (4)

-Sub1-2 (5)

-Sub1-2-1 (6)

-Root2 (7)

-Sub2-1 (8)

 

Ok lets start ...

 

To expand a root:

-Root1 (1)

-Sub1-1 (2)

-Sub1-1-1 (3)

-Sub1-1-2 (4)

-Sub1-2 (5)

-Sub1-2-1 (6)

+Root2

build_list( 1 )

To display/open one-level only of expanded root:

-Root1 (1)

+Sub1-1 (2)

+Sub1-2 (5)

+Root2

build_list( 1 , "collapsed")

To display/open one-level only of a child category:

-Root1 (1)

-Sub1-1 (2)

+Sub1-1-1 (3)

+Sub1-1-2 (4)

+Sub1-2 (5)

+Root2

build_list( 2 , "collapsed")

And finally to display the full expanded list:

-Root1 (1)

-Sub1-1 (2)

-Sub1-1-1 (3)

-Sub1-1-2 (4)

-Sub1-2 (5)

-Sub1-2-1 (6)

-Root2 (7)

-Sub2-1 (8)

build_list( 0 )

browse_by_id:

this function returns an array of sub-categories within a specific category .. and takes the category ID as a param $id

browse_by_id( 0 )

fetch:

this function returns the category info .. and takes the category ID as a param $id

fetch( 0 )

html_output:

this function returns the HTML list output, and takes the selected category ID as a param or it will print the roots list.

you can modify the style of the list by modifying the $HtmlTree variable as showen above.

this function is useful when you want to print a auto-expand list depending on the selected category.

html_output($id)

count_categories:

this function returns how many sub categories in below the given category ID, and takes category ID as a param.

count_categories($id);

Associating with another Table:

Currently the class support basic integration with another MySQL table of an items .. for example if you want to use this class with a book store , this class will build the categories and you should have another table contains the books records ( I call it items table ) ... for sure every book record should contain a field refere to its category ID ( I call it CID ).

This class provide basic functions to be executed on the items like .. get the items count in a Top-Level category and delete all items in a Top-Level category too.

to integrate your items table with this class , you will need to set 2 main class variables

$itemsTable this hold the items table name.

$CID_FieldName this hold the name of the field in that table which refere to the item's categoryID.

 

the functions usage:

count_items

this function returns how many items (total items) in a category and its sub-category, and takes category ID as a param.

count_items($id);

delete:

this method is used to delete existing category and all sub-categories below it, needs 2 params as the following:

$id: the ID of category which you want to delete.

$items: if you are associating items to the categories, assign 1 to delete all associated items otherwise it will delete the categories only.

example on method usage:

delete($id,$items)


Manual End.

Shadi Ali
Write2Shadi@Gmail.com
Jan/15/2006