content
Packages
Interfaces
Classes
Files

Class: CategoriesManager

Source Location: /content/categories_manager.class.php [line 101]

Class Overview


This class enables you to manage easily the administration of categories for your modules. It's as generic as possible, if you want to complete some actions to specialize them for you module, you can create a new class inheritating of it in which you call its methods using the syntax parent::method().
/!\ Warning : /!\
  • Your DB table must respect some rules :
    • You must have an integer attribute whose name is id and which represents the identifier of each category. It must be a primary key.
    • You also must have an integer attribute named id_parent which represents the identifier of the parent category (it will be 0 if its parent category is the root of the tree).
    • To maintain order, you must have a field containing the rank of the category which be an integer named c_order.
    • A field visible boolean (tynint 1 sur mysql)
    • A field name containing the category name
  • In this class the user are supposed to be an administrator, no checking of his auth is done.
  • To be correctly displayed, you must supply to functions a variable extracted from a file cache. Use the Cache class to build your file cache. Your variable must be an array in which keys are categories identifiers, an values are still arrays which are as this :
    • key id_parent containing the id_parent field of the database
    • key name containing the name of the category
    • key order
    • key visible which is a boolean
  • You can also have other fields such as auth level, description, visible, that class won't modify them.
  • To display the list of categories and actions you can do on them, you may want to customize it. For that you must build an array that you will give to set_display_config() containing your choices :
    • Key 'xmlhttprequest_file' which corresponds to the name of the file which will treat the AJAX requests. We usually call it xmlhttprequest.php.
    • Key 'url' which represents the url of the category (it won't display any link up to categories if you don't give this field). Its structure is the following :
      • key 'unrewrited' => string containing unrewrited urls (let %d where you want to display the category identifier)
      • Key administration_file_name which represents the file which allows you to update category
      • rewrited url (optionnal) 'rewrited' => string containing rewrited urls (let %d where you want to display the category identifier and %s the category name if you need it)
If you need more informations to use this class, we advise you to look at the wiki of PHPBoost, in which there is a tutorial explaining how to use it step by step.

Author(s):



Class Details

This class enables you to manage easily the administration of categories for your modules. It's as generic as possible, if you want to complete some actions to specialize them for you module, you can create a new class inheritating of it in which you call its methods using the syntax parent::method().
/!\ Warning : /!\
  • Your DB table must respect some rules :
    • You must have an integer attribute whose name is id and which represents the identifier of each category. It must be a primary key.
    • You also must have an integer attribute named id_parent which represents the identifier of the parent category (it will be 0 if its parent category is the root of the tree).
    • To maintain order, you must have a field containing the rank of the category which be an integer named c_order.
    • A field visible boolean (tynint 1 sur mysql)
    • A field name containing the category name
  • In this class the user are supposed to be an administrator, no checking of his auth is done.
  • To be correctly displayed, you must supply to functions a variable extracted from a file cache. Use the Cache class to build your file cache. Your variable must be an array in which keys are categories identifiers, an values are still arrays which are as this :
    • key id_parent containing the id_parent field of the database
    • key name containing the name of the category
    • key order
    • key visible which is a boolean
  • You can also have other fields such as auth level, description, visible, that class won't modify them.
  • To display the list of categories and actions you can do on them, you may want to customize it. For that you must build an array that you will give to set_display_config() containing your choices :
    • Key 'xmlhttprequest_file' which corresponds to the name of the file which will treat the AJAX requests. We usually call it xmlhttprequest.php.
    • Key 'url' which represents the url of the category (it won't display any link up to categories if you don't give this field). Its structure is the following :
      • key 'unrewrited' => string containing unrewrited urls (let %d where you want to display the category identifier)
      • Key administration_file_name which represents the file which allows you to update category
      • rewrited url (optionnal) 'rewrited' => string containing rewrited urls (let %d where you want to display the category identifier and %s the category name if you need it)
If you need more informations to use this class, we advise you to look at the wiki of PHPBoost, in which there is a tutorial explaining how to use it step by step.

Tags:

