Cleaning up the code and renaming some classes to better reflect what it is
Cleaning up the code and renaming some classes to better reflect what it is

file:b/.gitignore (new)
  *.egg-info
  *.pyc
  *.swp
  *.swo
  *~
  #*
  .#*
  build/
  dist/
  distribute-*
file:a/.hgignore (deleted)
syntax: glob  
*.egg-info  
*.pyc  
*.swp  
*.swo  
*~  
#*  
.#*  
build/  
dist/  
 
file:b/README.rst (new)
  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
 
  * A custom User registration and edition 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
 
 
file:a/README.txt (deleted)
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.lib.navl.validators import not_empty
 
  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 overrides 2 method hooks which the base class uses to create the
  validation schema for the creation and editing of a user; to require
  that a fullname is given.
  """
 
  new_user_form = 'user/register.html'
 
  def _add_requires_full_name_to_schema(self, schema):
  """
  Helper function that modifies the fullname validation on an existing schema
  """
  schema['fullname'] = [not_empty, unicode]
 
  def _new_form_to_db_schema(self):
  """
  Defines a custom schema that requires a full name to be supplied
 
  This method is a hook that the base class calls for the validation
  schema to use when creating a new user.
  """
  schema = super(CustomUserController, self)._new_form_to_db_schema()
  self._add_requires_full_name_to_schema(schema)
  return schema
 
  def _edit_form_to_db_schema(self):
  """
  Defines a custom schema that requires a full name cannot be removed
  when editing the user.
 
  This method is a hook that the base class calls for the validation
  schema to use when editing an exiting user.
  """
  schema = super(CustomUserController, self)._edit_form_to_db_schema()
  self._add_requires_full_name_to_schema(schema)
  return schema
 
 
  import logging
  from ckan.lib.base import BaseController, render, c, model, abort, request
  from ckan.lib.base import redirect, _, config, h
  import ckan.logic.action.create as create
  import ckan.logic.action.update as update
  import ckan.logic.action.get as get
  from ckan.logic.converters import date_to_db, date_to_form, convert_to_extras, convert_from_extras
  from ckan.lib.navl.dictization_functions import DataError, flatten_dict, unflatten
  from ckan.logic import NotFound, NotAuthorized, ValidationError
  from ckan.logic import tuplize_dict, clean_dict, parse_params
  from ckan.logic.schema import package_form_schema
  from ckan.plugins import IDatasetForm
  from ckan.plugins import implements, SingletonPlugin
  from ckan.lib.package_saver import PackageSaver
  from ckan.lib.field_types import DateType, DateConvertError
  from ckan.authz import Authorizer
  from ckan.lib.navl.dictization_functions import Invalid
  from ckanext.dgu.forms.package_gov_fields import GeoCoverageType
  from ckan.lib.navl.dictization_functions import validate, missing
  import ckan.logic.validators as val
  import ckan.logic.schema as default_schema
  from ckan.lib.navl.validators import (ignore_missing,
  not_empty,
  empty,
  ignore,
  keep_extras,
  )
 
  log = logging.getLogger(__name__)
 
 
 
  class ExampleDatasetForm(SingletonPlugin):
  """
 
  """
 
  implements(IDatasetForm, inherit=True)
 
  def package_form(self):
  """
  Returns a string representing the location of the template to be
  rendered. e.g. "package/new_package_form.html".
  """
  return 'controller/package_plugin.html'
 
  def is_fallback(self):
  """
  Returns true iff this provides the fallback behaviour, when no other
  plugin instance matches a package's type.
 
  As this is not the fallback controller we should return False. If
  we were wanting to act as the fallback, we'd return True
  """
  return False
 
  def package_types(self):
  """
  Returns an iterable of package type strings.
 
  If a request involving a package of one of those types is made, then
  this plugin instance will be delegated to.
 
  There must only be one plugin registered to each package type. Any
  attempts to register more than one plugin instance to a given package
  type will raise an exception at startup.
  """
  return ["example"]
 
  def setup_template_variables(self, context, data_dict=None):
  """
  Add variables to c just prior to the template being rendered.
  """
  c.licences = [('', '')] + model.Package.get_license_options()
  c.publishers = self.get_publishers()
  c.is_sysadmin = Authorizer().is_sysadmin(c.user)
  c.resource_columns = model.Resource.get_columns()
 
  ## This is messy as auths take domain object not data_dict
  pkg = context.get('package') or c.pkg
  if pkg:
  c.auth_for_change_state = Authorizer().am_authorized(
  c, model.Action.CHANGE_STATE, pkg)
 
  def form_to_db_schema(self):
  """
  Returns the schema for mapping package data from a form to a format
  suitable for the database.
  """
  schema = {
  'title': [not_empty, unicode],
  'name': [not_empty, unicode, val.name_validator, val.package_name_validator],
  'notes': [not_empty, unicode],
 
  'date_released': [date_to_db, convert_to_extras],
  'date_updated': [date_to_db, convert_to_extras],
  'date_update_future': [date_to_db, convert_to_extras],
  'url': [unicode],
  'taxonomy_url': [unicode, convert_to_extras],
 
  'resources': default_schema.default_resource_schema(),
 
  'published_by': [not_empty, unicode, convert_to_extras],
  'published_via': [ignore_missing, unicode, convert_to_extras],
  'author': [ignore_missing, unicode],
  'author_email': [ignore_missing, unicode],
  'mandate': [ignore_missing, unicode, convert_to_extras],
  'license_id': [ignore_missing, unicode],
  'tag_string': [ignore_missing, val.tag_string_convert],
  'national_statistic': [ignore_missing, convert_to_extras],
  'state': [val.ignore_not_admin, ignore_missing],
 
  'log_message': [unicode, val.no_http],
 
  '__extras': [ignore],
  '__junk': [empty],
  }
  return schema
 
  def db_to_form_schema(data):
  """
  Returns the schema for mapping package data from the database into a
  format suitable for the form (optional)
  """
  schema = {
  'date_released': [convert_from_extras, ignore_missing, date_to_form],
  'date_updated': [convert_from_extras, ignore_missing, date_to_form],
  'date_update_future': [convert_from_extras, ignore_missing, date_to_form],
  'precision': [convert_from_extras, ignore_missing],
  'taxonomy_url': [convert_from_extras, ignore_missing],
 
  'resources': default_schema.default_resource_schema(),
  'extras': {
  'key': [],
  'value': [],
  '__extras': [keep_extras]
  },
  'tags': {
  '__extras': [keep_extras]
  },
 
  'published_by': [convert_from_extras, ignore_missing],
  'published_via': [convert_from_extras, ignore_missing],
  'mandate': [convert_from_extras, ignore_missing],
  'national_statistic': [convert_from_extras, ignore_missing],
  '__extras': [keep_extras],
  '__junk': [ignore],
  }
  return schema
 
  def check_data_dict(self, data_dict):
  """
  Check if the return data is correct.
 
  raise a DataError if not.
  """
  return
 
  def get_publishers(self):
  """
  """
  return [('pub1', 'pub2')]
 
  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``.
  """
  # Hook in our custom user controller at the points of creation
  # and edition.
  map.connect('/user/register',
  controller='ckanext.example.controller:CustomUserController',
  action='register')
  map.connect('/user/edit',
  controller='ckanext.example.controller:CustomUserController',
  action='edit')
  map.connect('/user/edit/{id:.*}',
  controller='ckanext.example.controller:CustomUserController',
  action='edit')
 
  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;
  }
 
 
  <form id="package-edit" class="package_create_form ckan" method="post"
  py:attrs="{'class':'has-errors'} if errors else {}"
  xmlns:i18n="http://genshi.edgewall.org/i18n"
  xmlns:py="http://genshi.edgewall.org/"
  xmlns:xi="http://www.w3.org/2001/XInclude">
 
  <div class="error-explanation" py:if="error_summary">
  <h2>Errors in form</h2>
  <p>The form contains invalid entries:</p>
  <ul>
  <li py:for="key, error in error_summary.items()">${"%s: %s" % (key, error)}</li>
  </ul>
  </div>
 
  <fieldset>
  <legend>Example Basic information</legend>
  <dl>
  <dt><label class="field_req" for="title">Title *</label></dt>
  <dd><input id="title" name="title" type="text" value="${data.get('title', '')}"/></dd>
  <dd class="instructions basic">The title of the data set.</dd>
  <dd class="instructions further">The main subject of the data should be clear. For cross-government data requirements, such as spend data, specify the public body the data belongs to or its geographical coverage, in order to distinguish your data from other similar datasets in data.gov.uk. If the data relates to a period of time, include that in the name, although this would not be appropriate for data which is updated over time. It is not a description - save that for the Abstract element. Do not give a trailing full stop.</dd>
  <dd class="hints">e.g. Payments to suppliers with a value over &pound;500 from Harlow Council</dd>
  <dd class="field_error" py:if="errors.get('title', '')">${errors.get('title', '')}</dd>
 
  <dt><label class="field_req" for="name">Identifier *</label></dt>
  <dd><input id="name" maxlength="100" name="name" type="text" value="${data.get('name', '')}" /></dd>
  <dd class="instructions basic">A public unique identifier for the dataset</dd>
  <dd class="instructions further">It should be roughly readable, with dashes separating words.</dd>
  <dd class="hints">Format: Two or more lowercase alphanumeric, dash (-) or underscore (_) characters. e.g. uk-road-traffic-statistics-2008 or local-authority-spend-over-500-harlow</dd>
  <dd class="field_error" py:if="errors.get('name', '')">${errors.get('name', '')}</dd>
 
  <dt><label class="field_req" for="notes">Abstract *</label></dt>
  <dd><textarea cols="60" id="notes" name="notes" rows="15">${data.get('notes', '')}</textarea></dd>
  <dd class="instructions basic">The main description of the dataset</dd>
  <dd class="instructions further">It is often displayed with the package title. In particular, it should start with a short sentence that describes the data set succinctly, because the first few words alone may be used in some views of the data sets. Here is the place to state if there are any limitations or deficiencies to the data in order to enable users to evaluate the information; even incomplete data may be adequate for some users.</dd>
  <dd class="field_error" py:if="errors.get('notes', '')">${errors.get('notes', '')}</dd>
  </dl>
  </fieldset>
 
  <fieldset>
  <legend>Example Details</legend>
  <dl>
  <dt><label class="field_opt" for="date_released">Date released</label></dt>
  <dd><input id="date_released" name="date_released" size="40" type="text" value="${data.get('date_released', '')}" /></dd>
  <dd class="instructions basic">The date of the official release of the initial version of the dataset</dd>
  <dd class="instructions further">This is the date that the data was officially released</dd>
  <dd class="hints">DD/MM/YYYY</dd>
  <dd class="field_error" py:if="errors.get('date_released', '')">${errors.get('date_released', '')}</dd>
 
  <dt><label class="field_opt" for="date_updated">Date updated</label></dt>
  <dd><input id="date_updated" name="date_updated" size="40" type="text" value="${data.get('date_updated', '')}"/></dd>
  <dd class="instructions basic">The date of release of the most recent version of the dataset</dd>
  <dd class="instructions further">This is not necessarily the date when it was updated on data.gov.uk. As with 'Date released', this is for updates to a particular dataset, such as corrections or refinements, not for that of a new time period.</dd>
  <dd class="hints">DD/MM/YYYY</dd>
  <dd class="field_error" py:if="errors.get('date_updated', '')">${errors.get('date_updated', '')}</dd>
 
  <dt><label class="field_opt" for="date_update_future">Date to be published</label></dt>
  <dd><input id="date_update_future" name="date_update_future" size="40" type="text" value="${data.get('date_update_future', '')}"/></dd>
  <dd class="instructions basic">When the dataset will be updated in the future, if appropriate</dd>
  <dd class="hints">DD/MM/YYYY</dd>
  <dd class="field_error" py:if="errors.get('date_updated', '')">${errors.get('date_updated', '')}</dd>
 
  <dt><label class="field_opt" for="update_frequency">Update frequency</label></dt>
  <dd>
  <select class="short" id="update_frequency" name="update_frequency">
  <py:for each="freq_name, freq_desc in c.update_frequency">
  <option value="${freq_name}" py:attrs="{'selected': 'selected' if data.get('update_frequency', '') == freq_name else None}" >
  ${freq_desc}
  </option>
  </py:for>
  </select>
  <label class="inline" for="update_frequency-other">Other:
  <input class="medium-width" id="update_frequency-other" name="update_frequency-other" type="text" value="${data.get('update_frequency-other', '')}"/>
  </label>
  </dd>
  <dd class="instructions basic">How frequently the dataset is updated with new versions</dd>
  <dd class="instructions further">For one-off data, use 'never'. For those once updated but now discontinued, use 'discontinued'.</dd>
  <dd class="field_error" py:if="errors.get('update_frequency', '')">${errors.get('update_frequency', '')}</dd>
 
  <dt><label class="field_opt" for="precision">Precision</label></dt>
  <dd><input id="precision" name="precision" size="40" type="text" value="${data.get('precision', '')}"/></dd>
  <dd class="instructions basic">Indicate the level of precision in the data, to avoid over-interpretation.</dd>
  <dd class="hints">e.g. 'per cent to two decimal places' or 'as supplied by respondents'</dd>
 
  <dt><label class="field_opt" for="url">URL</label></dt>
  <dd><input id="url" name="url" type="text" value="${data.get('url', '')}"/></dd>
  <dd class="instructions basic">The Internet link to a web page discussing the dataset.</dd>
  <dd class="hints">e.g. http://www.somedept.gov.uk/growth-figures.html</dd>
  <dd class="field_error" py:if="errors.get('url', '')">${errors.get('url', '')}</dd>
 
  <dt><label class="field_opt" for="taxonomy_url">Taxonomy URL</label></dt>
  <dd><input id="taxonomy_url" name="taxonomy_url" size="40" type="text" value="${data.get('taxonomy_url', '')}"/></dd>
  <dd class="instructions basic">An Internet link to a web page describing the taxonomies used in the dataset, if any, to ensure they understand any terms used.</dd>
  <dd class="hints">e.g. http://www.somedept.gov.uk/growth-figures-technical-details.html</dd>
  <dd class="field_error" py:if="errors.get('taxonomy_url', '')">${errors.get('taxonomy_url', '')}</dd>
  </dl>
  </fieldset>
  <fieldset>
  <legend>Example Resources</legend>
  <table class="flexitable">
  <thead>
  <tr>
  <th class="field_req resource-url">URL*</th>
  <th class="field_opt resource-format">Format</th>
  <th class="field_opt resource-description">Description</th>
  <th class="field_opt resource-hash">Hash</th>
  </tr>
  </thead>
  <tbody>
  <py:for each="num, res in enumerate(data.get('resources', []) + [{}])">
  <tr>
  <py:for each="col in c.resource_columns">
  <td class="resource-${col}">
  <input name="resources__${num}__${col}" type="text" value="${res.get(col, '')}" class="${'medium-width' if col=='description' else 'short'}" />
  </td>
  </py:for>
  <td class="resource-id"><input name="resources__${num}__id" type="hidden" value="${res.get('id', '')}" /></td>
  </tr>
  </py:for>
  </tbody>
  </table>
  <div class="instructions basic">The files containing the data or address of the APIs for accessing it</div>
  <div class="instructions further">These can be repeated as required. For example if the data is being supplied in multiple formats, or split into different areas or time periods, each file is a different 'resource' which should be described differently. They will all appear on the dataset page on data.gov.uk together.<br/> <b>URL:</b> This is the Internet link directly to the data - by selecting this link in a web browser, the user will immediately download the full data set. Note that datasets are not hosted by data.gov.uk, but by the responsible department<br/> e.g. http://www.somedept.gov.uk/growth-figures-2009.csv<br/><b>Format:</b> This should give the file format in which the data is supplied. You may supply the data in a form not listed here, constrained by the <a href="http://data.gov.uk/blog/new-public-sector-transparency-board-and-public-data-transparency-principles" target="_blank">Public Sector Transparency Board's principles</a> that require that all data is available in an 'open and standardised format' that can be read by a machine. Data can also be released in formats that are not machine-processable (e.g. PDF) alongside this.<br/></div>
  <div class="hints">Format choices: CSV | RDF | XML | XBRL | SDMX | HTML+RDFa | Other as appropriate</div>
  <div class="field_error" py:if="errors.get('resources', '')">Package resource(s) incomplete.</div>
  </fieldset>
 
  <fieldset>
  <legend>Example More details</legend>
  <dl>
  <dt><label class="field_req" for="published_by">Published by *</label></dt>
  <dd>
  <select id="published_by" name="published_by">
  <py:for each="published_name, published_desc in c.publishers">
  <option value="${published_name}" py:attrs="{'selected': 'selected' if data.get('published_by', '') == published_name else None}" >
  ${published_desc}
  </option>
  </py:for>
  </select>
  </dd>
  <dd class="instructions basic">The organisation (usually a public body) credited with or associated with the publication of this data.</dd>
  <dd class="instructions further">Often datasets are associated with both a government department and an outside agency, in which case this field should store the department and "Published via" should store the agency. When an organisation is not listed, please request it using the form found in your data.gov.uk user page under the "Publishers" tab. An asterisk (*) denotes an pre-existing value for this field, which is allowed, but the current user's permissions would not be able to change a package\s publisher to this value.</dd>
 
  <dt><label class="field_opt" for="published_via">Published via</label></dt>
  <dd>
  <select id="published_via" name="published_via">
  <py:for each="published_name, published_desc in c.publishers">
  <option value="${published_name}" py:attrs="{'selected': 'selected' if data.get('published_via', '') == published_name else None}" >
  ${published_desc}
  </option>
  </py:for>
  </select>
  </dd>
  <dd class="instructions basic">A second organisation that is credited with or associated with the publication of this data.</dd>
  <dd class="instructions further">Often datasets are associated with both a government department and an outside agency, in which case the "Published by" field should store the department and this field should store the agency. When an organisation is not listed, please request it using the form found in your data.gov.uk user page under the "Publishers" tab. An asterisk (*) denotes an pre-existing value for this field, which is allowed, but the current user's permissions would not be able to change a package\s publisher to this value.</dd>
 
  <dt><label class="field_opt" for="author">Contact</label></dt>
  <dd><input id="author" name="author" type="text" value="${data.get('author', '')}"/></dd>
  <dd class="instructions basic">The permanent contact point for the public to enquire about this particular dataset. In addition, the Public Data and Transparency Team will use it for any suggestions for changes, feedback, reports of mistakes in the datasets or metadata.</dd>
  <dd class="instructions further">This should be the name of the section of the agency or Department responsible, and should not be a named person. Particular care should be taken in choosing this element.</dd>
  <dd class="hints">Examples: Statistics team, Public consultation unit, FOI contact point</dd>
 
  <dt><label class="field_opt" for="author_email">Contact email</label></dt>
  <dd><input id="author_email" name="author_email" type="text" value="${data.get('author_email', '')}"/></dd>
  <dd class="instructions basic">A generic official e-mail address for members of the public to contact, to match the 'Contact' element.</dd>
  <dd class="instructions further">A new e-mail address may need to be created for this function.</dd>
 
  <dt><label class="field_opt" for="mandate">Mandate</label></dt>
  <dd><input id="mandate" name="mandate" size="40" type="text" value="${data.get('mandate', '')}"/></dd>
  <dd class="instructions basic">An Internet link to the enabling legislation that serves as the mandate for the collection or creation of this data, if appropriate.</dd>
  <dd class="instructions further">This should be taken from The National Archives' Legislation website, and where possible be a link directly to the relevant section of the Act.</dd>
  <dd class="hints">For example Public Record Act s.2 would be: http://www.legislation.gov.uk/id/ukpga/Eliz2/6-7/51/section/2</dd>
 
  <dt><label class="field_opt" for="license_id">Licence *</label></dt>
  <dd>
  <select id="license_id" name="license_id">
  <py:for each="licence_desc, licence_id in c.licences">
  <option value="${licence_id}" py:attrs="{'selected': 'selected' if data.get('license_id', 'uk-ogl') == licence_id else None}" >${licence_desc}</option>
  </py:for>
  </select>
  </dd>
  <dd class="instructions basic">The licence under which the dataset is released.</dd>
  <dd class="instructions further">For most situations of central Departments' and Local Authority data, this should be the 'Open Government Licence'. If you wish to release the data under a different licence, please contact the <a href="mailto:PublicData@nationalarchives.gsi.gov.uk">Public Data and Transparency Team</a>.</dd>
 
  <dt><label class="field_opt" for="tags">Tags</label></dt>
  <dd>
  <input class="long tagComplete" data-tagcomplete-queryparam="incomplete"
  data-tagcomplete-url="/api/2/util/tag/autocomplete" id="tag_string" name="tag_string" size="60" type="text"
  value="${data.get('tag_string') or ' '.join([tag['name'] for tag in data.get('tags', [])])}" />
  </dd>
  <dd class="instructions basic">Tags can be thought of as the way that the packages are categorised, so are of primary importance.</dd>
  <dd class="instructions further">One or more tags should be added to give the government department and geographic location the data covers, as well as general descriptive words. The <a href="http://www.esd.org.uk/standards/ipsv_abridged/" target="_blank">Integrated Public Sector Vocabulary</a> may be helpful in forming these.</dd>
  <dd class="hints">Format: Two or more lowercase alphanumeric or dash (-) characters; different tags separated by spaces. As tags cannot contain spaces, use dashes instead. e.g. for a dataset containing statistics on burns to the arms in the UK in 2009: nhs uk arm burns medical-statistics</dd>
  <dd class="field_error" py:if="errors.get('tag_string', '')">${errors.get('tag_string', '')}</dd>
 
  <dt><label class="field_opt" for="national_statistic">National Statistic</label></dt>
  <dd><input id="national_statistic" name="national_statistic" size="40" type="checkbox" value="yes"
  py:attrs="{'checked': 'checked' if data.get('national_statistic', '').lower() == 'yes' else None}" /></dd>
  <dd class="instructions basic">Indicate if the dataset is a National Statistic</dd>
  <dd class="instructions further">This is so that it can be highlighted.</dd>
 
  </dl>
  </fieldset>
 
  <hr />
  <label for="log_message">Edit summary (briefly describe the changes you have made)</label>
  <textarea id="log_message" name="log_message" class="short wide"></textarea>
 
  <div class="ckan-logged-in" style="display: none;">
  <p>Author: ${c.author}</p>
  </div>
  <div class="ckan-logged-out">
  <label>Author: ${c.author}</label>
  <p class="hints">
  Since you have not signed in this will just be your IP address.
  <a href="${h.url_for(controller='user', action='login', id=None)}" target="_blank">Click here to sign in</a> before saving (opens in new window).
  </p>
  </div>
 
  <div class="submit">
  <input name="preview" type="submit" value="Preview" />
  <input id="save" name="save" type="submit" value="Save" />
  </div>
  <p class="hints">
  <strong>Important:</strong> By submitting content, you agree to release your contributions
  under the open license specified on the <a href="/license">license page</a>. Please <strong>refrain</strong> from editing this page if you are <strong>not</strong> happy to do this.
  </p>
 
  </form>
 
  <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=""
  >
 
  <!-- ! a custom primary nav -->
  <py:match path="//div[@class='menu']">
  <div class="menu">
  ${h.nav_link(c, _('Home'), controller='home', action='index', id=None)}
  ${h.nav_link(c, _('Data'), controller='package', action='index', id=None)}
  ${h.nav_link(c, _('New dataset'), controller='package', action='new', id=None)}
  </div>
  </py:match>
 
  <!-- make a really big search box in the top bar -->
  <py:match path="//div[@id='top-bar']/div[@class='search-form']">
  <div class="search-form">
  <form action="${url(controller='package', action='search')}" method="GET">
  <input type="search" class="search" name="q" value="" autocomplete="off" results="5" placeholder="What are you looking for?" id="bigsearch" />
  <input type="submit" class="searchbutton" value="search" />
  </form>
  </div>
  </py:match>
 
  <xi:include href="layout_base.html" />
  </html>
 
  <form id="user-edit" action="" method="post"
  py:attrs="{'class':'has-errors'} if errors else {}"
  xmlns:i18n="http://genshi.edgewall.org/i18n"
  xmlns:py="http://genshi.edgewall.org/"
  xmlns:xi="http://www.w3.org/2001/XInclude">
 
  <div class="error-explanation" py:if="error_summary">
  <h2>Errors in form</h2>
  <p>The form contains invalid entries:</p>
  <ul>
  <li py:for="key, error in error_summary.items()">${"%s: %s" % (key, error)}</li>
  </ul>
  </div>
 
  <dl>
  <dt><label class="field_opt" for="name">Login:</label></dt>
  <dd><input type="text" name="name" value="${data.get('name','')}" /></dd>
  <dd class="instructions basic">3+ chars, using only 'a-z0-9' and '-_'</dd>
  <dd class="field_error" py:if="errors.get('name', '')">${errors.get('name', '')}</dd>
 
  <dt><label class="field_opt" for="fullname">Full name:</label></dt>
  <dd><input type="text" name="fullname" value="${data.get('fullname','')}" /></dd>
  <dd class="field_error" py:if="errors.get('fullname', '')">${errors.get('fullname', '')}</dd>
 
  <dt><label class="field_opt" for="email">E-Mail</label></dt>
  <dd><input type="text" name="email" value="${data.get('email','')}" /></dd>
 
  <dt><label class="field_opt" for="password1">Password:</label></dt>
  <dd><input type="password" name="password1" value="" /></dd>
  <dd class="field_error" py:if="errors.get('password1', '')">${errors.get('password1', '')}</dd>
 
  <dt><label class="field_opt" for="password2">Password (repeat):</label></dt>
  <dd><input type="password" name="password2" value="" /></dd>
 
  <dd py:if="g.recaptcha_publickey">
  <script type="text/javascript"
  src="http://www.google.com/recaptcha/api/challenge?k=${g.recaptcha_publickey}">
  </script>
  <noscript>
  <iframe src="http://www.google.com/recaptcha/api/noscript?k=${g.recaptcha_publickey}"
  height="300" width="500" frameborder="0"></iframe><br/>
  <textarea name="recaptcha_challenge_field" rows="3" cols="40"> </textarea>
  <input type="hidden" name="recaptcha_response_field" value="manual_challenge" />
  </noscript>
  </dd>
 
  </dl>
  <input id="save" name="save" type="submit" class="pretty-button primary" value="Register now &raquo;" />
  </form>
 
