ckanext-contact
![Docs](https://img.shields.io/readthedocs/ckanext-contact?style=flat-square)
A CKAN extension for adding popup contact forms to pages.
Overview
Borrows much of the contact form code from ckanext-surrey.
An example can be seen on the Natural History Museum's Data Portal when clicking "Contact dataset curator."
This extension now includes Google's reCAPTCHA for preventing spam submissions.
Installation
Path variables used below:
$INSTALL_FOLDER
(i.e. where CKAN is installed), e.g. /usr/lib/ckan/default
$CONFIG_FILE
, e.g. /etc/ckan/default/development.ini
Installing from PyPI
pip install ckanext-contact
Installing from source
-
Clone the repository into the src
folder:
cd $INSTALL_FOLDER/src
git clone https://github.com/NaturalHistoryMuseum/ckanext-contact.git
-
Activate the virtual env:
. $INSTALL_FOLDER/bin/activate
-
Install via pip:
pip install $INSTALL_FOLDER/src/ckanext-contact
Installing in editable mode
Installing from a pyproject.toml
in editable mode (i.e. pip install -e
) requires setuptools>=64
; however, CKAN 2.9 requires setuptools==44.1.0
. See our CKAN fork for a version of v2.9 that uses an updated setuptools if this functionality is something you need.
Post-install setup
-
Add 'contact' to the list of plugins in your $CONFIG_FILE
:
ckan.plugins = ... contact
-
To use reCAPTCHA, you must register a site with the Google reCAPTCHA service and add your API key and secret in the configuration.
Configuration
These are the options that can be specified in your .ini config file.
Email
Name | Description | Default |
---|
ckanext.contact.mail_to | Email address to submit to | email_to |
ckanext.contact.recipient_name | Name of the recipient | ckan.site_title |
ckanext.contact.subject | Email subject for the submitted form | 'Contact/Question from visitor' |
ckanext.contact.add_timestamp_to_subject | Whether to append a timestamp to the subject line | false |
ckanext.contact.subject_prefix | A prefix to add to the subject before sending | '' |
Recaptcha
Name | Description | Default |
---|
ckanext.contact.recaptcha_v3_key | API key for the reCAPTCHA service. | False (i.e. disabled) |
ckanext.contact.recaptcha_v3_secret | API secret for the reCAPTCHA service. | False (i.e. disabled) |
ckanext.contact.recaptcha_v3_action | data-module-action for the form/button | |
Other
Name | Description | Default |
---|
ckanext.contact.check_email | Set to False to disable checking email addresses via pyIsEmail | True (i.e. enabled) |
Usage
Add the following HTML where you want the contact button to appear:
{% set params = {...} %}
<a class="btn btn-primary" data-module="modal-contact" data-module-template="{{ h.get_contact_form_template_url(params) }}" href="{{ h.url_for('contact.form', **params) }}" title="{{ _('Contact') }}">
<i class="fas fa-envelope"></i>{{ link_text if link_text else _('CONTACT BUTTON TEXT') }}
</a>
{% asset 'ckanext-contact/main' %}
Where params
is a dict with three entries: package_id, resource_id, record_id (all of which are optional).
Testing
There is a Docker compose configuration available in this repository to make it easier to run tests. The ckan image uses the Dockerfile in the docker/
folder.
To run the tests against ckan 2.9.x on Python3:
-
Build the required images:
docker compose build
-
Then run the tests.
The root of the repository is mounted into the ckan container as a volume by the Docker compose
configuration, so you should only need to rebuild the ckan image if you change the extension's
dependencies.
docker compose run ckan