[ Top ] - [ Class Details ] - [ Methods ] - [ Variables ]


Class Methods

constructor CategoriesManager [line 110]

CategoriesManager CategoriesManager( string $table, string $cache_file_name, &array[] &$cache_var)
Builds a CategoriesManager object

Parameters:

string   $table   Table name of the database which contains the require fields (explained in the class description)
string   $cache_file_name   Name of the cache file (usefull to regenerate the cache after a modification of the categories tree)
&array[]   &$cache_var   Array containing the correct data, descripted in the description of the class.
[ Top ] - [ Class Details ] - [ Methods ] - [ Variables ]

method add [line 127]

int add( int $id_parent, string $name, [bool $visible = CAT_VISIBLE], [int $order = 0])
Adds a category. We can decide if it will be visible and what its position will be

Tags:

  • return: The id of the category which has been added and 0 if it couldn't be added (the error will be explained in the check_error method). The error can be only NEW_PARENT_CATEGORY_DOES_NOT_EXIST, which means that its parent category doesn't exist.

Parameters:

int   $id_parent   Id of the category in which this category will be added
string   $name   Name of the category to add
bool   $visible   Is the category visible? CAT_VISIBLE if visible, CAT_UNVISIBLE else
int   $order  
[ Top ] - [ Class Details ] - [ Methods ] - [ Variables ]

method build_administration_interface [line 437]

mixed build_administration_interface( [bool $ajax_mode = NORMAL_MODE], [Template $category_template = NULL])
Builds the list of categories and links to makes operations to administrate them (delete, move, add...), it supplies a string ready to be displayed. It uses AJAX, read the class description to understand this user interface.

Tags:

  • return: If there was no error, it returns the HTML code which integrates the whole management of the category tree that you just have to display. If there is an error, it will return false and you will be able to know the error by using the wheck_error method. The raised erros can be INCORRECT_DISPLAYING_CONFIGURATION if the displaying configuration hasn't be established or is not correct.
  • warning: You must have defined a displaying configuration before calling this method. You must do it with the set_display_config method.

Parameters:

bool   $ajax_mode   Set this parameter to NORMAL_MODE if it's the global display and AJAX_MODE if it's called in the AJAX handler.
Template   $category_template   Use this parameter if you want to use a particular template. The default theme is framework/content/category.tpl.
[ Top ] - [ Class Details ] - [ Methods ] - [ Variables ]

method build_children_id_list [line 521]

int[] build_children_id_list( int $category_id, &int[] &$list, [bool $recursive_exploration = RECURSIVE_EXPLORATION], [bool $add_this = DO_NOT_ADD_THIS_CATEGORY_IN_LIST], [int $num_auth = 0])
Builds the list of all the children of a category

Tags:

  • return: The list of the ids of the subcategories.

Parameters:

int   $category_id   Id of the category for which we want to know the children
&int[]   &$list   Array in which the result will be written.
bool   $recursive_exploration   Sets if you want to explorer only the current sublevel of the tree or the whole subtree. Use RECURSIVE_OPERATION to make a recursive exploration, NOT_RECURSIVE_EXPLORATION otherwise.
bool   $add_this   If you want to add the current category to the list use ADD_THIS_CATEGORY_IN_LIST, DO_NOT_ADD_THIS_CATEGORY_IN_LIST otherwise.
int   $num_auth   If you want to filter the category according to an authorization bit, put its value here
[ Top ] - [ Class Details ] - [ Methods ] - [ Variables ]

method build_parents_id_list [line 558]

int[] build_parents_id_list( int $category_id, [bool $add_this = DO_NOT_ADD_THIS_CATEGORY_IN_LIST])
Builds the list of the parent categories of a category

Tags:

  • return: The list of the ids of the parent categories.

Parameters:

int   $category_id   Id of the category of which you want the list of parents categories.
bool   $add_this   If you want to add the current cat at the list. Use ADD_THIS_CATEGORY_IN_LIST if you want, DO_NOT_ADD_THIS_CATEGORY_IN_LIST otherwise.
[ Top ] - [ Class Details ] - [ Methods ] - [ Variables ]

