README.md 5.17 KB
Newer Older
1

David Read's avatar
David Read committed
2
[![Travis CI status](https://travis-ci.org/davidread/ckanext-hierarchy.svg?branch=master)](https://travis-ci.org/davidread/ckanext-hierarchy)
3
4
5
6
7
8

[![Latest version on pypi](https://img.shields.io/pypi/v/ckanext-hierarchy.svg)](https://pypi.org/project/ckanext-hierarchy/)

[![License](https://img.shields.io/pypi/l/ckanext-hierarchy.svg)](https://pypi.org/project/ckanext-hierarchy/)


David Read's avatar
David Read committed
9
# ckanext-hierarchy - Organization hierarchy for CKAN
David Read's avatar
David Read committed
10

11
12
13
14
15
16
Organizations can be arranged into a tree hierarchy.

This new hierarchical arrangement of organizations is displayed
using templates in this extension, instead of the usual list:
![Screenshot of organizations page](screenshots/orgs_page.png)

17
Provides a new field on the organization edit form to select a parent
18
19
20
21
22
23
organization:
![Screenshot of organization edit page](screenshots/org_edit.png)

When viewing an organization you see its context within the tree in the side bar. In addition you can widen search of the organization's datasets to include datasets in sub-organizations too:
![Screenshot of organization page](screenshots/org_page.png)

24
## Technical details
David Read's avatar
David Read committed
25

26
27
28
29
30
31
32
33
Forms (hierachy_form plugin):
* /organization/new
* /organization/edit/{id}

Templates (hierarchy_display plugin):
* /organization - now shows the organization hierarchy instead of list
* /organization/about/{id} - now also shows the relevant part of the hierarchy

34
35
36
Snippets (used by hierarchy_display and ckanext-scheming):
* /scheming/form_snippets/org_hierarchy.html

37
38
39
40
41
42
You can use this extension with CKAN as it is, enabling both plugins. Or if you
use an extension to customise the form already with an IGroupForm, then you
will want to only use the hierarchy_display plugin, and copy bits of the
hierarchy_form into your own. If you have your own templates then you can use
the snippets (or logic functions) that this extension provides to display the
trees.
43

44
In order to make hierarchy work with ckanext-scheming you need to enable just
45
46
47
48
49
50
51
52
53
54
55
56
hierarchy_display and then use corresponding form_snippet in your org_schema.
For example, you may add next field:
```
{
    "field_name": "not_used",
    "label": "Parent organization",
    "display_snippet": null,
    "form_snippet": "org_hierarchy.html",
    "validators": "ignore_missing"
}
```

Lucia Espona's avatar
Lucia Espona committed
57
58
59
60
61
62
63
64
65
66
67
68
69
70
Optionally one could also specify a full name and leave the field 'title' for
the short name or acronym (more convenient for  display).
```
{
    "field_name": "longname",
    "label": "Full Name",
    "validators": "ignore_missing unicode",
    "form_snippet": "large_text.html",
    "form_attrs": {"data-module": "slug-preview-target"},
    "form_placeholder": "My Organization full name",
    "display_snippet": null
}
```

David Read's avatar
David Read committed
71
72
73
TODO:
* make the trees prettier with JSTree

74
## Requirements
David Read's avatar
David Read committed
75

76
This extension requires CKAN v2.7 or later.
David Read's avatar
David Read committed
77
78

## Installation
79

80
81
82
83
84
85
86
87
88
89
To install ckanext-hierarchy:

1. Activate your CKAN virtual environment, for example:

       . /usr/lib/ckan/default/bin/activate

2. Install the ckanext-hierarchy Python package into your virtual environment:

       cd /usr/lib/ckan/default/src
       pip install -e "git+https://github.com/davidread/ckanext-hierarchy.git#egg=ckanext-hierarchy"
Sergey Motornyuk's avatar
Sergey Motornyuk committed
90
       pip install -r ckanext-hierarchy/requirements.txt
91
92
93
94

3. Add ``hierarchy_display`` and ``hierarchy_form`` to the ``ckan.plugins`` setting in your CKAN
   config file (by default the config file is located at
   ``/etc/ckan/default/production.ini``). Note that hierarchy_display
95
should come before hierarchy_form
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153

   e.g.:

       ckan.plugins = stats text_view recline_view ... hierarchy_display hierarchy_form

4. Restart CKAN. For example if you've deployed CKAN with Apache on Ubuntu:

        sudo service apache2 reload

## Config settings

None at present

## Tests

To run the tests, do::

    nosetests --nologcapture --with-pylons=test.ini

To run the tests and produce a coverage report, first make sure you have
coverage installed in your virtualenv (``pip install coverage``) then run::

    nosetests --nologcapture --with-pylons=test.ini --with-coverage --cover-package=ckanext.hierarchy --cover-inclusive --cover-erase --cover-tests


## Releasing a new version of ckanext-hierarchy

ckanext-hierarchy should be available on PyPI as https://pypi.org/project/ckanext-hierarchy.
To publish a new version to PyPI follow these steps:

1. Update the version number in the ``setup.py`` file.
   See `PEP 440 <http://legacy.python.org/dev/peps/pep-0440/#public-version-identifiers>`_
   for how to choose version numbers.

2. Make sure you have the latest version of necessary packages:

       pip install --upgrade setuptools wheel twine

3. Create a source and binary distributions of the new version:

       python setup.py sdist bdist_wheel && twine check dist/*

   Fix any errors you get.

4. Upload the source distribution to PyPI:

       twine upload dist/*

5. Commit any outstanding changes:

       git commit -a

6. Tag the new release of the project on GitHub with the version number from
   the ``setup.py`` file. For example if the version number in ``setup.py`` is
   0.0.1 then do:

       git tag 0.0.1
       git push --tags
154

David Read's avatar
David Read committed
155
156
157
158
159
## Licence and copyright

This module is openly licensed with AGPLv3 - see LICENSE file.

Copyright belongs to commit authors. Commits 2013-2017 by @davidread are Crown Copyright.