Metadata-Version: 2.1
Name: django-slug-preview
Version: 2.0.1
Summary: An advanced slug field with URL previews.
Home-page: https://github.com/edoburu/django-slug-preview
Author: Diederik van der Boor
Author-email: opensource@edoburu.nl
License: Apache 2.0
Download-URL: https://github.com/edoburu/django-slug-preview/zipball/master
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Framework :: Django
Classifier: Framework :: Django :: 2.2
Classifier: Framework :: Django :: 3.1
Classifier: Framework :: Django :: 3.2
Classifier: Framework :: Django :: 4.0
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
License-File: LICENSE
License-File: AUTHORS

django-slug-preview
===================

An advanced slug field offering live URL previews.

This is inspired by the "Permalink" preview that WordPress offers.
While not looking as fancy yet, this is a good start for Django projects.
Improvements are welcome!


.. figure:: https://github.com/edoburu/django-slug-preview/raw/master/docs/images/slugpreview1.png
   :width: 632px
   :height: 95px


Installation
============

First install the module, preferably in a virtual environment.
It can be installed from PyPI::

    pip install django-slug-preview

Or the current folder can be installed for development::

    pip install -e .

Add ``slug_preview`` to your ``INSTALLED_APPS``:

.. code-block:: python

    INSTALLED_APPS += (
        'slug_preview',
    )


Usage
=====

* Use ``slug_preview.models.SlugPreviewField`` in your models instead of the standard ``models.SlugField``.
* Add ``slug_preview.forms.SlugPreviewFormMixin`` in your forms.

For example:

.. code-block:: python

    from django.db import models
    from slug_preview.models import SlugPreviewField

    class MyModel(models.Model):
        slug = SlugPreviewField(_("Slug"))


In the admin you can use the ``SlugPreviewModelForm`` shortcut:

.. code-block:: python

    from django.contrib import admin
    from django import forms
    from slug_preview.forms import SlugPreviewModelForm

    @admin.register(MyModel)
    class MyModelAdmin(admin.ModelAdmin):
        form = SlugPreviewModelForm


In custom forms, use ``SlugPreviewFormMixin`` directly:

.. code-block:: python

    from django import forms
    from slug_preview.forms import SlugPreviewFormMixin
    from .models import MyModel

    class MyModelForm(SlugPreviewFormMixin, forms.ModelForm):
        class Meta:
            model = MyModel


Special model URLS
~~~~~~~~~~~~~~~~~~

When a model has a custom URL layout (not just ``/{slug}/``), you can add a ``get_absolute_url_format()`` method in the model.
For example:

.. code-block:: python

    from django.db import models
    from slug_preview.models import SlugPreviewField

    class Page(models.Model):
        parent = models.ForeignKey('self')
        slug = SlugPreviewField(_("Slug"))
        # ...


        def get_absolute_url(self):
            if self.parent_id:
                return "{0}{1}/".format(self.parent.get_absolute_url(), self.slug)
            else:
                return "/{0}/".format(self.slug)

        def get_absolute_url_format(self):
            if self.parent_id:
                return "{0}{{slug}}/".format(self.parent.get_absolute_url())
            else:
                return "/{slug}/"

For a blog, you can add the ``/blog/{year}/{month}/`` format too:

.. code-block:: python

    from django.core.urlresolvers import reverse
    from django.db import models
    from django.utils.timezone import now
    from slug_preview.models import SlugPreviewField

    class Article(models.Model):
        slug = SlugPreviewField(_("Slug"))
        pubdate = models.DateTimeField(default=now)
        # ...

        def get_absolute_url(self):
            root = reverse('article_list')
            return "{root}/{year}/{month}/{slug}/".format(
                root=reverse('article_list').rstrip('/'),
                year=self.pubdate.strftime('%Y'),
                monthy=self.pubdate.strftime('%M'),
                slug=self.slug
            )

        def get_absolute_url_format(self):
            root = reverse('article_list')
            pubdate = self.pubdate or now()
            return "{root}/{year}/{month}/{{slug}}/".format(
                root=reverse('article_list').rstrip('/'),
                year=pubdate.strftime('%Y'),
                monthy=pubdate.strftime('%M'),
            )


Improving this package
======================

This module is designed to be usable for other projects too.
In case there is anything you didn't like about it,
or think it's not flexible enough, please let us know.
We'd love to improve it! Pull requests are welcome too. :-)


