From b5dcc4da46f27341f54e50449626d18048cd99a6 Mon Sep 17 00:00:00 2001 From: John Flatness Date: Tue, 4 Jun 2019 17:37:45 -0400 Subject: [PATCH] Add docs for new 2.7 filters --- source/Reference/filters/file_markup.rst | 6 +- .../Reference/filters/file_markup_files.rst | 30 ++++++++++ .../Reference/filters/file_markup_options.rst | 54 +++++++++++++++++ source/Reference/filters/files_for_item.rst | 43 +++++++++++++ .../filters/html_purifier_config_setup.rst | 60 +++++++++++++++++++ .../filters/image_tag_attributes.rst | 39 ++++++++++++ source/Reference/filters/index.rst | 30 ++++++---- 7 files changed, 249 insertions(+), 13 deletions(-) create mode 100644 source/Reference/filters/file_markup_files.rst create mode 100644 source/Reference/filters/file_markup_options.rst create mode 100644 source/Reference/filters/files_for_item.rst create mode 100644 source/Reference/filters/html_purifier_config_setup.rst create mode 100644 source/Reference/filters/image_tag_attributes.rst diff --git a/source/Reference/filters/file_markup.rst b/source/Reference/filters/file_markup.rst index f501a0e7..a6714fa4 100644 --- a/source/Reference/filters/file_markup.rst +++ b/source/Reference/filters/file_markup.rst @@ -32,4 +32,8 @@ Arguments ``string`` wrapper_attributes Attributes to apply to the wrapping ``
`` element - \ No newline at end of file +******** +See Also +******** + +:php:func:`file_markup`, the function diff --git a/source/Reference/filters/file_markup_files.rst b/source/Reference/filters/file_markup_files.rst new file mode 100644 index 00000000..cbf943c9 --- /dev/null +++ b/source/Reference/filters/file_markup_files.rst @@ -0,0 +1,30 @@ +################# +file_markup_files +################# + +.. versionadded:: 2.7 + +***** +Usage +***** + +Filter the set of files to be displayed by :php:func:`file_markup` + +Omeka uses functions like :php:func:`files_for_item` to render all +the files attached to an item; this filter allows a developer +to alter that list, for example to exclude some files from being +displayed. + +***** +Value +***** + +``array`` $files + Array of :php:class:`File` objects to be displayed + +********* +Arguments +********* + +``array`` options + Options passed to ``file_markup`` diff --git a/source/Reference/filters/file_markup_options.rst b/source/Reference/filters/file_markup_options.rst new file mode 100644 index 00000000..e9632236 --- /dev/null +++ b/source/Reference/filters/file_markup_options.rst @@ -0,0 +1,54 @@ +################### +file_markup_options +################### + +.. versionadded:: 2.7 + +***** +Usage +***** + +Modify the options passed to :php:func:`file_markup` + +Unlike the :doc:`file_markup` filter, this filter allows you to change +options that Omeka uses when rendering HTML for a file, meaning you can +alter the output without having to write completely new markup yourself. + +***** +Value +***** + +``array`` $options + Array of options for ``file_markup`` + +********* +Arguments +********* + +:php:class:`File` file + The file object + +******** +Examples +******** + +Add ``target="_blank"`` to all links to original files: + +.. code-block:: php + + class MyPlugin extends :php:class:`Omeka_Plugin_AbstractPlugin` + { + protected $_filters = array('file_markup_options'); + + public filterHtmlPurifierConfigSetup($options, $args) + { + $options['linkAttributes']['target'] = '_blank'; + return $options; + } + } + +******** +See Also +******** + +:php:func:`file_markup` documentation for a list of possible options diff --git a/source/Reference/filters/files_for_item.rst b/source/Reference/filters/files_for_item.rst new file mode 100644 index 00000000..9483d42b --- /dev/null +++ b/source/Reference/filters/files_for_item.rst @@ -0,0 +1,43 @@ +############## +files_for_item +############## + +.. versionadded:: 2.7 + +***** +Usage +***** + +Filter the HTML for displaying all files for an item. + +The :doc:`file_markup` filter is used to modify the HTML markup for +displaying a single file, but this filter can be used to modify the +markup for all the files being displayed as a whole (for example, to +add markup that comes before or after, or wraps around, all the +displayed files). + +***** +Value +***** + +``string`` $html + The HTML for displaying the files + +********* +Arguments +********* + +:php:class:`Item` item + The item object + +``array`` options + Options to pass to the callback + +``string`` wrapperAttributes + Attributes to apply to the wrapping ``
`` element + +******** +See Also +******** + +:php:func:`files_for_item` diff --git a/source/Reference/filters/html_purifier_config_setup.rst b/source/Reference/filters/html_purifier_config_setup.rst new file mode 100644 index 00000000..52119b95 --- /dev/null +++ b/source/Reference/filters/html_purifier_config_setup.rst @@ -0,0 +1,60 @@ +########################## +html_purifier_config_setup +########################## + +.. versionadded:: 2.7 + +***** +Usage +***** + +Alters the configuration settings for the HTMLPurifier library. + +***** +Value +***** + +``HTMLPurifier_Config`` $purifierConfig + The config object for HTMLPurifier + +********* +Arguments +********* + +``array`` defaults + The default configuration keys (these have already been set to the passed config object) +``array`` allowedHtmlElements + List of user-configured enabled elements +``array`` allowedHtmlAttributes + List of user-configured enabled attributes + +******** +Examples +******** + +Force a prefix on all user-provided ``id`` attributes (for other options see the HTMLPurifier +documentation pages linked below: + +.. code-block:: php + + class MyPlugin extends :php:class:`Omeka_Plugin_AbstractPlugin` + { + protected $_filters = array('html_purifier_config_setup'); + + public filterHtmlPurifierConfigSetup($purifierConfig, $args) + { + $purifierConfig->set('Attr.IDPrefix', 'foo_'); + return $purifierConfig; + } + } + + +******** +See Also +******** + +- `HTMLPurifier customization documentation `_ + +- `HTMLPurifier list of configuration options `_ + + diff --git a/source/Reference/filters/image_tag_attributes.rst b/source/Reference/filters/image_tag_attributes.rst new file mode 100644 index 00000000..899162c9 --- /dev/null +++ b/source/Reference/filters/image_tag_attributes.rst @@ -0,0 +1,39 @@ +#################### +image_tag_attributes +#################### + +.. versionadded:: 2.7 + +***** +Usage +***** + +Filter the HTML attributes used for an record's image. + +This filter affects ```` tags created by :php:func:`file_markup`, :php:func:`files_for_item`, +:php:func:`record_image`, :php:func:`item_image`, and :php:func:`file_image` (essentially meaning +it covers anywhere derivative images are used for a record). + +***** +Value +***** + +``array`` $attrs + Array of HTML attributes for the ```` tag. + +********* +Arguments +********* + +:php:class:`Omeka_Record` record + The record being displayed (could be an Item or Collection in the case of a thumbnail) + +:php:class:`File` file + The file being displayed. This is always the File that directly corresponds with the + image, while ``record`` can be another record like an Item, Collection or Exhibit + that simply uses the File as its representative image. + +``string`` format + Type of derivative image being displayed (e.g., ``'thumbnail'``, ``'fullsize'``, ``'square_thumbnail'``) + + diff --git a/source/Reference/filters/index.rst b/source/Reference/filters/index.rst index 12ae70a0..8deb0e0a 100644 --- a/source/Reference/filters/index.rst +++ b/source/Reference/filters/index.rst @@ -30,7 +30,20 @@ Database :maxdepth: 1 file_ingest_validators + + +********************** +File and Image Display +********************** + +.. toctree:: + :maxdepth: 1 + file_markup + file_markup_files + file_markup_options + files_for_item + image_tag_attributes ******* Records @@ -40,7 +53,10 @@ Records :glob: :maxdepth: 1 - _* + s_browse_default_sort + s_browse_params + s_browse_per_page + s_select_options Record Metadata @@ -51,8 +67,6 @@ Record Metadata :maxdepth: 1 Element_* - record_metadata_elements - ****** @@ -83,14 +97,6 @@ Text Views ***** -.. toctree:: - :glob: - :maxdepth: 1 - - define* - - - Admin Views =========== @@ -100,7 +106,6 @@ Admin Views admin* - Forms ===== @@ -119,5 +124,6 @@ Public Views :maxdepth: 1 body_tag_attributes + public*