* // Calls the hook 'after_save_item' with the arguments '$item' and '$arg2'
* fire_plugin_hook('after_save_item', array('item' => $item, 'foo' => $arg2));
@@ -191,7 +191,7 @@ function fire_plugin_hook($name, array $args = array())
/**
* Get the output of fire_plugin_hook() as a string.
- *
+ *
* @package Omeka\Function\Plugin
* @uses fire_plugin_hook()
* @param string $name The hook name.
@@ -215,8 +215,8 @@ function get_plugin_hook_output($name, array $args = array())
*
* @package Omeka\Function\Plugin
* @uses Omeka_Plugin_Broker::getHook()
- * @param string $pluginName
- * @param string $hookName
+ * @param string $pluginName Directory name of the plugin to execute the hook for.
+ * @param string $hookName Name of the hook to fire.
* @param mixed $args Any arguments to be passed to the hook implementation.
* @return string|null
*/
@@ -227,16 +227,16 @@ function get_specific_plugin_hook_output()
// Get the plugin name (1st arg) and hook name (2nd arg).
$pluginName = array_shift($args);
$hookName = array_shift($args);
-
+
// Get the specific hook.
$pluginBroker = get_plugin_broker();
$hookNameSpecific = $pluginBroker->getHook($pluginName, $hookName);
-
+
// Return null if the specific hook doesn't exist.
if (!$hookNameSpecific) {
return null;
}
-
+
// Buffer and return any output originating from the hook.
ob_start();
foreach ($hookNameSpecific as $cb) {
@@ -281,7 +281,7 @@ function get_plugin_ini($pluginDirName, $iniKeyName)
}
/**
- * Declare a callback to display files with a given MIME type and/or file extension.
+ * Add a callback for displaying files with a given mimetype and/or extension.
*
* @package Omeka\Function\Plugin
* @uses Omeka_View_Helper_FileMarkup::addMimeTypes() See for info on usage.
@@ -328,7 +328,7 @@ function apply_filters($name, $value, array $args = array())
if ($pluginBroker = get_plugin_broker()) {
return $pluginBroker->applyFilters($name, $value, $args);
}
- // If the plugin broker is not enabled for this request (possibly for
+ // If the plugin broker is not enabled for this request (possibly for
// testing), return the original value.
return $value;
}
@@ -354,8 +354,8 @@ function add_filter($name, $callback, $priority = 10)
*
* @package Omeka\Function\Plugin
* @uses Omeka_Plugin_Broker::clearFilters()
- * @param string|null $name The name of the filter to clear. If null or omitted,
- * all filters will be cleared.
+ * @param string|null $name The name of the filter to clear. If null or omitted,
+ * all filters will be cleared.
*/
function clear_filters($filterName = null)
{
@@ -396,14 +396,14 @@ function is_admin_theme()
/**
* Get all record types that may be indexed and searchable.
- *
- * Plugins may add record types via the "search_record_types" filter. The
- * keys should be the record's class name and the respective values should
+ *
+ * Plugins may add record types via the "search_record_types" filter. The
+ * keys should be the record's class name and the respective values should
* be the human readable and internationalized version of the record type.
- *
- * These record classes must extend Omeka_Record_AbstractRecord and
+ *
+ * These record classes must extend Omeka_Record_AbstractRecord and
* implement this search mixin (Mixin_Search).
- *
+ *
* @package Omeka\Function\Search
* @see Mixin_Search
* @return array
@@ -411,9 +411,9 @@ function is_admin_theme()
function get_search_record_types()
{
$searchRecordTypes = array(
- 'Item' => __('Item'),
- 'File' => __('File'),
- 'Collection' => __('Collection'),
+ 'Item' => __('Item'),
+ 'File' => __('File'),
+ 'Collection' => __('Collection'),
);
$searchRecordTypes = apply_filters('search_record_types', $searchRecordTypes);
return $searchRecordTypes;
@@ -421,7 +421,7 @@ function get_search_record_types()
/**
* Get all record types that have been customized to be searchable.
- *
+ *
* @package Omeka\Function\Search
* @uses get_search_record_types()
* @return array
@@ -433,7 +433,7 @@ function get_custom_search_record_types()
if (!is_array($customSearchRecordTypes)) {
$customSearchRecordTypes = array();
}
-
+
// Compare the custom list to the full list.
$searchRecordTypes = get_search_record_types();
foreach ($searchRecordTypes as $key => $value) {
@@ -442,21 +442,21 @@ function get_custom_search_record_types()
unset($searchRecordTypes[$key]);
}
}
-
+
return $searchRecordTypes;
}
/**
* Get all available search query types.
- *
- * Plugins may add query types via the "search_query_types" filter. The keys
- * should be the type's GET query value and the respective values should be the
+ *
+ * Plugins may add query types via the "search_query_types" filter. The keys
+ * should be the type's GET query value and the respective values should be the
* human readable and internationalized version of the query type.
- *
- * Plugins that add a query type must modify the select object via the
- * "search_sql" hook to account for whatever custom search strategy they
+ *
+ * Plugins that add a query type must modify the select object via the
+ * "search_sql" hook to account for whatever custom search strategy they
* implement.
- *
+ *
* @package Omeka\Function\Search
* @see Table_SearchText::applySearchFilters()
* @return array
@@ -468,11 +468,11 @@ function get_search_query_types()
if ($searchQueryTypes) {
return $searchQueryTypes;
}
-
+
$searchQueryTypes = array(
- 'keyword' => __('Keyword'),
- 'boolean' => __('Boolean'),
- 'exact_match' => __('Exact match'),
+ 'keyword' => __('Keyword'),
+ 'boolean' => __('Boolean'),
+ 'exact_match' => __('Exact match'),
);
$searchQueryTypes = apply_filters('search_query_types', $searchQueryTypes);
return $searchQueryTypes;
@@ -483,59 +483,56 @@ function get_search_query_types()
*
* @package Omeka\Function\Db\Item
* @uses Builder_Item
- * @param array $metadata Set of metadata options for configuring the item.
- * Array which can include the following properties:
- *
- * - 'public' (boolean)
- * - 'featured' (boolean)
- * - 'collection_id' (integer)
- * - 'item_type_id' (integer)
- * - 'item_type_name' (string)
- * - 'tags' (string, comma-delimited)
- * - 'overwriteElementTexts' (boolean) -- determines whether or not to
- * overwrite existing element texts. If true, this will loop through the
- * element texts provided in $elementTexts, and it will update existing records
- * where possible. All texts that are not yet in the DB will be added in the
- * usual manner. False by default.
- *
+ * @param array $metadata Set of metadata options for configuring the item.
+ * The array can include the following properties:
+ * - 'public' (boolean)
+ * - 'featured' (boolean)
+ * - 'collection_id' (integer)
+ * - 'item_type_id' (integer)
+ * - 'item_type_name' (string)
+ * - 'tags' (string, comma-delimited)
+ * - 'overwriteElementTexts' (boolean) -- determines whether or not to
+ * overwrite existing element texts. If true, this will loop through the
+ * element texts provided in $elementTexts, and it will update existing records
+ * where possible. All texts that are not yet in the DB will be added in the
+ * usual manner. False by default.
+ *
* @param array $elementTexts Array of element texts to assign to the item.
- * This follows the format:
- *
- * array(
- * [element set name] => array(
- * [element name] => array(
- * array('text' => [string], 'html' => [false|true]),
- * array('text' => [string], 'html' => [false|true])
+ * This follows the following format::
+ * array(
+ * [element set name] => array(
+ * [element name] => array(
+ * array('text' => [string], 'html' => [false|true]),
+ * array('text' => [string], 'html' => [false|true])
+ * ),
+ * [element name] => array(
+ * array('text' => [string], 'html' => [false|true]),
+ * array('text' => [string], 'html' => [false|true])
+ * )
* ),
- * [element name] => array(
- * array('text' => [string], 'html' => [false|true]),
- * array('text' => [string], 'html' => [false|true])
- * )
- * ),
- * [element set name] => array(
- * [element name] => array(
- * array('text' => [string], 'html' => [false|true]),
- * array('text' => [string], 'html' => [false|true])
- * ),
- * [element name] => array(
- * array('text' => [string], 'html' => [false|true]),
- * array('text' => [string], 'html' => [false|true])
- * )
- * )
- * );
- *
- * @param array $fileMetadata Set of metadata options that allow one or more
- * files to be associated with the item. Includes the following options:
- *
- * - 'file_transfer_type' (string = 'Url|Filesystem|Upload' or
- * Omeka_File_Transfer_Adapter_Interface). Corresponds to the $transferStrategy
- * argument for addFiles().
- * - 'file_ingest_options' OPTIONAL (array of possible options to pass
- * modify the behavior of the ingest script). Corresponds to the $options
- * argument for addFiles().
- * - 'files' (array or string) Represents information indicating the file to
- * ingest. Corresponds to the $files argument for addFiles().
- *
+ * [element set name] => array(
+ * [element name] => array(
+ * array('text' => [string], 'html' => [false|true]),
+ * array('text' => [string], 'html' => [false|true])
+ * ),
+ * [element name] => array(
+ * array('text' => [string], 'html' => [false|true]),
+ * array('text' => [string], 'html' => [false|true])
+ * )
+ * )
+ * );
+ *
+ * @param array $fileMetadata Settings and data used to ingest files into Omeka
+ * and add them to this item. Includes the following options:
+ * - 'file_transfer_type' (string = 'Url|Filesystem|Upload' or
+ * Omeka_File_Transfer_Adapter_Interface). Corresponds to the $transferStrategy
+ * argument for addFiles().
+ * - 'file_ingest_options' (array) Optional array of options to
+ * modify the behavior of the ingest. Corresponds to the $options
+ * argument for addFiles().
+ * - 'files' (array or string) Represents information indicating the file to
+ * ingest. Corresponds to the $files argument for addFiles().
+ *
* @return Item
*/
function insert_item($metadata = array(), $elementTexts = array(), $fileMetadata = array())
@@ -552,16 +549,21 @@ function insert_item($metadata = array(), $elementTexts = array(), $fileMetadata
*
* @package Omeka\Function\Db\Item
* @uses Builder_Item::addFiles()
- * @param Item|integer $item
- * @param string|Omeka_File_Ingest_AbstractIngest $transferStrategy
- * @param array $files
- * @param array $options Available Options:
- *
- * - 'ignore_invalid_files': boolean false by default. Determine
- * whether or not to throw exceptions when a file is not valid.
- *
- *
- * @return array
+ * @param Item|integer $item Item record or ID of item to add files to
+ * @param string|Omeka_File_Ingest_AbstractIngest $transferStrategy Strategy
+ * to use when ingesting the file. The strings 'Url', 'Filesystem' and 'Upload'
+ * correspond to those built-in strategies. Alternatively a strategy object
+ * can be passed.
+ * @param array $files Information about the file(s) to ingest. See addFiles()
+ * for details
+ * @param array $options Array of options to
+ * modify the behavior of the ingest. Available options include:
+ * - 'ignore_invalid_files': boolean, false by default. Whether or not to
+ * throw exceptions when a file is not valid.
+ * - 'ignoreNoFile': (for Upload only) boolean, false by default. Whether to
+ * ignore validation errors that occur when an uploaded file is missing, like
+ * when a file input is left empty on a form.
+ * @return array The added File records.
*/
function insert_files_for_item($item, $transferStrategy, $files, $options = array())
{
@@ -578,8 +580,8 @@ function insert_files_for_item($item, $transferStrategy, $files, $options = arra
* @uses Builder_Item
* @param Item|int $item Either an Item object or the ID for the item.
* @param array $metadata Set of options that can be passed to the item.
- * @param array $elementTexts
- * @param array $fileMetadata
+ * @param array $elementTexts Element texts to assign. See insert_item() for details.
+ * @param array $fileMetadata File ingest data. See insert_item() for details.
* @return Item
*/
function update_item($item, $metadata = array(), $elementTexts = array(), $fileMetadata = array())
@@ -600,7 +602,7 @@ function update_item($item, $metadata = array(), $elementTexts = array(), $fileM
* @uses Builder_Collection
* @param Collection|int $collection Either an Collection object or the ID for the collection.
* @param array $metadata Set of options that can be passed to the collection.
- * @param array $elementTexts The element texts for the collection
+ * @param array $elementTexts The element texts for the collection.
* @return Collection
*/
function update_collection($collection, $metadata = array(), $elementTexts = array())
@@ -624,7 +626,7 @@ function update_collection($collection, $metadata = array(), $elementTexts = arr
* 'description' => [string]
* );
*
- * @param array $elementInfos An array containing element data. Each entry
+ * @param array $elementInfos An array containing element data. Each entry
* follows one or more of the following formats:
* tag. If no paragraphs are found, then the @@ -2788,7 +2824,7 @@ function xml_escape($value) */ function text_to_paragraphs($str) { - return str_replace('
', '', '' + return str_replace('
', '', '' . preg_replace('#([\r\n]\s*?[\r\n]){2,}#', '
$0', $str) . '
'); } @@ -2809,9 +2845,9 @@ function snippet($text, $startPos, $endPos, $append = '…') { // strip html tags from the text $text = strip_formatting($text); - + $textLength = strlen($text); - + // Calculate the start position. Set to zero if the start position is // null or 0, OR if the start offset is greater than the length of the // original text. @@ -2819,7 +2855,7 @@ function snippet($text, $startPos, $endPos, $append = '…') $startPos = !$startPos || $startPosOffset > $textLength ? 0 : strrpos($text, ' ', $startPosOffset); - + // Calculate the end position. Set to the length of the text if the // end position is greater than or equal to the length of the original // text, OR if the end offset is greater than the length of the @@ -2828,10 +2864,10 @@ function snippet($text, $startPos, $endPos, $append = '…') $endPos = $endPos >= $textLength || $endPosOffset > $textLength ? $textLength : strrpos($text, ' ', $endPosOffset); - + // Set the snippet by getting its substring. $snippet = substr($text, $startPos, $endPos - $startPos); - + // Return the snippet without the append string if the text's original // length equals to 1) the length of the snippet, i.e. when the return // string is identical to the passed string; OR 2) the calculated @@ -2844,7 +2880,7 @@ function snippet($text, $startPos, $endPos, $append = '…') /** * Return a substring of the text by limiting the word count. - * + * * Note: it strips the HTML tags from the text before getting the snippet * * @package Omeka\Function\Text @@ -2869,7 +2905,7 @@ function snippet_by_word_count($text, $maxWords = 20, $ellipsis = '...') } /** - * Strip HTML formatting (i.e. tags) from the provided string. + * Strip HTML tags from a string. * * This is essentially a wrapper around PHP's strip_tags() function, with the * added benefit of returning a fallback string in case the resulting stripped @@ -2897,17 +2933,13 @@ function strip_formatting($str, $allowableTags = '', $fallbackStr = '') } /** - * Convert a word or phrase to dashed format, i.e. Foo Bar => foo-bar. + * Convert a word or phrase to a valid HTML ID. * - * This is primarily for easy creation of HTML ids within Omeka + * For example: 'Foo Bar' becomes 'foo-bar'. * - *' . __('No tags are available.') . '
'; } - + //Get the largest value in the tags array $largest = 0; foreach ($tags as $tag) { @@ -3002,11 +3034,11 @@ function tag_cloud($recordOrTags = null, $link = null, $maxClasses = 9, $tagNumb } $html = '
- * is_allowed('Items', 'showNotPublic');
- *
- * Will check if the user has permission to view Items that are not public.
+ * Check whether the current user has a give permission.
*
* @package Omeka\Function\User
* @uses Zend_Acl::is_allowed()
- * @param string|Zend_Acl_Resource_Interface $resource
- * @param string|null $privilege
+ * @param string|Zend_Acl_Resource_Interface $resource The name of a resource,
+ * or a record implementing Zend_Acl_Resource_Interface
+ * @param string|null $privilege The privilege to check for the resource.
* @return boolean
*/
function is_allowed($resource, $privilege)
@@ -3403,8 +3427,9 @@ function is_allowed($resource, $privilege)
}
/**
- * Add a shortcode
+ * Add a shortcode.
*
+ * @package Omeka\Function\View
* @uses Omeka_View_Helper_Shortcodes::shortcodeCallbacks()
* @param string $shortcodeName Name of the new shortcode.
* @param callback $function Callback to execute for this shortcode.