-
Notifications
You must be signed in to change notification settings - Fork 1
Resource Views
In CKAN 2.3 we are adding a new way to visualize and preview data that is stored within CKAN. Previously this feature was called Resource Previews. This feature had the following limitations:
- It restricted each resource to a single preview type. This was defined by which plugin was deemed more important (but this was not clearly defined)
- There was only one preview per resource.
- There where no ways of storing a predefined configurations of these previews if you wanted a particular configuration of a preview to be displayed.
- No uniform way to embed previews in other sites with particular configuration.
The Resource Views feature gets over all these limitations by having a way to persist saved configurations of views of the data. From here on in these will be just called Views. Each View has a type (i.e could be a graph or a map) and those types will be defined by a new extension point IResourceViews. Old Resource Previews using the IResourcePreview interface will still work and show up as the first View in the new interface, but this extension point is not encouraged for use anymore. There was no way we could change the old extension point without breaking backwards compatibility. However, migration should be fairly simple as they share many of the same methods.
The main difference between the new behaviour and the old behaviour is that there is now an explicit model in CKAN to store the state of the Views. Each View has a view_type defined by the extension point that created it.
The model will be a follows.
id text PRIMARY KEY resource_id text REFERENCES resource (id) title text, description text, view_type text NOT NULL “order” integer NOT NULL config text -- (JSON)
Through the API you only get direct access to the resource_id, title, description and view_type. Ordering is done by CKAN through a special reordering endpoint. Any keys in the config are promoted to the top level json object through the API and these are validated by the schema defined in the extension. i.e if an extension has an extra field "image", a valid json to create a Resource View could be:
{"resource_id": "resid", "view_type": "customviewtype", "title": "My Image", "image": "link to my image"}
As you can see you put the image key in the main dictionary and this will get converted in and out of the config field automatically when using all the API endpoints.
The API endpoints have all necessary functions to view, create, delete and reorder Resource Views:
resource_view_show
resource_view_list
resource_view_create
resource_view_update
resource_view_reorder
resource_view_delete
These are currently documented in the code and will therefore be in the docs once released.
Examples of use can be found in core extension and they all use this extension point the same way an external plugin would too. Use these as a good place to start when creating your own.
https://github.com/ckan/ckan/blob/1251-resource-view/ckanext/imageview/plugin.py
https://github.com/ckan/ckan/blob/1251-resource-view/ckanext/pdfpreview/plugin.py
https://github.com/ckan/ckan/blob/1251-resource-view/ckanext/reclinepreview/plugin.py
https://github.com/ckan/ckan/blob/1251-resource-view/ckanext/textpreview/plugin.py
https://github.com/ckan/ckan/blob/1251-resource-view/ckanext/webpageview/plugin.py
Also a few external plugins have already been made using this extension point:
https://github.com/okfn/ckanext-vegaview
https://github.com/ckan/ckanext-basiccharts
Resource Views inherit authorization of the Resource they belong to. The resource inherits in turn authorization from the dataset it belongs to. There is no current way to make a resource view separate from a resource but there are plans to be able to feed custom config to a view in order to embed your own custom version of a view in another page (the api for this is not finalized).
There is no way to explicitly mark a resource as the default one shown. However, each Resource View has an order it appears against a Resource. The default one shown is the first in the order, so you can just move the View to being first in the order to make it effectively the default. The only exception to this is if the old Resource Preview extension is used and that preview is always the first View in order to preserve old behaviour.
For all core extensions Resource Previews will no longer work, for example the PDF preview will no longer appear. However, there is a paster command that will create a new Resource View for all these types:
paster views create all
It will only create views for the type that are defined in your config file. So for example if you only have pdf_preview defined as a plugin in your config, only PDF Views will be created.
If you disable a Resource View extension point once it has been used, then it can cause problems because CKAN will not know what to display for the Views the extension defined. There is a paster command to delete all views defined by an extension.
paster views clean
This should be run every time you disable a used Resource View extension in your config.
An embed link will be available for all Views in the interface.
class IResourceView(Interface): '''Add custom Resource View type for a resource.
'''
def info(self):
'''Return configuration for the view. Info can return
: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:
{'name': 'image',
'title': 'Image',
'schema': {'image_url': [ignore_empty, unicode]},
'icon': 'compass',
'iframed': false,
}
'''
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``.
return ``True`` or ``False``.
'''
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``.
The ``data_dict`` contains: ``resource_view``, ``resource`` and
``package``.
'''
def view_template(self, context, data_dict):
'''
Returns a string representing the location of the template to be
rendered when the view is rendered.
The ``data_dict`` contains: ``resource_view``, ``resource`` and
``package``.
'''
def form_template(self, context, data_dict):
'''
Returns a string representing the location of the template to be
rendered for the read page.
The ``data_dict`` contains: ``resource_view``, ``resource`` and
``package``.
'''