===============
django-snakeoil
===============

django-snakeoil helps manage your ``<meta>`` tags. It works on all supported
Django versions and databases.

It offers full internationalization support (tags for multiple languages),
content set dynamically from object attributes, automatic Opengraph image
width and heights for ``ImageField``, and more.

`Full documentation <https://django-snakeoil.readthedocs.io/en/latest/index.html>`_

Getting started
===============

To install, ``pip install django-snakeoil`` or use your favourite package
manager.

You can use Snakeoil in two ways. If you'd like to attach metadata to an
object, you can use the model abstract base class:

.. code-block:: python

    from snakeoil.models import SEOModel

    class Article(SEOModel):
        title = models.CharField(max_length=200)
        author = models.ForeignKey(User, on_delete=models.CASCADE)
        main_image = models.Imagefield(blank=True, null=True)

        @property
        def author_name(self):
            return

        @property
        def snakeoil_metadata(self):
            metadata = {
                "default": [
                    {
                        "name": "author",
                        "content": self.author.get_full_name(),
                    },
                    {"property": "og:title", "content": self.title},
                ]
            }
            if self.main_image:
                metadata["default"].append(
                    {"property": "og:image", "attribute": "main_image"}
                )
            return metadata

You can also override these tags in the admin per-object.

For situations where you can't change the model (flatpages, third party apps)
or don't have one at all, there is an ``SEOPath`` model that maps paths to
your meta tags.

Tags are added in the admin (or however else you like) as JSON. For example:

.. code-block:: JSON

    {
        "default": [
            {"name": "description", "property": "og:description", "content": "Meta description"},
            {"property": "og:title", "content": "My blog post"},
            {"name": "author", "attribute": "author_name"},
            {"property": "og:image", "static": "img/default.jpg"}
        ]
    }

Where ``default`` will work for any language. You can replace ``default``
with a language code, e.g. "nl_NL", and these tags will only display if the
current language is Dutch. This will generate something like:

.. code-block:: html

    <meta name="description" property="og:description" content="Meta description">
    <meta property="og:title" "content="My blog post">
    <!-- from my_object.author_name -->
    <meta name="author" content="Tom Carrick">
    <!-- build a static URL -->
    <meta property="og:image" content="/static/img/default.jpg">

Note that when using ``static``, width and height are not added, but you may
add these yourself. For ``ImageField``, this will be added automatically:

.. code-block:: JSON

    {
        "default": [
            {"property": "og:image", "attribute": "main_image"}
        ]
    }

Results in:

.. code-block:: html

    <meta property="og:image" content="/media/blog_1_main_image.jpg">
    <meta property="og:image:width" content="640">
    <meta property="og:image:height" content="480">

Django Templates
----------------

Add ``snakeoil`` to your ``INSTALLED_APPS``:

.. code-block:: python

    INSTALLED_APPS = [
        "snakeoil",
        # ...
    ]

In your base template, add this where you want the tags to appear:

.. code-block:: html

    {% load snakeoil %}
    {% block head %}
        {% meta %}
    {% endblock %}

This will automatically find an object based on the ``get_absolute_url()``
of your model, by looking in the request context. If nothing is found,
snakeoil will check for an ``SEOPath`` object for the current path. If
you have an object, it is recommended to pass it into the tag directly
to short-circuit the tag finding mechanisms:

.. code-block:: html

    {% meta my_obj %}

Jinja2
------

Set your environment:

.. code-block:: python

    from jinja2 import Environment
    from snakeoil.jinja2 import get_meta_tags

    def environment(**options):
        env = Environment(**options)
        env.globals.update(
            {
                "get_meta_tags": get_meta_tags,
                # ...
            }
        )
        return env

In your template:

.. code-block:: html

    {% block meta %}
        {% with meta_tags=get_meta_tags() %}
            {% include "snakeoil/seo.jinja2" %}
        {% endwith %}
    {% endblock meta %}

To pass in an object:

.. code-block:: html

    {% block meta %}
        {% with meta_tags=get_meta_tags(my_object) %}
            {% include "snakeoil/seo.jinja2" %}
        {% endwith %}
    {% endblock meta %}

Notes
=====

Thanks to kezabelle for the name. For those wondering:

Metadata is often used for SEO purposes. A lot of people (rightly or not)
consider SEO to be snakeoil. Also, SnakEOil. Very clever, I know.

The old version of django-snakeoil can be found on the ``old`` branch, but
won't be updated.