Metadata-Version: 2.1
Name: wagtail-schema.org
Version: 4.1.0
Summary: Add Schema.org JSON-LD to your website
Home-page: https://github.com/takeflight/wagtail-schema.org
Author: Tim Heap
Author-email: tim@takeflight.com.au
License: BSD License
Platform: UNKNOWN
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Framework :: Django
Classifier: Framework :: Django :: 3
Classifier: Framework :: Django :: 3.0
Classifier: Framework :: Django :: 3.1
Classifier: Framework :: Django :: 3.2
Classifier: Framework :: Django :: 4
Classifier: Framework :: Django :: 4.0
Classifier: Framework :: Django :: 4.1
Classifier: Framework :: Wagtail
Classifier: Framework :: Wagtail :: 2
Classifier: Framework :: Wagtail :: 3
Classifier: Framework :: Wagtail :: 4
Classifier: License :: OSI Approved :: BSD License
Provides-Extra: testing
License-File: LICENSE

==================
wagtail-schema.org
==================

Add Schema.org JSON-LD to your website

Installing
==========

wagtail-schema.org supports Wagtail 2.0 upwards.

Install using pip:

.. code-block:: console

    $ pip install wagtail-schema.org

Add it to your ``INSTALLED_APPS`` to use the Django template tags:

.. code-block:: python

    INSTALLED_APPS = [
        ...
        'wagtailschemaorg',
        'wagtail.contrib.settings',
    ]

Using
=====

``wagtail-schema.org`` supports two types of schema entities:
site-wide entities and page-specific entities.
Site-wide entities might be the organisation that the site as a whole is about,
while page-specific entities might be a single person that the page in question is about.
Both sets of entities are optional, and
sites can implement only those that make sense.

Site-wide entities
------------------

A site-wide entity is printed on every page
using the ``{% ld_for_site %}`` template tag.
They should be entities that are relevant to the whole site,
such as the Organisation or Person that the site is about.
Multiple (or zero) site-wide entities can exist for a site.

.. code-block:: python

    from django.db import models
    from wagtail.contrib.settings.models import register_setting

    from wagtailschemaorg.models import BaseLDSetting
    from wagtailschemaorg.registry import register_site_thing
    from wagtailschemaorg.utils import extend


    @register_setting
    @register_site_thing
    class TestOrganisation(BaseLDSetting):
        """Details about this organisation"""
        name = models.CharField(max_length=100)
        phone_number = models.CharField(max_length=20)
        email = models.EmailField()
        twitter_handle = models.CharField(max_length=15)
        facebook_url = models.URLField()

        def ld_entity(self):
            return extend(super().ld_entity(), {
                '@type': 'Organization',
                'name': self.name,
                'email': self.email,
                'telephone': self.phone_number,
                'sameAs': [
                    self.twitter_url,
                    self.facebook_url,
                ],
            })

        @property
        def twitter_url(self):
            return 'https://twitter.com/' + self.twitter_handle

.. note:: Every site-wide Thing should have a different ``@id``.
    By default, the ``@id`` is the Thing's ``url``.
    You can change a Thing's ``@id`` by overriding
    ``ld_get_id`` or ``ld_get_url`` as required.

Page-specific entities
----------------------

Each page can specify a list of relevant entities.
Use ``{% ld_for_object page %}`` to print these.

.. code-block:: python

    # this code example assumes that the Wagtail version is 3.0 or higher
    from django.db import models
    from wagtail.admin import FieldPanel
    from wagtail.models import Page

    from testapp.models import TestOrganisation
    from wagtailschemaorg.models import PageLDMixin
    from wagtailschemaorg.utils import extend, image_ld


    class PersonPage(PageLDMixin, Page):
        bio = models.TextField()
        date_of_birth = models.DateField()
        photo = models.ForeignKey('wagtailimages.Image', on_delete=models.PROTECT)

        content_panels = Page.content_panels + [
            FieldPanel('bio'),
            FieldPanel('date_of_birth'),
            FieldPanel('photo'),
        ]

        def ld_entity(self):
            site = self.get_site()
            return extend(super().ld_entity(), {
                '@type': 'Person',
                'birthDate': self.date_of_birth.isoformat(),
                'image': image_ld(self.photo, base_url=site.root_url),
                'organisation': TestOrganisation.for_site(site),
            })

In templates
============

``wagtail-schema.org`` provides two template tags:
one for printing out the site-wide entities and
one for page-specific entities.

Django templates
----------------

Make sure that ``wagtailschemaorg`` is in your ``INSTALLED_APPS``,
and add ``{% load wagtailschemaorg_tags %}`` to the top of your template.

``{% ld_for_site [site] %}``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Print all the site-wide entities for a site.
Takes an optional ``site`` argument,
which defaults to the site from the current template request context.
See ``register_site_thing`` for more information on site-wide entities.

``{% ld_for_object [obj] %}``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Print all the entities for ``obj``.
``obj`` is optional, and defaults to ``page`` in the current template context.
``obj`` should implement the ``ThingLD`` interface.
Calls ``obj.ld_to_data_list``, and prints all the entities returned.

``{% ld_print_entity entity %}``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Print an entity directly. ``entity`` should be a ``dict`` with JSON-LD data.

Jinja2 templates
~~~~~~~~~~~~~~~~

Add ``wagtailschemaorg.jinja2tags.WagtailSchemaOrgExtension`` to your Jinja2 extensions.

``{% ld.for_site([site]) %}``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Print all the site-wide entities for a site.
Takes an optional ``site`` argument,
which defaults to the site from the current template request context.
See ``register_site_thing`` for more information on site-wide entities.

``{% ld.for_object([obj]) %}``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Print all the entities for ``obj``.
``obj`` is optional, and defaults to ``page`` in the current template context.
``obj`` should implement the ``ThingLD`` interface.
Calls ``obj.ld_to_data_list``, and prints all the entities returned.

``{% ld.print_entity(entity) %}``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Print an entity directly. ``entity`` should be a ``dict`` with JSON-LD data.