method build_select_form [line 488]

string build_select_form( int $selected_id, string $form_id, string $form_name, [int $current_id_cat = 0], [int $num_auth = 0], [mixed[] $array_auth = array()], [bool $recursion_mode = STOP_BROWSING_IF_A_CATEGORY_DOES_NOT_MATCH], [Template $template = NULL])
Builds a formulary which allows user to choose a category in a select form.

Tags:

  • return: The HTML code which displays the select form.

Parameters:

int   $selected_id   Current category id (the id of the category selected in default displaying).
string   $form_id   HTML identifier of the object (id of the DOM Document Objet Model).t'
string   $form_name   HTML name of the select form in which you will manage to retrieve the selected category.
int   $current_id_cat   This parameter is to use when for instance you want to move a category in another, it will not display the children categories of the current category because you cannot move it into one of its subcategories.
int   $num_auth   If you don't want to display the categories which can not be chosen by the user, you can supply an authorization number which will be used on the $array_auth parameter
mixed[]   $array_auth   Authorization array which is used if a category hasn't special authorizations
bool   $recursion_mode   Sets whether you want to display only the current category or its whole subcategories. Use the constant RECURSIVE_EXPLORATION if you want to explore the whole tree, NOT_RECURSIVE_EXPLORATION otherwise.
Template   $template   If you want to customize the displaying, you can give the method a template objet in which variables will be assigned. The default template is framework/content/categories_select_form.tpl.
[ Top ] - [ Class Details ] - [ Methods ] - [ Variables ]

method change_visibility [line 345]

bool change_visibility( int $category_id, bool $visibility, [bool $generate_cache = LOAD_CACHE])
Changes the visibility of a category

