*.egg-info | |
*.pyc | |
*.swp | |
*.swo | |
*~ | |
#* | |
.#* | |
build/ | |
dist/ | |
distribute-* |
syntax: glob | |
*.egg-info | |
*.pyc | |
*.swp | |
*.swo | |
*~ | |
#* | |
.#* | |
build/ | |
dist/ | |
This CKAN Extension demonstrates some common patterns for customising a CKAN instance. | |
It comprises: | |
* A CKAN Extension "plugin" at ``ckanext/example/plugin.py`` which, when | |
loaded, overrides various settings in the core ``ini``-file to provide: | |
* A path to local customisations of the core templates and stylesheets | |
* A "stream filter" that replaces arbitrary strings in rendered templates | |
* A "route" to override and extend the default behaviour of a core CKAN page | |
* A custom Pylons controller for overriding some core CKAN behaviour | |
* A custom Package edit form | |
* Some simple template customisations | |
Installation | |
============ | |
To install this package, from your CKAN virtualenv, run the following from your CKAN base folder (e.g. ``pyenv/``):: | |
pip install -e git+https://github.com/okfn/ckanext-example#egg=ckanext-example | |
Then activate it by setting ``ckan.plugins = example`` in your main ``ini``-file. | |
Orientation | |
=========== | |
* Examine the source code, starting with ``ckanext/example/plugin.py`` | |
* To understand the nuts and bolts of this file, which is a CKAN | |
*Extension*, read in conjunction with the "Extension | |
documentation": http://docs.ckan.org/en/latest/plugins.html | |
* One thing the extension does is set the values of | |
``extra_public_paths`` and ``extra_template_paths`` in the CKAN | |
config, which are "documented | |
here": http://docs.ckan.org/en/latest/configuration.html#extra-template-paths | |
* These are set to point at directories within | |
``ckanext/example/theme/`` (in this package). Here we: | |
* override the home page HTML ``ckanext/example/theme/templates/home/index.html`` | |
* provide some extra style by serving ``extra.css`` (which is loaded using the ``ckan.template_head_end`` option | |
* customise the navigation and header of the main template in the file ``layout.html``. | |
The latter file is a great place to make global theme alterations. | |
It uses the _layout template_ pattern "described in the Genshi | |
documentation":http://genshi.edgewall.org/wiki/GenshiTutorial#AddingaLayoutTemplate. | |
This allows you to use Xpath selectors to override snippets of HTML | |
globally. | |
* The custom package edit form at ``package_form.py`` follows a deprecated | |
way to make a form (using FormAlchemy). This part of the Example Theme needs | |
updating. In the meantime, follow the instructions at: | |
http://readthedocs.org/docs/ckan/en/latest/forms.html | |
This CKAN Extension demonstrates some common patterns for customising a CKAN instance. | |
It comprises: | |
* A CKAN Extension "plugin" at ``ckanext/exampletheme/plugin.py`` | |
which, when loaded, overrides various settings in the core | |
``ini``-file to provide: | |
* A path to local customisations of the core templates and stylesheets | |
* A "stream filter" that replaces arbitrary strings in rendered templates | |
* A "route" to override and extend the default behaviour of a core CKAN page | |
* A custom Pylons controller for overriding some core CKAN behaviour | |
* A custom Package edit form | |
* Some simple template customisations | |
Installation | |
============ | |
To install this package, from your CKAN virtualenv, run the following from your CKAN base folder (e.g. ``pyenv/``):: | |
pip install -e hg+https://bitbucket.org/okfn/ckanext-exampletheme#egg=ckanext-exampletheme | |
Then activate it by setting ``ckan.plugins = exampletheme`` in your main ``ini``-file. | |
Orientation | |
=========== | |
* Examine the source code, starting with ``ckanext/exampletheme/plugin.py`` | |
* To understand the nuts and bolts of this file, which is a CKAN | |
*Extension*, read in conjunction with the "Extension | |
documentation":http://packages.python.org/ckan/plugins.html | |
* One thing the extension does is set the values of | |
``extra_public_paths`` and ``extra_template_paths`` in the CKAN | |
config, which are "documented | |
here":http://packages.python.org/ckan/configuration.html#extra-template-paths | |
* These are set to point at directories within | |
`ckanext/exampletheme/theme/`` (in this package). Here, we override | |
the home page, provide some extra style with an ``extra.css``, and | |
customise the navigation and header of the main template in the file ``layout.html``. | |
The latter file is a great place to make global theme alterations. | |
It uses the _layout template_ pattern "described in the Genshi | |
documentation":http://genshi.edgewall.org/wiki/GenshiTutorial#AddingaLayoutTemplate. | |
This allows you to use Xpath selectors to override snippets of HTML | |
globally. | |
* The custom package edit form at ``package_form.py`` follows the | |
conventions in the "main CKAN | |
documentation":http://packages.python.org/ckan/forms.html | |
# package | |
import sys | |
from ckan.lib.base import request | |
from ckan.lib.base import c, g, h | |
from ckan.lib.base import model | |
from ckan.lib.base import render | |
from ckan.lib.base import _ | |
from ckan.controllers.user import UserController | |
class CustomUserController(UserController): | |
"""This controller is an example to show how you might extend or | |
override core CKAN behaviour from an extension package. | |
It duplicates functionality in the core CKAN UserController's | |
register function, but extends it to make an email address | |
mandatory. | |
""" | |
def custom_register(self): | |
if request.method == 'POST': | |
# custom validation that requires an email address | |
error = False | |
c.email = request.params.getone('email') | |
c.login = request.params.getone('login') | |
if not model.User.check_name_available(c.login): | |
error = True | |
h.flash_error(_("That username is not available.")) | |
if not c.email: | |
error = True | |
h.flash_error(_("You must supply an email address.")) | |
try: | |
self._get_form_password() | |
except ValueError, ve: | |
h.flash_error(ve) | |
error = True | |
if error: | |
return render('user/register.html') | |
# now delegate to core CKAN register method | |
return self.register() | |
from sqlalchemy.util import OrderedDict | |
from pylons.i18n import _ | |
from ckan.forms import common | |
from ckan.forms import package | |
# Setup the fieldset | |
def build_example_form(is_admin=False, | |
user_editable_groups=None, | |
**kwargs): | |
"""Customise the core CKAN dataset editing form by adding a new | |
field "temporal coverage", and changing the layout of the core | |
fields. | |
""" | |
# Restrict fields | |
builder = package.build_package_form( | |
user_editable_groups=user_editable_groups) | |
# Extra fields | |
builder.add_field(common.DateRangeExtraField('temporal_coverage')) | |
# Layout | |
field_groups = OrderedDict([ | |
(_('Customised Basic information'), ['title', 'name', 'url', | |
'notes', 'tags']), | |
(_('Details'), ['author', 'author_email', 'groups', | |
'maintainer', 'maintainer_email', | |
'license_id', 'temporal_coverage' ]), | |
(_('Resources'), ['resources']), | |
]) | |
builder.set_displayed_fields(field_groups) | |
return builder | |
def get_example_fieldset(is_admin=False, user_editable_groups=None, **kwargs): | |
return build_example_form(is_admin=is_admin, | |
user_editable_groups=user_editable_groups, | |
**kwargs).get_fieldset() | |
import os | |
from logging import getLogger | |
from genshi.filters.transform import Transformer | |
from ckan.plugins import implements, SingletonPlugin | |
from ckan.plugins import IConfigurer | |
from ckan.plugins import IGenshiStreamFilter | |
from ckan.plugins import IRoutes | |
log = getLogger(__name__) | |
class ExamplePlugin(SingletonPlugin): | |
"""This plugin demonstrates how a theme packaged as a CKAN | |
extension might extend CKAN behaviour. | |
In this case, we implement three extension interfaces: | |
- ``IConfigurer`` allows us to override configuration normally | |
found in the ``ini``-file. Here we use it to specify the site | |
title, and to tell CKAN to look in this package for templates | |
and resources that customise the core look and feel. | |
- ``IGenshiStreamFilter`` allows us to filter and transform the | |
HTML stream just before it is rendered. In this case we use | |
it to rename "frob" to "foobar" | |
- ``IRoutes`` allows us to add new URLs, or override existing | |
URLs. In this example we use it to override the default | |
``/register`` behaviour with a custom controller | |
""" | |
implements(IConfigurer, inherit=True) | |
implements(IGenshiStreamFilter, inherit=True) | |
implements(IRoutes, inherit=True) | |
def update_config(self, config): | |
"""This IConfigurer implementation causes CKAN to look in the | |
```public``` and ```templates``` directories present in this | |
package for any customisations. | |
It also shows how to set the site title here (rather than in | |
the main site .ini file), and causes CKAN to use the | |
customised package form defined in ``package_form.py`` in this | |
directory. | |
""" | |
here = os.path.dirname(__file__) | |
rootdir = os.path.dirname(os.path.dirname(here)) | |
our_public_dir = os.path.join(rootdir, 'ckanext', | |
'example', 'theme', 'public') | |
template_dir = os.path.join(rootdir, 'ckanext', | |
'example', 'theme', | |
'templates') | |
# set our local template and resource overrides | |
config['extra_public_paths'] = ','.join([our_public_dir, | |
config.get('extra_public_paths', '')]) | |
config['extra_template_paths'] = ','.join([template_dir, | |
config.get('extra_template_paths', '')]) | |
# add in the extra.css | |
config['ckan.template_head_end'] = config.get('ckan.template_head_end', '') +\ | |
'<link rel="stylesheet" href="/css/extra.css" type="text/css"> ' | |
# set the title | |
config['ckan.site_title'] = "Example CKAN theme" | |
# set the customised package form (see ``setup.py`` for entry point) | |
config['package_form'] = "example_form" | |
def filter(self, stream): | |
"""Conform to IGenshiStreamFilter interface. | |
This example filter renames 'frob' to 'foobar' (this string is | |
found in the custom ``home/index.html`` template provided as | |
part of the package). | |
""" | |
stream = stream | Transformer('//p[@id="examplething"]/text()')\ | |
.substitute(r'frob', r'foobar') | |
return stream | |
def before_map(self, map): | |
"""This IRoutes implementation overrides the standard | |
``/user/register`` behaviour with a custom controller. You | |
might instead use it to provide a completely new page, for | |
example. | |
Note that we have also provided a custom register form | |
template at ``theme/templates/user/register.html``. | |
""" | |
# Note that when we set up the route, we must use the form | |
# that gives it a name (i.e. in this case, 'register'), so it | |
# works correctly with the url_for helper:: | |
# h.url_for('register') | |
map.connect('register', | |
'/user/register', | |
controller='ckanext.example.controller:CustomUserController', | |
action='custom_register') | |
map.connect('/package/new', controller='package_formalchemy', action='new') | |
map.connect('/package/edit/{id}', controller='package_formalchemy', action='edit') | |
return map | |
body { | |
background-color: pink; | |
} | |
<html xmlns:py="http://genshi.edgewall.org/" | |
xmlns:i18n="http://genshi.edgewall.org/i18n" | |
xmlns:xi="http://www.w3.org/2001/XInclude" | |
py:strip=""> | |
<py:def function="page_title">Home</py:def> | |
<py:def function="optional_head"> | |
<style type="text/css"> | |
#examplething { | |
background-color: yellow; | |
padding: 10px; | |
} | |
</style> | |
</py:def> | |
<div py:match="content"> | |
<h2>Welcome to Example Theme!</h2> | |
<p> | |
This page left intentionally ugly | |
</p> | |
<p id="examplething"> | |
Here is the frob | |
</p> | |
</div> | |
<xi:include href="layout.html" /> | |
</html> | |
<html xmlns="http://www.w3.org/1999/xhtml" | |
xmlns:py="http://genshi.edgewall.org/" | |
xmlns:xi="http://www.w3.org/2001/XInclude" | |
xmlns:doap="http://usefulinc.com/ns/doap" | |
xmlns:foaf="http://xmlns.com/foaf/0.1/" | |
py:strip="" |