projects / ckanext-datagovau.git / commitdiff
search:
summary | shortlog | log | commit | commitdiff | tree
unified | plain
[1720][forms] tidy up: remove unused imports
[1720][forms] tidy up: remove unused imports

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 Group edit form
 
  * A plugin that allows for custom forms to be used for datasets based on
  their "type".
 
  * 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  
 
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/forms.py (new)
  import os, logging
  from ckan.authz import Authorizer
  from ckan.logic.converters import convert_to_extras,\
  convert_from_extras, convert_to_tags, convert_from_tags
  from ckan.logic.schema import package_form_schema, group_form_schema
  from ckan.model import vocabulary
  from ckan.lib.base import c, model
  from ckan.plugins import IDatasetForm, IGroupForm, IConfigurer, IConfigurable
  from ckan.plugins import implements, SingletonPlugin
  from ckan.lib.navl.validators import ignore_missing, not_empty, keep_extras
 
  log = logging.getLogger(__name__)
 
  class ExampleGroupForm(SingletonPlugin):
  """This plugin demonstrates how a class packaged as a CKAN
  extension might extend CKAN behaviour by providing custom forms
  based on the type of a Group.
 
  In this case, we implement two extension interfaces to provide custom
  forms for specific types of group.
 
  - ``IConfigurer`` allows us to override configuration normally
  found in the ``ini``-file. Here we use it to specify where the
  form templates can be found.
 
  - ``IGroupForm`` allows us to provide a custom form for a dataset
  based on the 'type' that may be set for a group. Where the
  'type' matches one of the values in group_types then this
  class will be used.
  """
  implements(IGroupForm, inherit=True)
  implements(IConfigurer, inherit=True)
 
  def update_config(self, config):
  """
  This IConfigurer implementation causes CKAN to look in the
  ```templates``` directory when looking for the group_form()
  """
  here = os.path.dirname(__file__)
  rootdir = os.path.dirname(os.path.dirname(here))
  template_dir = os.path.join(rootdir, 'ckanext',
  'example', 'theme', 'templates')
  config['extra_template_paths'] = ','.join([template_dir,
  config.get('extra_template_paths', '')])
 
  def group_form(self):
  """
  Returns a string representing the location of the template to be
  rendered. e.g. "forms/group_form.html".
  """
  return 'forms/group_form.html'
 
  def group_types(self):
  """
  Returns an iterable of group type strings.
 
  If a request involving a group of one of those types is made, then
  this plugin instance will be delegated to.
 
  There must only be one plugin registered to each group type. Any
  attempts to register more than one plugin instance to a given group
  type will raise an exception at startup.
  """
  return ["testgroup"]
 
  def is_fallback(self):
  """
  Returns true iff this provides the fallback behaviour, when no other
  plugin instance matches a group'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 form_to_db_schema(self):
  """
  Returns the schema for mapping group data from a form to a format
  suitable for the database.
  """
  return group_form_schema()
 
  def db_to_form_schema(self):
  """
  Returns the schema for mapping group data from the database into a
  format suitable for the form (optional)
  """
  return {}
 
  def check_data_dict(self, data_dict):
  """
  Check if the return data is correct.
 
  raise a DataError if not.
  """
 
  def setup_template_variables(self, context, data_dict):
  """
  Add variables to c just prior to the template being rendered.
  """
 
 
  class ExampleDatasetForm(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 where the
  form templates can be found.
  - ``IDatasetForm`` allows us to provide a custom form for a dataset
  based on the type_name that may be set for a package. Where the
  type_name matches one of the values in package_types then this
  class will be used.
  """
  implements(IDatasetForm, inherit=True)
  implements(IConfigurer, inherit=True)
  implements(IConfigurable)
 
  def update_config(self, config):
  """
  This IConfigurer implementation causes CKAN to look in the
  ```templates``` directory when looking for the package_form()
  """
  here = os.path.dirname(__file__)
  rootdir = os.path.dirname(os.path.dirname(here))
  template_dir = os.path.join(rootdir, 'ckanext',
  'example', 'theme', 'templates')
  config['extra_template_paths'] = ','.join([template_dir,
  config.get('extra_template_paths', '')])
 
  def configure(self, config):
  """
  Adds our new vocabulary to the database if it doesn't
  already exist.
  """
  self.vocab_name = u'example_vocab'
  v = vocabulary.get(self.vocab_name)
  if not v:
  log.info("Adding vocab %s" % self.vocab_name)
  vocab = model.Vocabulary(self.vocab_name)
  model.Session.add(vocab)
  model.Session.commit()
 
  def package_form(self):
  """
  Returns a string representing the location of the template to be
  rendered. e.g. "package/new_package_form.html".
  """
  return 'forms/dataset_form.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 True
 
  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 mo