projects / ckanext-datagovau.git / commitdiff
search:
summary | shortlog | log | commit | commitdiff | tree
unified | plain
initial commit
initial commit

file:a/.gitignore -> file:b/.gitignore
*.egg-info *.egg-info
*.pyc *.pyc
*.swp *.swp
*.swo *.swo
*~ *~
#* #*
.#* .#*
build/ build/
dist/ dist/
  distribute-*
file:b/.idea/other.xml (new)
  <?xml version="1.0" encoding="UTF-8"?>
  <project version="4">
  <component name="PyDocumentationSettings">
  <option name="myDocStringFormat" value="Plain" />
  </component>
  </project>
 
 
file:b/.idea/testrunner.xml (new)
  <?xml version="1.0" encoding="UTF-8"?>
  <project version="4">
  <component name="TestRunnerService">
  <option name="projectConfiguration" value="Unittests" />
  <option name="PROJECT_TEST_RUNNER" value="Unittests" />
  </component>
  </project>
 
 
file:a/README.rst -> file:b/README.rst
This CKAN Extension demonstrates some common patterns for customising a CKAN instance. This CKAN Extension customises a CKAN instance for the hosting of data.gov.au.
   
It comprises: It comprises:
   
* A CKAN Extension "plugin" at ``ckanext/example/plugin.py`` which, when * A CKAN Extension "plugin" at ``ckanext/datagovau/plugin.py`` which, when
loaded, overrides various settings in the core ``ini``-file to provide: loaded, overrides various settings in the core ``ini``-file to provide:
  * A path to local customisations of the core templates and available licenses database
* A path to local customisations of the core templates and stylesheets * A custom Package edit form
* A "stream filter" that replaces arbitrary strings in rendered templates * A custom n3/rdf output format
* 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 Installation
============ ============
   
To install this package, from your CKAN virtualenv, run the following from your CKAN base folder (e.g. ``pyenv/``):: 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 pip install -e git+https://github.com/okfn/ckanext-datagovau#egg=ckanext-datagovau
   
Then activate it by setting ``ckan.plugins = example`` in your main ``ini``-file. Then activate it by setting ``ckan.plugins = datagovau`` 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://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/example/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-datagovau.iml (new)
  <?xml version="1.0" encoding="UTF-8"?>
  <module type="PYTHON_MODULE" version="4">
  <component name="NewModuleRootManager" inherit-compiler-output="true">
  <exclude-output />
  <content url="file://$MODULE_DIR$">
  <sourceFolder url="file://$MODULE_DIR$" isTestSource="false" />
  </content>
  <orderEntry type="inheritedJdk" />
  <orderEntry type="sourceFolder" forTests="false" />
  </component>
  </module>
 
 
file:b/ckanext/datagovau/templates/package/read_base.html (new)
  {% ckan_extends %}
 
  {% block subtitle %}{{ pkg.title or pkg.name }}{% endblock %}
 
  {% block links -%}
  {{ super() }}
  <link rel="lol" type="test"/>
  {% endblock -%}
 
  {% block head_extras -%}
  {{ super() }}
  <meta property="og:gon" content="lol">
  {% endblock -%}
 
 
file:a/ckanext/example/__init__.py (deleted)
# package  
 
file:a/ckanext/example/controller.py (deleted)
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()  
 
file:a/ckanext/example/package_form.py (deleted)
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:a/ckanext/example/plugin.py (deleted)
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', '')])  
# 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``.  
"""  
# 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  
 
file:a/ckanext/example/theme/public/css/extra.css (deleted)
body {  
background-color: pink;  
}  
 
 
file:a/ckanext/example/theme/templates/home/index.html (deleted)
<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>  
 
file:a/ckanext/example/theme/templates/layout.html (deleted)
<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[@c