|
|
|
1 |
This CKAN Extension demonstrates some common patterns for customising a CKAN instance. |
|
|
|
2 |
|
|
|
|
3 |
It comprises: |
|
|
|
4 |
|
|
|
rgrp
|
5 |
* A CKAN Extension "plugin" at ``ckanext/example/plugin.py`` which, when |
|
|
|
6 |
loaded, overrides various settings in the core ``ini``-file to provide: |
|
|
|
7 |
|
|
|
rgrp
|
8 |
* A path to local customisations of the core templates and stylesheets |
|
|
|
9 |
* A "stream filter" that replaces arbitrary strings in rendered templates |
|
|
|
10 |
* A "route" to override and extend the default behaviour of a core CKAN page |
|
|
|
11 |
|
|
|
|
12 |
* A custom Pylons controller for overriding some core CKAN behaviour |
|
|
|
13 |
|
|
|
|
14 |
* A custom Package edit form |
|
|
|
15 |
|
|
|
Ross Jones
|
16 |
* A custom Group edit form |
|
|
|
17 |
|
|
|
Ross Jones
|
18 |
* A plugin that allows for custom forms to be used for datasets based on |
|
|
|
19 |
their "type". |
|
|
|
20 |
|
|
|
Ian Murray
|
21 |
* A custom User registration and edition form |
|
|
|
22 |
|
|
|
rgrp
|
23 |
* Some simple template customisations |
|
|
|
24 |
|
|
|
Seb Bacon
|
25 |
Installation |
|
|
|
26 |
============ |
|
|
|
27 |
|
|
|
|
28 |
To install this package, from your CKAN virtualenv, run the following from your CKAN base folder (e.g. ``pyenv/``):: |
|
|
|
29 |
|
|
|
rgrp
|
30 |
pip install -e git+https://github.com/okfn/ckanext-example#egg=ckanext-example |
|
|
Seb Bacon
|
31 |
|
|
|
rgrp
|
32 |
Then activate it by setting ``ckan.plugins = example`` in your main ``ini``-file. |
|
|
Seb Bacon
|
33 |
|
|
|
|
34 |
Orientation |
|
|
|
35 |
=========== |
|
|
|
36 |
|
|
|
rgrp
|
37 |
* Examine the source code, starting with ``ckanext/example/plugin.py`` |
|
|
Seb Bacon
|
38 |
|
|
|
|
39 |
* To understand the nuts and bolts of this file, which is a CKAN |
|
|
|
40 |
*Extension*, read in conjunction with the "Extension |
|
|
Rufus Pollock
|
41 |
documentation": http://docs.ckan.org/en/latest/extensions.html |
|
|
Seb Bacon
|
42 |
|
|
|
|
43 |
* One thing the extension does is set the values of |
|
|
|
44 |
``extra_public_paths`` and ``extra_template_paths`` in the CKAN |
|
|
|
45 |
config, which are "documented |
|
|
David Read
|
46 |
here": http://docs.ckan.org/en/latest/configuration.html#extra-template-paths |
|
|
Seb Bacon
|
47 |
|
|
|
|
48 |
* These are set to point at directories within |
|
|
David Read
|
49 |
``ckanext/example/theme/`` (in this package). Here we: |
|
|
|
50 |
* override the home page HTML ``ckanext/example/theme/templates/home/index.html`` |
|
|
|
51 |
* provide some extra style by serving ``extra.css`` (which is loaded using the ``ckan.template_head_end`` option |
|
|
|
52 |
* customise the navigation and header of the main template in the file ``layout.html``. |
|
|
Seb Bacon
|
53 |
|
|
|
|
54 |
The latter file is a great place to make global theme alterations. |
|
|
|
55 |
It uses the _layout template_ pattern "described in the Genshi |
|
|
|
56 |
documentation":http://genshi.edgewall.org/wiki/GenshiTutorial#AddingaLayoutTemplate. |
|
|
|
57 |
This allows you to use Xpath selectors to override snippets of HTML |
|
|
|
58 |
globally. |
|
|
|
59 |
|
|
|
Ian Murray
|
60 |
* The custom package edit form at ``package_form.py`` follows a deprecated |
|
|
|
61 |
way to make a form (using FormAlchemy). This part of the Example Theme needs |
|
|
|
62 |
updating. In the meantime, follow the instructions at: |
|
|
Rufus Pollock
|
63 |
http://docs.ckan.org/en/latest/forms.html |
|
|
Ian Murray
|
64 |
|
|
|
John Glover
|
65 |
Example Tags With Vocabularies |
|
|
|
66 |
============================== |
|
|
|
67 |
|
|
|
|
68 |
To add example tag vocabulary data to the database, from the ckanext-example directory run: |
|
|
|
69 |
|
|
|
|
70 |
:: |
|
|
|
71 |
|
|
|
|
72 |
paster example create-example-vocabs -c <path to your ckan config file> |
|
|
|
73 |
|
|
|
|
74 |
This data can be removed with |
|
|
|
75 |
|
|
|
|
76 |
:: |
|
|
|
77 |
|
|
|
|
78 |
paster example clean -c <path to your ckan config file> |
|
|
|
79 |
|
|
|
|
80 |
|