From 4d008fefd2882a51309b5c6a7c3c7775fb34270d Mon Sep 17 00:00:00 2001 From: brettp Date: Wed, 15 Sep 2010 15:34:50 +0000 Subject: Refs #2450: Added documentation to elgglib. git-svn-id: http://code.elgg.org/elgg/trunk@6932 36083f99-b078-4883-b0ff-0f9b5a30f544 --- engine/lib/elgglib.php | 759 +++++++++++++++++++++++++++++++++++-------------- 1 file changed, 540 insertions(+), 219 deletions(-) (limited to 'engine/lib/elgglib.php') diff --git a/engine/lib/elgglib.php b/engine/lib/elgglib.php index d4aa37a53..47d05327e 100644 --- a/engine/lib/elgglib.php +++ b/engine/lib/elgglib.php @@ -1,25 +1,22 @@ url . $location; } // return new forward location or false to stop the forward or empty string to exit + $current_page = current_page_url(); $params = array('current_url' => $current_page, 'forward_url' => $location); $location = trigger_plugin_hook('forward', 'system', $params, $location); + if ($location) { header("Location: {$location}"); exit; @@ -47,7 +45,13 @@ } /** - * Return the current page URL. + * Returns the current page's complete URL. + * + * The current URL is assembled using the network's wwwroot and the request URI + * in $_SERVER as populated by the web server. This function will include + * any schemes, usernames and passwords, and ports. + * + * @return string The current page URL. */ function current_page_url() { global $CONFIG; @@ -74,7 +78,6 @@ function current_page_url() { $page .= ":" . $url['port']; } - //$page.="/"; $page = trim($page, "/"); $page .= $_SERVER['REQUEST_URI']; @@ -83,22 +86,33 @@ function current_page_url() { } /** - * This is a factory function which produces an ElggCache object suitable for caching file load paths. + * Returns an ElggCache object suitable for caching view + * file load paths to disk under $CONFIG->dataroot. * * @todo Can this be done in a cleaner way? * @todo Swap to memcache etc? + * + * @return ElggFileCache A cache object suitable for caching file load paths. */ function elgg_get_filepath_cache() { global $CONFIG; + + /** + * A default filestore cache using the dataroot. + */ static $FILE_PATH_CACHE; - if (!$FILE_PATH_CACHE) $FILE_PATH_CACHE = new ElggFileCache($CONFIG->dataroot); + + if (!$FILE_PATH_CACHE) { + $FILE_PATH_CACHE = new ElggFileCache($CONFIG->dataroot); + } return $FILE_PATH_CACHE; } /** - * Function which resets the file path cache. + * Deletes the view file paths cache from disk. * + * @return bool On success */ function elgg_filepath_cache_reset() { $cache = elgg_get_filepath_cache(); @@ -106,9 +120,11 @@ function elgg_filepath_cache_reset() { } /** - * Saves a filepath cache. + * Saves $data to the views file paths disk cache as + * 'view_paths'. * - * @param mixed $data + * @param mixed $data The data + * @return bool On success */ function elgg_filepath_cache_save($data) { global $CONFIG; @@ -122,8 +138,9 @@ function elgg_filepath_cache_save($data) { } /** - * Retrieve the contents of the filepath cache. + * Returns the contents of the views file paths cache from disk. * + * @return mixed Null if simplecache isn't enabled, the contents of the views file paths cache if it is. */ function elgg_filepath_cache_load() { global $CONFIG; @@ -141,25 +158,33 @@ function elgg_filepath_cache_load() { } /** - * Enable the filepath cache. + * Enables the views file paths disk cache. * + * Uses the 'viewpath_cache_enabled' datalist with a boolean value. + * Resets the views paths cache. + * + * @return null */ function elgg_enable_filepath_cache() { global $CONFIG; - datalist_set('viewpath_cache_enabled',1); + datalist_set('viewpath_cache_enabled', 1); $CONFIG->viewpath_cache_enabled = 1; elgg_filepath_cache_reset(); } /** - * Disable filepath cache. + * Disables the views file paths disk cache. + * + * Uses the 'viewpath_cache_enabled' datalist with a boolean value. + * Resets the views paths cache. * + * @return null */ function elgg_disable_filepath_cache() { global $CONFIG; - datalist_set('viewpath_cache_enabled',0); + datalist_set('viewpath_cache_enabled', 0); $CONFIG->viewpath_cache_enabled = 0; elgg_filepath_cache_reset(); } @@ -203,7 +228,9 @@ function add_submenu_item($label, $link, $group = 'default', $onclick = false, $ /** * Add an entry to the submenu. * - * @param array $item The item as array( + * @param array $item The item as: + * + * array( * 'title' => 'Text to display', * 'url' => 'URL of the link', * 'id' => 'entry_unique_id' //used by children items to identify parents @@ -211,11 +238,13 @@ function add_submenu_item($label, $link, $group = 'default', $onclick = false, $ * 'selected' => BOOL // Is this item selected? (If NULL or unset will attempt to guess) * 'vars' => array() // Array of vars to pass to the navigation/submenu_item view * ) + * * * @param string $context Context in which to display this menu item. 'all' will make it show up all the time. Use sparingly. * @param string $group Group for the item. Each submenu group has its own