# 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
      dcatde_rdf_harvester
      harvest
      image_view
      kiel_harvester
      odsh
      odsh_autocomplete
      odsh_dcat_harvest
      odsh_collections
      qa
      archiver
      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 | Default | Description
--------- | ---- | ------- | -----------
`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` | `/usr/lib/ckan/default/src/ckanext-odsh/ckanext/odsh/resources/language_mapping.json` | Absolute path to language mapping file.
`ckanext.odsh.spatial.mapping` | `string` | `/usr/lib/ckan/default/src/ckanext-odsh/ckanext/odsh/resources/schleswig-holstein_geojson.csv` | Absolute path to spatial mapping file. The mapping file is expected to be a tab-separated file with three columns: URI, spatial text, and JSON geometry.
`ckanext.odsh.applicable_legislation` | `string` | `/usr/lib/ckan/default/src/ckanext-odsh/ckanext/odsh/resources/applicable_legislation.json` | Absolute path to applicable legislation mapping file.
`ckanext.odsh.hvd_categories` | `string` | `/usr/lib/ckan/default/src/ckanext-odsh/ckanext/odsh/resources/hvd_categories.json` | Absolute path to HVD category mapping file.
`ckanext.odsh.resource_formats_fallback_filepath` | `string` | `/usr/lib/ckan/default/src/ckanext-odsh/ckanext/odsh/resources/fileformats.rdf` | Absolute path to resource formats fallback file.
`ckanext.odsh.require_at_least_one_category` | `boolean` | `False` |  Indicates whether the presence of at least one category is required during validation.
`ckanext.odsh.require_spatial_uri` | `boolean` | `False` | Indicates whether a spatial URI is required for the dataset.
`ckanext.odsh.is_optional_temporal_start` | `boolean` | `False` | Indicate whether the `temporal_start` property is considered optional or not during validation.
`ckanext.odsh.download_proxy` | `string` | `None` | Use proxy server to access the web, e.g., `http://1.2.3.4:4123`.
`ckanext.odsh.copy_remote_resources` | `boolean` | `False` | Indicates whether remote resources should be copied when creating a resource.
`ckanext.odsh.lenient_with` | `string` | Empty string | Comma seperated list of organization IDs for which certain validations should be more lenient, e.g., `09871195-cd0a-4767-9396-276404c940d9,6389d8d9-4eed-472f-9220-4cc2dd82fb90`.
`ckanext.odsh.testuser` | `string` | `None` | Name of user for testing.
`ckanext.odsh.testuserpass` | `string` | `None` | Password of user for testing.

Additionaly you might want to set the following configuration parameters:

```ini
licenses_group_url = file://<path_to_ckan>/default/src/ckanext-odsh/ckanext/odsh/resources/licenses.json
```

### 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/
    ```

Running these commands will initiate the test suite, which will automatically execute
various test cases and verify the expected behavior of the extension.

### Internationalization

To enable internationalization of strings, follow these steps:

1. Ensure that you are in the appropriate environment and located within the extensions directory.

2. Run the following command:

    ```sh
    python setup.py extract_messages
    ```

This command will generate a template PO file named `ckanext/odsh/i18n/ckanext-odsh.pot`. You can utilize tools like [POEdit](https://poedit.net/) to work with this file.

For detailed instructions on internationalizing strings in extensions, refer to CKAN's official guide on [translating extensions](https://docs.ckan.org/en/latest/extensions/translating-extensions.html).

## 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.