## /forums.php

Description

This script implements the Phorum forum admin API.

This API is used for managing Phorum forums and folders. It can be used to retrieve information about the available forums and folders and takes care of creating and editing them.

This API combines forums and folders into one API script, because at the data level, they are the same kind of entity. Folders are also forums, only they act differently based on the "folder_flag" field. Therefore, folders are also identified by a forum_id.

- license: Phorum
- copyright: 2007, Phorum Development Team

Functions
phorum_api_forums_build_path (line 392)

This function can be used for building the folder paths that lead up to forums/folders.

The function is internally used by Phorum to build the paths that are stored in the "forum_path" field of the forums table. If you need access to the path for a folder or forum, then do not call this function for retrieving that info, but look at the "forum_path" field instead.

- return:

  If the $forum_id parameter is a single forum_id, then a single path is returned. If it is NULL, then an array or paths is returned, indexed by the forum_id for which the path was built. Each path is an array, containing the nodes in the path (key = forum_id, value = name). The first element in a path array will be the (v)root and the last element the forum or folder for which the path was built.

  Note: the root node (forum_id = 0) will also be returned in the data when using NULL or 0 as the $forum_id argument. This is however a generated node for which no database record exists. So if you are using this functions return data for updating folders in the database, then beware to skip the forum_id = 0 root node.

array phorum_api_forums_build_path ([mixed $forum_id = NULL], mixed $forum_id )

- mixed $forum_id : If $forum_id is NULL, then the paths for all available forums and folders will be built. Otherwise, only the path for the requested forum_id is built.

phorum_api_forums_by_folder (line 478)

Retrieve data for all direct descendant forums and folders within a folder.

- return: An array of forums, index by the their forum_id and sorted by their display order.

array phorum_api_forums_by_folder ([mixed $folder_id = 0], integer $folder_id )

- integer $folder_id : The forum_id of the folder for which to retrieve the forums.

phorum_api_forums_by_inheritance (line 512)

Retrieve data for all forums inheriting their settings from a certain forum.

- return: An array of forums, index by the their forum_id and sorted by their display order.

array phorum_api_forums_by_inheritance ([mixed $forum_id = 0], integer $forum_id )

- integer $forum_id : The forum_id for which to check what forums inherit its setting.

phorum_api_forums_by_vroot (line 495)

Retrieve data for all forums and folders that belong to a certain vroot.

- return: An array of forums, index by the their forum_id and sorted by their display order.

array phorum_api_forums_by_vroot ([mixed $vroot_id = 0], integer $vroot_id )

- integer $vroot_id : The forum_id of the vroot for which to retrieve the forums.

phorum_api_forums_change_order (line 222)

Change the displaying order for forums and folders in a certain folder.

void phorum_api_forums_change_order (mixed $folder_id, mixed $forum_id, mixed $movement, [mixed $value = NULL], integer $folder_id , integer $forum_id , string $movement , mixed $value )

- integer $folder_id : The forum_id of the folder in which to change the display order.
- integer $forum_id : The id of the forum or folder to move.
- string $movement : This field determines the type of movement to apply to the forum or folder. This can be one of:
  - "up": Move the forum or folder $value positions up
  - "down": Move the forum or folder $value permissions down
  - "pos": Move the forum or folder to position $value
  - "start": Move the forum or folder to the start of the list
  - "end": Move the forum or folder to the end of the list
- mixed $value : This field specifies a value for the requested type of movement. An integer value is only needed for movements "up", "down" and "pos". For other movements, this parameter can be omitted.

phorum_api_forums_folder_save (line 330)

Create or update a folder.

This function can be used for both creating and updating Phorum folders. If no forum_id is provided in the folder data, a new folder will be created. If a forum_id is provided, then the existing folder will be updated or a new folder with that forum_id is created.

- return: The forum_id of the folder. For new folderss, the newly assigned folder_id will be returned.

array phorum_api_forums_folder_save (mixed $folder, array $folder )

- array $folder : An array containing folder data. This array should at least contain a field "folder_id". This field can be NULL to create a new folder with an automatically assigned folder_id. It can also be set to a folder_id to either update an existing folder or to create a new folder with the provided folder_id. Other fields in the folder data are:
  - name: the name to assign to the folder. Phorum will not escape HTML code in this name, so formatting the title using HTML is allowed.
  - description: the description for the folder. Phorum will not escape HTML code in this name, so formatting the description using HTML is allowed.
  - parent_id: The folder_id of the parent folder.
  - active: Whether the folder is active/visible (1) or not (0).
  - template: The name of the template to use for the folder.
  - language: The name of the language to use for the folder.
  - vroot: Whether the folder is a vroot (1) or not (0).

phorum_api_forums_get (line 144)

Retrieve the data for forums and/or folders in various ways.

- return: If the $forum_ids parameter is used and if it contains a single forum_id, then a single array containg forum data is returned or NULL if the forum was not found. For all other cases, an array of forum data arrays is returned, indexed by the forum_id and sorted by their display order. If the $forum_ids parameter is an array containing non-existant forum_ids, then the return array will have no entry available in the returned array.

mixed phorum_api_forums_get ([mixed $forum_ids = NULL], [mixed $parent_id = NULL], [mixed $vroot = NULL], [mixed $inherit_id = NULL], mixed $forum_ids , mixed $parent_id , mixed $vroot , mixed $inherit_id )

- mixed $forum_ids : A single forum_id or an array of forum_ids for which to retrieve the forum data. If this parameter is NULL, then the $parent_id parameter will be checked.
- mixed $parent_id : Retrieve the forum data for all forums that have their parent_id set to $parent_id. If this parameter is NULL, then the $vroot parameter will be checked.
- mixed $vroot : Retrieve the forum data for all forums that are in the given $vroot. If this parameter is NULL, then the $inherit_id parameter will be checked.
- mixed $inherit_id : Retrieve the forum data for all forums that inherit their settings from the forum with id $inherit_id.

Documentation generated on Thu, 29 Nov 2007 15:45:59 -0600 by phpDocumentor 1.3.0RC5