README.md

# ckanext-odsh

This CKAN extension provides custom features and the layout of the Open Data Portal
Schleswig-Holstein.

## Table of Contents

- [Getting Started](#getting-started)
- [Contributing](#contributing)
- [Versioning](#versioning)
- [Acknowledgement](#acknowledgement)
- [Authors](#authors)
- [License](#license)

## Getting Started

These instructions will get you a copy of the project up and running on your local
machine for development and testing purposes.

### Prerequisites

This project requires the following CKAN extensions to work properly:

- [ckanext-archiver](https://github.com/ckan/ckanext-archiver)
- [ckanext-dcat](https://github.com/ckan/ckanext-dcat)
- [ckanext-dcatde](https://github.com/GovDataOfficial/ckanext-dcatde)
- [ckanext-harvest](https://github.com/ckan/ckanext-harvest)
- [ckanext-qa](https://github.com/ckan/ckanext-qa)
- [ckanext-spatial](https://github.com/ckan/ckanext-spatial)
- [ckanext-report](https://github.com/ckan/ckanext-report)

### Installing

To install ckanext-odsh:

1. Activate your CKAN virtual environment, for example:

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

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

    ```sh
    pip install https://code.schleswig-holstein.de/opendata/ckanext-odsh.git
    ```

3. Add `odsh` to the `ckan.plugins` setting in your CKAN config file (by default
the config file is located at `/etc/ckan/default/production.ini`).

   You may also add `odsh_autocomplete`, `odsh_collections`, `odsh_dcat_harvest`,
   `kiel_harvester` and `statistikamtnord_harvester` to the plugin list, to enable
   custom functionality, e.g.:

    ```ini
    ckan.plugins =
      ckan_harvester
      dcat
      dcatde
      dcat_json_harvester
      dcat_json_interface
      dcat_rdf_harvester
      dcatde_rdf_harvester
      harvest
      image_view
      kiel_harvester
      odsh
      odsh_autocomplete
      odsh_dcat_harvest
      odsh_collections
      qa
      archiver
      recline_view
      report
      spatial_metadata
      spatial_query
      statistikamtnord_harvester
      stats
      structured_data
      text_view
    ```

4. Restart CKAN.

### Configuration

The extension requires configuration parameters in the CKAN configuration file (e.g.,
`production.ini`). The following parameters should be set:

Parameter | Type | Description
--------- | ----- | -----------
ckanext.odsh.home | `string` | Absolute path to base directory, e.g., `/usr/lib/ckan/default/src/ckanext-odsh`.
ckanext.odsh.public_url | `string` | The public URL, e.g., `https://opendata.schleswig-holstein.de`.
ckanext.odsh.showtestbanner | `boolean` | `true` switches on the banner "test system". Must be `false` for production server.
ckanext.odsh.language_mapping | `string` | Absolute path to language mapping file, e.g., `/usr/lib/ckan/default/src/ckanext-odsh/language_mapping.json`.
ckanext.odsh.subject_mapping | `string` | Absolute path to subject mapping file, e.g., `/usr/lib/ckan/default/src/ckanext-odsh/subject_mapping.json`.
ckanext.odsh.spatial.mapping | `string` | Absolute path to spatial mapping file, e.g., `/usr/lib/ckan/default/src/odsh-odsh/schleswig-holstein_geojson.csv`.
ckanext.odsh.resource_formats_fallback_filepath | `string` | Absolute path to resource formats fallback file, e.g., `/usr/lib/ckan/default/src/ckanext-odsh/fileformats.rdf`
ckanext.odsh.upload_formats | `string` | E.g., `pdf`.
ckanext.odsh.require_at_least_one_category | `boolean` | E.g., `True`.
ckanext.odsh.require_spatial_uri | `boolean` | E.g., `True`.
ckanext.odsh.require_subject | `boolean` | E.g., `False`.
ckanext.odsh.is_optional_temporal_start | `boolean` | E.g., `False`.

### Testing

To ensure the quality and functionality of the `ckanext-odsh` extension, a comprehensive
test suite is provided. You can follow the instructions below to run the tests:

1. Activate the virtual environment associated with your project, for example:

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

2. From the `ckanext-odsh` base directory, execute the following commands:

    ```sh
    pytest ckanext/odsh/tests/
    pytest ckanext/odsh/tests_tpsh/
    ```

Running these commands will initiate the test suite, which will automatically execute
various test cases and verify the expected behavior of the extension. The tests are
organized into two directories: `tests` and `tests_tpsh`, each containing different
sets of tests.

## Contributing

To contribute to this documentation, create a branch or fork this repository, make
your changes and create a merge request.

## Versioning

We use [SemVer](http://semver.org/) for versioning. For the versions available, see
the [tags on this repository](https://code.schleswig-holstein.de/opendata/ckanext-odsh/-/tags).

## Acknowledgement

This extension was originally developed by [HITeC e.V](https://www.hitec-hamburg.de/).

## Authors

See also the list of [contributors](https://code.schleswig-holstein.de/opendata/ckanext-odsh/-/graphs/master)
who participated in this project.

## License

This project is licensed under the GNU AFFERO GENERAL PUBLIC LICENSE - see the
[LICENSE](./LICENSE) file for details.