Welcome to Django KDL Wagtail’s documentation!

Contents:

Django KDL Wagtail

https://badge.fury.io/py/django-kdl-wagtail.svg https://travis-ci.org/kingsdigitallab/django-kdl-wagtail.svg?branch=master https://codecov.io/gh/kingsdigitallab/django-kdl-wagtail/branch/master/graph/badge.svg

KDL Wagtail Base Models

Documentation

The full documentation is at https://django-kdl-wagtail.readthedocs.io.

Quickstart

Install Django KDL Wagtail:

pip install django-kdl-wagtail

Add it to your INSTALLED_APPS:

INSTALLED_APPS = (
    ...
    'wagtail.contrib.settings',
    ...
    'kdl_wagtail.core',
    'kdl_wagtail.people',
    ...
)

Features

  • A Core Wagtail application, kdl_wagtail.core with:
    • An abstract BasePage that contains and introduction and image fields, which all the other class in this package extend
    • A RichTextPage with just a RichTextField (WYSIWYG)
    • A StreamPage with a StreamField body
    • An abstract BaseIndexPage, with functions to return the page’s live children, context, and a function to paginate the children
    • An IndexPage
    • A set of reusable StreamField blocks
    • Simple default templates for the pages and blocks defined in the module
  • A public API based on Wagtail’s API https://docs.wagtail.io/en/latest/advanced_topics/api/v2/configuration.html
  • People application, kdl_wagtail_people with:
    • A Person snippet, this is accessible from the Wagtail menu bar
    • A PersonPage
    • A PeopleIndexPage
  • Zotero application, kdl_wagtail_zotero:
    • A Bibliography model to store entried harvested from a Zotero collection
    • A management command, zotero_import, to import entries from a Zotero collection
    • A BibliographyIndexPage, to display all the bibliography entries
    • The Zotero based Bibliography is available from the Wagtail menu bar
  • Custom settings
    • Footer customisation
    • Analytics integration
  • ProxyPage: a new page type to support shortcuts and external links in menus

TODO

  • generic front end search page (with filters for tags, page types, …)
  • generic/abstract wagtail form page
    • contact us page (could possibly inherit from wagtail form page)
  • FAQ page

Running Tests

Does the code actually work?

source <YOURVIRTUALENV>/bin/activate
(myenv) $ pip install tox
(myenv) $ tox

Credits

Tools used in rendering this package:

Installation

At the command line:

$ easy_install django-kdl-wagtail

Or, if you have virtualenvwrapper installed:

$ mkvirtualenv django-kdl-wagtail
$ pip install django-kdl-wagtail

Usage

To use Django KDL Wagtail in a project, add it to your INSTALLED_APPS:

INSTALLED_APPS = (
    ...
    'wagtail.contrib.settings',
    ...
    'kdl_wagtail.core',
    'kdl_wagtail.people',
    'kdl_wagtail.zotero',
    ...
)

Note that to use the zotero app you need to install [pyzotero](https://pyzotero.readthedocs.io/).

To use the Wagtail API, add Django KDL Wagtail’s api_router to urls.py:

from kdl_wagtail.core.api import api_router
urlpatterns = [
    ...
    path('api/v2/', api_router.urls),
    ...
    path('', include('wagtail.core.urls'))
]

Available settings:

# The number of items per page used by the pagination functions
KDL_WAGTAIL_ITEMS_PER_PAGE = 10

# The person model to be used by the kdl_wagtail.people app
KDL_WAGTAIL_PERSON_MODEL = 'kdl_wagtail_people.Person'

# Zotero bibliography settings
# The bibliography model to be used by the kdl_wagtail.zotero app, defaults to
KDL_WAGTAIL_BIBLIOGRAPHY_MODEL = 'kdl_wagtail_zotero.Bibliography'
# Zotero collection to import
KDL_WAGTAIL_ZOTERO_COLLECTION = ''
# ID of the Zotero library
KDL_WAGTAIL_ZOTERO_LIBRARY_ID = ''
# The type of library, either `group` or `user`
KDL_WAGTAIL_ZOTERO_LIBRARY_TYPE = ''
# Note citation style, for available styles see https://www.zotero.org/styles/
KDL_WAGTAIL_ZOTERO_STYLE = 'chicago-note-bibliography'
# Zotero API token
KDL_WAGTAIL_ZOTERO_TOKEN = ''

Available commands:

To import bibliography entries from Zotero run the management command zotero_import. The command takes the optional argument –delete which when present will delele all the existing bibliography entries before doing the Zotero import.

Contributing

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.

You can contribute in many ways:

Types of Contributions

Report Bugs

Report bugs at https://github.com/kingsdigitallab/django-kdl-wagtail/issues.

If you are reporting a bug, please include:

  • Your operating system name and version.
  • Any details about your local setup that might be helpful in troubleshooting.
  • Detailed steps to reproduce the bug.

Fix Bugs

Look through the GitHub issues for bugs. Anything tagged with “bug” is open to whoever wants to implement it.

Implement Features

Look through the GitHub issues for features. Anything tagged with “feature” is open to whoever wants to implement it.

Write Documentation

Django KDL Wagtail could always use more documentation, whether as part of the official Django KDL Wagtail docs, in docstrings, or even on the web in blog posts, articles, and such.

Submit Feedback

The best way to send feedback is to file an issue at https://github.com/kingsdigitallab/django-kdl-wagtail/issues.

If you are proposing a feature:

  • Explain in detail how it would work.
  • Keep the scope as narrow as possible, to make it easier to implement.
  • Remember that this is a volunteer-driven project, and that contributions are welcome :)

Get Started!

Ready to contribute? Here’s how to set up django-kdl-wagtail for local development.

  1. Fork the django-kdl-wagtail repo on GitHub.

  2. Clone your fork locally:

    $ git clone git@github.com:your_name_here/django-kdl-wagtail.git

  3. Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development:

    $ mkvirtualenv django-kdl-wagtail
$ cd django-kdl-wagtail/
$ python setup.py develop

  4. Create a branch for local development:

    $ git checkout -b name-of-your-bugfix-or-feature

    Now you can make your changes locally.

  5. When you’re done making changes, check that your changes pass flake8 and the tests, including testing other Python versions with tox:

    $ flake8 kdl_wagtail tests
$ python setup.py test
$ tox

    To get flake8 and tox, just pip install them into your virtualenv.

  6. Commit your changes and push your branch to GitHub:

    $ git add .
$ git commit -m "Your detailed description of your changes."
$ git push origin name-of-your-bugfix-or-feature

  7. Submit a pull request through the GitHub website.

Pull Request Guidelines

Before you submit a pull request, check that it meets these guidelines:

  1. The pull request should include tests.
  2. If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in README.rst.
  3. The pull request should work for Python 2.6, 2.7, and 3.3, and for PyPy. Check https://travis-ci.org/kingsdigitallab/django-kdl-wagtail/pull_requests and make sure that the tests pass for all supported Python versions.

Tips

To run a subset of tests:

$ python -m unittest tests.test_kdl_wagtail

Credits

Development Lead

Contributors

None yet. Why not be the first?

History

0.10 (2021-10-08)

  • ProxyPage: a new page type to support shortcuts and external links in menus

0.9.0 (2020-01-23)

  • Integration with Zotero
  • Base search

0.5.0 (2019-02-05)

  • Wagtail settings for footer text and analytics settings
  • kdl_wagtail_core utils:
    • paginate
  • kdl_wagtail_core template tags:
    • get_page_children
    • get_analytics_id

0.1.0 (2019-01-22)

  • First release on PyPI.