Tags:

  • return: true if the visibility has been changed, false otherwise. If it fails, you can check the error with the method check_method, it can raise the following errors:
    • NEW_STATUS_UNKNOWN when the new status you want to give to the category is not supported (if it's neither CAT_VISIBLE nor CAT_UNVISIBLE)
    • CATEGORY_DOES_NOT_EXIST when the category for which you want to change the visibility doesn't exist

Parameters:

int   $category_id   id of the category whose property must be changed
bool   $visibility   set to visible or unvisible (use constants CAT_VISIBLE and CAT_UNVISIBLE)
bool   $generate_cache   if you want that the system regenerate the cache file of the module. Use the constants LOAD_CACHE to regenerate and reload the cache or DO_NOT_LOAD_CACHE else.
[ Top ] - [ Class Details ] - [ Methods ] - [ Variables ]

method check_display_config [line 400]

bool check_display_config( [bool $debug = PRODUCTION_MODE])
Checks if display configuration is good

Tags:

  • return: true if the configuration is correct, false otherwise.

Parameters:

bool   $debug   DEBUG_MODE if you want to display the errors, or PRODUCTION_MODE to return false if it fails.
[ Top ] - [ Class Details ] - [ Methods ] - [ Variables ]

method check_error [line 580]

bool check_error( int $error)
Checks if an error has been raised on the last reported error. At each call of a method of this class which can raise an error, the last error is erased.

Tags:

  • return: true if the error has been raised and false else.

Parameters:

int   $error   Constant corresponding to the error to check. Use the constant corresponding to the error (detailed in each method description).
[ Top ] - [ Class Details ] - [ Methods ] - [ Variables ]

method compute_heritated_auth [line 592]

mixed[] compute_heritated_auth( int $category_id, int $bit, int $mode)
Computes the global authorization level of the whole parent categories. The result corresponds to all the category's parents merged.

Tags:

  • return: The merged array that you can use only for the bit $bit.

Parameters:

int   $category_id   Id of the category for which you want to know what is the global authorization
int   $bit   The autorization bit you want to check
int   $mode   Merge mode. If it corresponds to a read autorization, use AUTH_PARENT_PRIORITY which will disallow for example all the subcategories of a category to which you can't access, or AUTH_CHILD_PRIORITY if you want to work in write mode, each child will be able to redifine the authorization.
[ Top ] - [ Class Details ] - [ Methods ] - [ Variables ]

method delete [line 308]

bool delete( int $id)
Deletes a category.

Tags:

  • return: true if the category has been deleted successfully and false otherwise, and in this case you can find the error in the check_error method. The error CATEGORY_DOES_NOT_EXIST is raised if the category to delete doesn't exist.

Parameters:

int   $id   Id of the category to delete.
[ Top ] - [ Class Details ] - [ Methods ] - [ Variables ]

method get_feeds_list [line 614]

FeedsList get_feeds_list( )
Computes the list of the feeds corresponding to each category of the category tree.

Tags:

  • return: The list.
[ Top ] - [ Class Details ] - [ Methods ] - [ Variables ]

method move [line 171]

bool move( int $id, string $way)
Moves a category (makes it gone up or down)

Tags:

  • return: true whether the category could be moved, false otherwise. If it's false, you will be able to know what was the error by using check_error method. The error will be:
    • CATEGORY_DOES_NOT_EXIST when the category to move doesn't exist
    • ERROR_CAT_IS_AT_BOTTOM when you want to move down a category whereas it's already at the bottom of the parent category
    • ERROR_CAT_IS_AT_TOP when you want to move up a categoty whereas it's already at the top of the parent category
    • ERROR_UNKNOWN_MOTION if the motion you asked is neither MOVE_CATEGORY_UP nor MOVE_CATEGORY_DOWN

Parameters:

int   $id   Id of the category to move
string   $way   The way according to which the category has to be moved. It must be either MOVE_CATEGORY_UP or MOVE_CATEGORY_DOWN.
[ Top ] - [ Class Details ] - [ Methods ] - [ Variables ]

method move_into_another [line 248]

bool move_into_another( int $id, int $new_id_cat, [int $position = 0])
Moves a category into another category. You can specify its future position in its future parent category.

Tags:

  • return: true if the category has been moved successfully, false otherwise, in this case you will be able to know the error by using the check_error method. The errors can be
    • NEW_CATEGORY_IS_IN_ITS_CHILDRENS if you tried to move the category into one of its children. It's not possible because the structure won't be anymore a tree.
    • NEW_PARENT_CATEGORY_DOES_NOT_EXIST when the category in which you want it to be moved doesn't exist.
    • CATEGORY_DOES_NOT_EXIST when the category you want to move doesn't exist

Parameters:

int   $id   Id of the category to move
int   $new_id_cat   Id of the parent category in which the category will be moved.
int   $position   Position (number) that the category has to take in its new parent category. If not specified, it will be placed at the end of the category.
[ Top ] - [ Class Details ] - [ Methods ] - [ Variables ]

method set_display_config [line 387]

unknown_type set_display_config( $config $config)
Method which sets the displaying configuration Config example $config = array( 'xmlhttprequest_file' => 'xmlhttprequest.php', 'administration_file_name' => 'admin_news_cats.php', 'url' => array( 'unrewrited' => PATH_TO_ROOT . '/news/news.php?id=%d', 'rewrited' => PATH_TO_ROOT . '/news-%d+%s.php' ), );

Parameters:

$config   $config  
[ Top ] - [ Class Details ] - [ Methods ] - [ Variables ]


Class Variables

[line 853]   string  $cache_file_name  =  ''

Tags:

    [ Top ] - [ Class Details ] - [ Methods ] - [ Variables ]
    [line 868]   mixed[]  $cache_var  = array()

    Tags:

      [ Top ] - [ Class Details ] - [ Methods ] - [ Variables ]
      [line 863]   mixed[]  $display_config  = array()

      Tags:

        [ Top ] - [ Class Details ] - [ Methods ] - [ Variables ]
        [line 858]   int  $errors  =  0

        Tags:

          [ Top ] - [ Class Details ] - [ Methods ] - [ Variables ]
          [line 848]   string  $table  =  ''

          Tags:

            [ Top ] - [ Class Details ] - [ Methods ] - [ Variables ]
            Documentation generated on Tue, 28 Jul 2009 22:43:35 +0200 by phpDocumentor 1.4.1