projects / ckanext-datagovau.git / commitdiff
search:
summary | shortlog | log | commit | commitdiff | tree
unified | plain
[docs] Updated documentation to reflect change to the User form
[docs] Updated documentation to reflect change to the User form

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.
 
 
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  
 
file:b/ckanext/example/__init__.py (new)
  # package
 
file:b/ckanext/example/controller.py (new)
  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
 
 
file:b/ckanext/example/package_form.py (new)
  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()
 
file:b/ckanext/example/plugin.py (new)
  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
 
file:b/ckanext/example/theme/public/css/extra.css (new)
  body {
  background-color: pink;
  }
 
 
file:b/ckanext/example/theme/templates/home/index.html (new)
  <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.