# 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([  
(_('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 ExampleThemePlugin(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',  
'exampletheme', 'theme', 'public')  
template_dir = os.path.join(rootdir, 'ckanext',  
'exampletheme', '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', '')])  
# set the title  
config['ckan.site_title'] = "An 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``.  
"""  
map.connect('/user/register',  
controller='ckanext.exampletheme.controller:CustomUserController',  
action='custom_register')  
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=""  
>  
 
<!-- ! a custom primary nav -->  
<py:match path="//div[@class='menu']">  
<div class="menu">  
<ul>  
<li>${h.nav_link(c, _('Home'), controller='home', action='index', id=None)}  
</li>  
<li>${h.nav_link(c, _('Data'), controller='package', action='index', id=None)}  
</li>  
</ul>  
</div>  
</py:match>  
 
<!-- make a really big search box in the top bar -->  
<py:match path="//div[@id='top-bar']/div[@class='search-form']">  
<div class="search-form">  
<form action="${url(controller='package', action='search')}" method="GET">  
<input type="search" class="search" name="q" value="" autocomplete="off" results="5" placeholder="What are you looking for?" id="bigsearch" />  
<input type="submit" class="searchbutton" value="search" />  
</form>  
</div>  
</py:match>  
 
<xi:include href="layout_base.html" />  
</html>  
 
<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:match path="primarysidebar">  
<li class="widget-container widget_text">  
<h2>Have an OpenID?</h2>  
<p>  
If you have an account with Google, Yahoo or one of many other  
OpenID providers, you can log in without signing up.  
</p>  
<ul>  
<li>${h.link_to(_('Log in now'), h.url_for(conroller='user', action='login'))}</li>  
</ul>  
</li>  
</py:match>  
 
<py:def function="page_title">Register - User</py:def>  
 
<div py:match="content">  
<h2>Join the community</h2>  
 
<form action="/user/register" method="post" class="simple-form" id="register_form">  
<fieldset>  
<legend i18n:msg="site_title">Register with CKAN</legend>  
 
<label for="login">Login:</label>  
<input name="login" value="${c.login}" />  
<br/>  
<label for="fullname">Full name (optional):</label>  
<input name="fullname" value="${c.fullname}" />  
<br/>  
<label for="email">E-Mail:</label>  
<input name="email" value="${c.email}" />  
<br/>  
<label for="password1">Password:</label>  
<input type="password" name="password1" value="" />  
<br/>  
<label for="password2">Password (repeat):</label>  
<input type="password" name="password2" value="" />  
<br/>  
</fieldset>  
${h.submit('s', _('Sign up'))}  
</form>  
</div>  
<xi:include href="layout.html" />  
</html>  
 
file:a/rename.sh -> file:b/rename.sh
if [ $# -ne 1 ]; then if [ $# -ne 1 ]; then
echo "Usage: `basename $0` {NewExtensionName}" echo "Usage: `basename $0` {NewExtensionName}"
exit 65 exit 65
fi fi
   
NEWNAME=$1 NEWNAME=$1
NEWNAME_LOWER="`echo $NEWNAME | awk '{print tolower($0)}'`" NEWNAME_LOWER="`echo $NEWNAME | awk '{print tolower($0)}'`"
echo $NEWNAME_LOWER echo $NEWNAME_LOWER
mv ckanext/exampletheme ckanext/$NEWNAME_LOWER mv ckanext/example ckanext/$NEWNAME_LOWER
grep -rl ExampleTheme * | grep -v `basename $0` | xargs perl -pi -e "s/ExampleTheme/$NEWNAME/g" grep -rl Example * | grep -v `basename $0` | xargs perl -pi -e "s/Example/$NEWNAME/g"
grep -rl exampletheme * | grep -v `basename $0` | xargs perl -pi -e "s/exampletheme/$NEWNAME_LOWER/g" grep -rl example * | grep -v `basename $0` | xargs perl -pi -e "s/example/$NEWNAME_LOWER/g"
cd .. cd ..
mv ckanext-exampletheme ckanext-$NEWNAME_LOWER mv ckanext-example ckanext-$NEWNAME_LOWER
   
file:a/setup.py -> file:b/setup.py
from setuptools import setup, find_packages from setuptools import setup, find_packages
import sys, os import sys, os
   
version = '0.1' version = '0.2'
   
setup( setup(
name='ckanext-exampletheme', name='ckanext-example',
version=version, version=version,
description="Example themeb for customising CKAN", description="Example extension for customising CKAN",
long_description="""\ long_description="""\
""", """,
classifiers=[], # Get strings from http://pypi.python.org/pypi?%3Aaction=list_classifiers classifiers=[], # Get strings from http://pypi.python.org/pypi?%3Aaction=list_classifiers
keywords='', keywords='',
author='Seb Bacon', author='Seb Bacon',
author_email='seb.bacon@gmail.com', author_email='seb.bacon@gmail.com',
url='', url='',
license='', license='',
packages=find_packages(exclude=['ez_setup', 'examples', 'tests']), packages=find_packages(exclude=['ez_setup', 'examples', 'tests']),
namespace_packages=['ckanext', 'ckanext.exampletheme'], namespace_packages=['ckanext', 'ckanext.example'],
include_package_data=True, include_package_data=True,
zip_safe=False, zip_safe=False,
install_requires=[ install_requires=[
# -*- Extra requirements: -*- # -*- Extra requirements: -*-
], ],
entry_points=\ entry_points=\
""" """
[ckan.plugins] [ckan.plugins]
exampletheme=ckanext.exampletheme.plugin:ExampleThemePlugin example=ckanext.example.plugin:ExamplePlugin
  example_package=ckanext.example.controller_plugin:ExampleDatasetForm
   
[ckan.forms] [ckan.forms]
example_form = ckanext.exampletheme.package_form:get_example_fieldset example_form = ckanext.example.package_form:get_example_fieldset
""", """,
) )