Skip to content

Commit

Permalink
[#2205] Document properly the IResourceView interface
Browse files Browse the repository at this point in the history
  • Loading branch information
@amercader
amercader committed Feb 12, 2015
1 parent 894efa3 commit 4cd2c31
Show file tree
Hide file tree
Showing 2 changed files with 115 additions and 45 deletions.
154 changes: 111 additions & 43 deletions ckan/plugins/interfaces.py
View file
Expand Up @@ -206,78 +206,146 @@ def notify(self, resource):


class IResourceView(Interface):
'''Add custom data view for resource file-types.
'''Add custom view renderings for different resource types.
'''
def info(self):
'''
Return configuration for the view. Info can return the following.
:param name: name of view type
:param title: title of view type (Optional)
:param schema: schema to validate extra view config (Optional)
:param icon: icon from
http://fortawesome.github.io/Font-Awesome/3.2.1/icons/
without the icon- prefix eg. compass (Optional).
:param iframed: should we iframe the view template before rendering.
If the styles or JavaScript clash with the main site theme this
should be set to true. Default is true. (Optional)
:param preview_enabled:
Says if the preview button appears for this resource. Some preview
types have their previews integrated with the form.
Some preview types have their previews integrated with the form.
Default false (Optional)
:param full_page_edit: Says if the edit form is the full page width
of the page. Default false (Optional)
eg:
Returns a dictionarty with configuration options for the view.
The available keys are:
:param name: name of the view type. This should match the name of the
actual plugin (eg ``image_view`` or ``recline_view``).
:param title: title of the view type, will be displayed on the
frontend. This should be translatable (ie wrapped on
``toolkit._('Title')``).
:param default_title: default title that will be used if the view is
created automatically (optional, defaults to 'View').
:param default_description: default description that will be used if
the view is created automatically (optional, defaults to '').
:param icon: icon for the view type. Should be one of the
`Font Awesome`_ types without the `icon-` prefix eg. `compass`
(optional, defaults to 'picture').
:param always_available: the view type should be always available when
creating new views regardless of the format of the resource
(optional, defaults to False).
:param iframed: the view template should be iframed before rendering.
You generally want this option to be True unless the view styles
and JavaScript don't clash with the main site theme (optional,
defaults to True).
:param preview_enabled: the preview button should appear on the edit
view form. Some view types have their previews integrated with the
form (optional, defaults to False).
:param full_page_edit: the edit form should take the full page width
of the page (optional, defaults to False).
:param schema: schema to validate extra configuration fields for the
view (optional). Schemas are defined as a dictionary, with the
keys being the field name and the values a list of validator
functions that will get applied to the field. For instance::
{
'offset': [ignore_empty, natural_number_validator],
'limit': [ignore_empty, natural_number_validator],
}
Example configuration object::
{'name': 'image_view',
'title': 'Image',
'schema': {'image_url': [ignore_empty, unicode]},
'icon': 'compass',
'iframed': false,
'title': toolkit._('Image'),
'schema': {
'image_url': [ignore_empty, unicode]
},
'icon': 'picture',
'always_available': True,
'iframed': False,
}
:returns: a dictionary with the view type configuration
:rtype: dict
.. _Font Awesome: http://fortawesome.github.io/Font-Awesome/3.2.1/icons
'''
return {'name': self.__class__.__name__}

def can_view(self, data_dict):
'''Return info on whether the plugin can preview the resource.
The ``data_dict`` contains: ``resource`` and ``package``.
'''
Returns whether the plugin can render a particular resource.
The ``data_dict`` contains the following keys:
:param resource: dict of the resource fields
:param package: dict of the full parent dataset
return ``True`` or ``False``.
:returns: True if the plugin can render a particular resource, False
otherwise
:rtype: bool
'''

def setup_template_variables(self, context, data_dict):
'''
Add variables to the ``data_dict`` that is passed to the
template being rendered.
Should return a new dict instead of updating the input ``data_dict``.
Adds variables to be passed to the template being rendered.
The ``data_dict`` contains: ``resource_view``, ``resource`` and
``package``.
This should return a new dict instead of updating the input
``data_dict``.
The ``data_dict`` contains the following keys:
:param resource_view: dict of the resource view being rendered
:param resource: dict of the parent resource fields
:param package: dict of the full parent dataset
:returns: a dictionary with the extra variables to pass
:rtype: dict
'''

def view_template(self, context, data_dict):
'''
Returns a string representing the location of the template to be
rendered when the view is rendered.
rendered when the view is displayed
The path will be relative to the template directory you registered
using the :py:func:`~ckan.plugins.toolkit.add_template_directory`
on the :py:class:`~ckan.plugins.interfaces.IConfigurer.update_config`
method, for instance ``views/my_view.html``.
:param resource_view: dict of the resource view being rendered
:param resource: dict of the parent resource fields
:param package: dict of the full parent dataset
The ``data_dict`` contains: ``resource_view``, ``resource`` and
``package``.
:returns: the location of the view template.
:rtype: string
'''

def form_template(self, context, data_dict):
'''
Returns a string representing the location of the template to be
rendered for the read page.
rendered when the edit view form is displayed
The path will be relative to the template directory you registered
using the :py:func:`~ckan.plugins.toolkit.add_template_directory`
on the :py:class:`~ckan.plugins.interfaces.IConfigurer.update_config`
method, for instance ``views/my_view_form.html``.
The ``data_dict`` contains: ``resource_view``, ``resource`` and
``package``.
:param resource_view: dict of the resource view being rendered
:param resource: dict of the parent resource fields
:param package: dict of the full parent dataset
:returns: the location of the edit view form template.
:rtype: string
'''


class IResourcePreview(Interface):
''' For backwards compatibility with the old resource preview code. '''
'''
.. warning:: This interface is deprecated, and is only kept for backwards
compatibility with the old resource preview code. Please
use :py:class:`~ckan.plugins.interfaces.IResourceView` for writing
custom view plugins.
'''

def can_preview(self, data_dict):
'''Return info on whether the plugin can preview the resource.
Expand All @@ -287,14 +355,14 @@ def can_preview(self, data_dict):
2. The new way is to return a dict with three keys:
``'can_preview'`` (``boolean``)
* ``can_preview`` (``boolean``)
``True`` if the extension can preview the resource.
``'fixable'`` (``string``)
* ``fixable`` (``string``)
A string explaining how preview for the resource could be enabled,
for example if the ``resource_proxy`` plugin was enabled.
``'quality'`` (``int``)
* ``quality`` (``int``)
How good the preview is: ``1`` (poor), ``2`` (average) or
``3`` (good). When multiple preview extensions can preview the
same resource, this is used to determine which extension will
Expand Down
6 changes: 4 additions & 2 deletions doc/maintaining/data-viewer.rst
View file
Expand Up @@ -200,8 +200,10 @@ are hosted on separate repositories. Some examples include:
If you want to add another view type to this list, edit this file by sending
a pull request on GitHub.

New plugins to render custom view types can be implemented using
the :py:class:`~ckan.plugins.interfaces.IResourceView` interface.

.. todo:: Link to the documentation for writing view plugins
.. todo:: Link to a proper tutorial for writing custom views


.. _Recline: https://github.com/okfn/recline/
Expand Down Expand Up @@ -327,4 +329,4 @@ Check the command help for the full options::
paster views create -h


.. todo:: Writing custom view types (tutorial?)
.. todo:: Tutorial for writing custom view types.

0 comments on commit 4cd2c31

Please sign in to comment.