From d433ae0d8adc2e615e1f3ef6c8a8603a0c5d214d Mon Sep 17 00:00:00 2001 From: cash Date: Sun, 13 Feb 2011 18:57:47 +0000 Subject: documentation update for admin functions git-svn-id: http://code.elgg.org/elgg/trunk@8202 36083f99-b078-4883-b0ff-0f9b5a30f544 --- engine/lib/admin.php | 224 ++++++++++++++++++++++++++------------------------- 1 file changed, 115 insertions(+), 109 deletions(-) (limited to 'engine/lib/admin.php') diff --git a/engine/lib/admin.php b/engine/lib/admin.php index ea18d9e3f..2384a9278 100644 --- a/engine/lib/admin.php +++ b/engine/lib/admin.php @@ -8,29 +8,102 @@ */ /** - * Create the plugin settings submenu. + * Write a persistent message to the admin view. + * Useful to alert the admin to take a certain action. + * The id is a unique ID that can be cleared once the admin + * completes the action. * - * This is done in a separate function called from the admin - * page handler because of performance concerns. + * eg: add_admin_notice('twitter_services_no_api', + * 'Before your users can use Twitter services on this site, you must set up + * the Twitter API key in the Twitter Services Settings'); * - * @return void + * @param string $id A unique ID that your plugin can remember + * @param string $message Body of the message + * + * @return bool + * @since 1.8.0 */ -function elgg_admin_add_plugin_settings_menu() { +function elgg_add_admin_notice($id, $message) { + if ($id && $message) { + $admin_notice = new ElggObject(); + $admin_notice->subtype = 'admin_notice'; + // admins can see ACCESS_PRIVATE but no one else can. + $admin_notice->access_id = ACCESS_PRIVATE; + $admin_notice->admin_notice_id = $id; + $admin_notice->description = $message; - $active_plugins = elgg_get_plugins('active'); - if (!$active_plugins) { - // nothing added because no items - return FALSE; + return $admin_notice->save(); } - elgg_add_admin_menu_item('plugin_settings', elgg_echo('admin:plugin_settings'), null, 51); + return FALSE; +} - foreach ($active_plugins as $plugin) { - $plugin_id = $plugin->getID(); - if (elgg_view_exists("settings/$plugin_id/edit")) { - elgg_add_admin_menu_item($plugin_id, $plugin->manifest->getName(), 'plugin_settings'); + +/** + * Remove an admin notice by ID. + * + * eg In actions/twitter_service/save_settings: + * if (is_valid_twitter_api_key()) { + * delete_admin_notice('twitter_services_no_api'); + * } + * + * @param string $id The unique ID assigned in add_admin_notice() + * + * @return bool + * @since 1.8.0 + */ +function elgg_delete_admin_notice($id) { + if (!$id) { + return FALSE; + } + $result = TRUE; + $notices = elgg_get_entities_from_metadata(array( + 'metadata_name' => 'admin_notice_id', + 'metadata_value' => $id + )); + + if ($notices) { + // in case a bad plugin adds many, let it remove them all at once. + foreach ($notices as $notice) { + $result = ($result && $notice->delete()); } + return $result; } + return FALSE; +} + +/** + * List all admin messages. + * + * @param int $limit Limit + * + * @return array List of admin notices + * @since 1.8.0 + */ +function elgg_get_admin_notices($limit = 10) { + return elgg_get_entities_from_metadata(array( + 'type' => 'object', + 'subtype' => 'admin_notice', + 'limit' => $limit + )); +} + +/** + * Check if an admin notice is currently active. + * + * @param string $id The unique ID used to register the notice. + * + * @return bool + * @since 1.8.0 + */ +function elgg_admin_notice_exists($id) { + $notice = elgg_get_entities_from_metadata(array( + 'type' => 'object', + 'subtype' => 'admin_notice', + 'metadata_name_value_pair' => array('name' => 'admin_notice_id', 'value' => $id) + )); + + return ($notice) ? TRUE : FALSE; } /** @@ -152,8 +225,36 @@ function admin_init() { register_page_handler('admin_plugin_screenshot', 'admin_plugin_screenshot_page_handler'); } +/** + * Create the plugin settings submenu. + * + * This is done in a separate function called from the admin + * page handler because of performance concerns. + * + * @return void + * @access private + */ +function elgg_admin_add_plugin_settings_menu() { + + $active_plugins = elgg_get_plugins('active'); + if (!$active_plugins) { + // nothing added because no items + return FALSE; + } + + elgg_add_admin_menu_item('plugin_settings', elgg_echo('admin:plugin_settings'), null, 51); + + foreach ($active_plugins as $plugin) { + $plugin_id = $plugin->getID(); + if (elgg_view_exists("settings/$plugin_id/edit")) { + elgg_add_admin_menu_item($plugin_id, $plugin->manifest->getName(), 'plugin_settings'); + } + } +} + /** * Handles any set up required for administration pages + * @access private */ function admin_pagesetup() { if (elgg_in_context('admin')) { @@ -280,100 +381,5 @@ function admin_plugin_screenshot_page_handler($pages) { return true; } -/** - * Write a persistent message to the admin view. - * Useful to alert the admin to take a certain action. - * The id is a unique ID that can be cleared once the admin - * completes the action. - * - * eg: add_admin_notice('twitter_services_no_api', - * 'Before your users can use Twitter services on this site, you must set up - * the Twitter API key in the Twitter Services Settings'); - * - * @param string $id A unique ID that your plugin can remember - * @param string $message Body of the message - * - * @return boo - */ -function elgg_add_admin_notice($id, $message) { - if ($id && $message) { - $admin_notice = new ElggObject(); - $admin_notice->subtype = 'admin_notice'; - // admins can see ACCESS_PRIVATE but no one else can. - $admin_notice->access_id = ACCESS_PRIVATE; - $admin_notice->admin_notice_id = $id; - $admin_notice->description = $message; - - return $admin_notice->save(); - } - - return FALSE; -} - - -/** - * Remove an admin notice by ID. - * - * eg In actions/twitter_service/save_settings: - * if (is_valid_twitter_api_key()) { - * delete_admin_notice('twitter_services_no_api'); - * } - * - * @param string $id The unique ID assigned in add_admin_notice() - * - * @return bool - */ -function elgg_delete_admin_notice($id) { - if (!$id) { - return FALSE; - } - $result = TRUE; - $notices = elgg_get_entities_from_metadata(array( - 'metadata_name' => 'admin_notice_id', - 'metadata_value' => $id - )); - - if ($notices) { - // in case a bad plugin adds many, let it remove them all at once. - foreach ($notices as $notice) { - $result = ($result && $notice->delete()); - } - return $result; - } - return FALSE; -} - -/** - * List all admin messages. - * - * @param int $limit Limit - * - * @return array List of admin notices - */ -function elgg_get_admin_notices($limit = 10) { - return elgg_get_entities_from_metadata(array( - 'type' => 'object', - 'subtype' => 'admin_notice', - 'limit' => $limit - )); -} - -/** - * Check if an admin notice is currently active. - * - * @param string $id The unique ID used to register the notice. - * - * @return bool - */ -function elgg_admin_notice_exists($id) { - $notice = elgg_get_entities_from_metadata(array( - 'type' => 'object', - 'subtype' => 'admin_notice', - 'metadata_name_value_pair' => array('name' => 'admin_notice_id', 'value' => $id) - )); - - return ($notice) ? TRUE : FALSE; -} - elgg_register_event_handler('init', 'system', 'admin_init'); elgg_register_event_handler('pagesetup', 'system', 'admin_pagesetup', 1000); -- cgit v1.2.3