1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
|
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/extensions.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://docs.ckan.org/en/latest/forms.html
Example Tags With Vocabularies
==============================
To add example tag vocabulary data to the database, from the ckanext-example directory run:
::
paster example create-example-vocabs -c <path to your ckan config file>
This data can be removed with
::
paster example clean -c <path to your ckan config file>
|