Feature/documentation (#170)
* Splits documentation over multiple folders * Editor guide documentation intro * Adds segment dashboard documentation * Adds editor documenation regarding segment creation * Adds logo with padding for the documentation * Updates usage guide documentation * Splits sandbox and custom rules documentation * Improves ‘Create a variant’ documentation * Adds documentation regarding streamfield and template tags * Consistent StreamField references * Feedback from M. Dingjan * Remove ‘coming soon’ section * Enable sandbox debug toolbar * Updated documentation
16
README.rst
|
@ -35,9 +35,11 @@ in the admin interface.
|
|||
|
||||
Instructions
|
||||
------------
|
||||
Wagtail Personalisation requires Wagtail 1.9 or 1.10 and Django 1.9, 1.10 or 1.11.
|
||||
Wagtail Personalisation requires Wagtail 2.0 or 2.1 and Django 1.11 or 2.0.
|
||||
|
||||
To install the package with pip::
|
||||
To install the package with pip:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
pip install wagtail-personalisation
|
||||
|
||||
|
@ -64,6 +66,16 @@ been added in first, this is a prerequisite for this project.
|
|||
# ...
|
||||
]
|
||||
|
||||
|
||||
Documentation
|
||||
-------------
|
||||
|
||||
You can find more information about installing, extending and using this module
|
||||
on `Read the Docs`_.
|
||||
|
||||
.. _Read the Docs: http://wagtail-personalisation.readthedocs.io
|
||||
|
||||
|
||||
Sandbox
|
||||
-------
|
||||
|
||||
|
|
After Width: | Height: | Size: 84 KiB |
After Width: | Height: | Size: 16 KiB |
After Width: | Height: | Size: 84 KiB |
After Width: | Height: | Size: 83 KiB |
After Width: | Height: | Size: 9.7 KiB |
After Width: | Height: | Size: 91 KiB |
After Width: | Height: | Size: 63 KiB |
After Width: | Height: | Size: 73 KiB |
After Width: | Height: | Size: 89 KiB |
30
docs/conf.py
|
@ -17,10 +17,17 @@
|
|||
# add these directories to sys.path here. If the directory is relative to the
|
||||
# documentation root, use os.path.abspath to make it absolute, like shown here.
|
||||
#
|
||||
# import os
|
||||
# import sys
|
||||
# sys.path.insert(0, os.path.abspath('.'))
|
||||
import os
|
||||
import sys
|
||||
|
||||
on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
|
||||
|
||||
if not on_rtd: # only import and set the theme if we're building docs locally
|
||||
import sphinx_rtd_theme
|
||||
html_theme = 'sphinx_rtd_theme'
|
||||
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
|
||||
|
||||
sys.path.insert(0, os.path.abspath('.'))
|
||||
|
||||
# -- General configuration ------------------------------------------------
|
||||
|
||||
|
@ -47,7 +54,7 @@ master_doc = 'index'
|
|||
|
||||
# General information about the project.
|
||||
project = 'wagtail-personalisation'
|
||||
copyright = '2017, Lab Digital BV'
|
||||
copyright = '2018, Lab Digital BV'
|
||||
author = 'Lab Digital BV'
|
||||
|
||||
# The version info for the project you're documenting, acts as replacement for
|
||||
|
@ -55,17 +62,17 @@ author = 'Lab Digital BV'
|
|||
# built documents.
|
||||
#
|
||||
# The short X.Y version.
|
||||
version = '0.11.3'
|
||||
version = '0.12.0'
|
||||
|
||||
# The full version, including alpha/beta/rc tags.
|
||||
release = '0.11.3'
|
||||
release = '0.12.0'
|
||||
|
||||
# The language for content autogenerated by Sphinx. Refer to documentation
|
||||
# for a list of supported languages.
|
||||
#
|
||||
# This is also used if you do content translation via gettext catalogs.
|
||||
# Usually you set "language" from the command line for these cases.
|
||||
language = None
|
||||
# language = None
|
||||
|
||||
# List of patterns, relative to source directory, that match files and
|
||||
# directories to ignore when looking for source files.
|
||||
|
@ -84,7 +91,7 @@ todo_include_todos = False
|
|||
# The theme to use for HTML and HTML Help pages. See the documentation for
|
||||
# a list of builtin themes.
|
||||
#
|
||||
html_theme = 'alabaster'
|
||||
# html_theme = 'alabaster'
|
||||
|
||||
# Theme options are theme-specific and customize the look and feel of a theme
|
||||
# further. For a list of options available for each theme, see the
|
||||
|
@ -92,14 +99,11 @@ html_theme = 'alabaster'
|
|||
#
|
||||
# html_theme_options = {}
|
||||
html_theme_options = {
|
||||
'github_user': 'LabD',
|
||||
'github_banner': True,
|
||||
'github_repo': 'wagtail-personalisation',
|
||||
'travis_button': True,
|
||||
'codecov_button': True,
|
||||
'analytics_id': 'UA-100203499-2',
|
||||
}
|
||||
|
||||
html_logo = 'logo.png'
|
||||
|
||||
# Add any paths that contain custom static files (such as style sheets) here,
|
||||
# relative to this directory. They are copied after the builtin static files,
|
||||
# so a file named "default.css" will overwrite the builtin "default.css".
|
||||
|
|
|
@ -1,6 +1,10 @@
|
|||
Included rules
|
||||
==============
|
||||
|
||||
Wagxperience comes with a base set of rules that allow you to start segmenting
|
||||
your visitors quickly.
|
||||
|
||||
|
||||
Time rule
|
||||
---------
|
||||
|
||||
|
@ -16,11 +20,12 @@ End time The end time of your time frame.
|
|||
|
||||
``wagtail_personalisation.rules.TimeRule``
|
||||
|
||||
|
||||
Day rule
|
||||
--------
|
||||
|
||||
The day rule allows you to segment visitors based on the day of their visit.
|
||||
Select one or multiple days on which you'd like your segment to be applied.
|
||||
Select one or multiple days on which you would like your segment to be applied.
|
||||
|
||||
================== ==========================================================
|
||||
Option Description
|
||||
|
@ -36,6 +41,7 @@ Sunday Matches when the visitors visits on a sunday.
|
|||
|
||||
``wagtail_personalisation.rules.DayRule``
|
||||
|
||||
|
||||
Referral rule
|
||||
-------------
|
||||
|
||||
|
@ -54,6 +60,7 @@ Regex string The regex string to match the referral header to.
|
|||
|
||||
``wagtail_personalisation.rules.ReferralRule``
|
||||
|
||||
|
||||
Visit count rule
|
||||
----------------
|
||||
|
||||
|
@ -72,6 +79,7 @@ Operator Whether to match for more than, less than or equal to the
|
|||
|
||||
``wagtail_personalisation.rules.VisitCountRule``
|
||||
|
||||
|
||||
Query rule
|
||||
----------
|
||||
|
||||
|
@ -92,6 +100,7 @@ Value The second part of the query ('ourbestoffer').
|
|||
|
||||
``wagtail_personalisation.rules.QueryRule``
|
||||
|
||||
|
||||
Device rule
|
||||
-----------
|
||||
|
||||
|
@ -108,6 +117,7 @@ Desktop Matches when the visitor uses a desktop.
|
|||
|
||||
``wagtail_personalisation.rules.DeviceRule``
|
||||
|
||||
|
||||
User is logged in rule
|
||||
----------------------
|
||||
|
||||
|
|
|
@ -0,0 +1,91 @@
|
|||
Creating personalised content
|
||||
=============================
|
||||
|
||||
Once you've created a segment you can start serving personalised content to your
|
||||
visitors. To do this, you can choose one of three methods.
|
||||
|
||||
1. Create a page variant for a segment.
|
||||
2. Use StreamField blocks visible for a segment only.
|
||||
3. Use a template block visible for a segment only.
|
||||
|
||||
|
||||
Method 1: Create a page variant
|
||||
-------------------------------
|
||||
|
||||
**Why you would want to use this method**
|
||||
|
||||
* It has absolutely no restrictions, you can change anything you want.
|
||||
* That's pretty much it.
|
||||
|
||||
**Why you would want to use a different method**
|
||||
|
||||
* You are editing a page that changes often. You would probably rather not
|
||||
change the variation(s) every time the original page changes.
|
||||
|
||||
To create a variant of a page for a specific Segment (which you can change to
|
||||
your liking after creating it), simply go to the Explorer section and find the
|
||||
page you would like to personalize.
|
||||
|
||||
.. figure:: ../_static/images/variants_button.png
|
||||
:alt: The variants button that appears on personalisable pages.
|
||||
|
||||
When you hover over a page, you'll notice a "Variants" dropdown button appears.
|
||||
Click the button and select the segment you would like to create personalised
|
||||
content for.
|
||||
|
||||
Once you've selected the segment, a copy of the original page will be created
|
||||
with a title that includes the segment. Don't worry, your visitors won't be able
|
||||
to see this title. It's only there for your reference.
|
||||
|
||||
.. figure:: ../_static/images/editing_variant.png
|
||||
:alt: The newly created page allowing you to change anything you want.
|
||||
|
||||
You can change everything on this page you would like. Visitors that are appointed
|
||||
to your segment will automatically see the new variant you've created for them
|
||||
when attempting to visit the original page.
|
||||
|
||||
|
||||
Method 2: Use a StreamField block
|
||||
---------------------------------
|
||||
|
||||
Preparing a page and it's StreamField blocks for this method is described in the
|
||||
Usage guide for developers. Please refer to
|
||||
:ref:`implementing_streamfield_blocks` for more information.
|
||||
|
||||
**Why you would want to use this method**
|
||||
|
||||
* Allows you to create personalised content in the original page (without
|
||||
creating a variant).
|
||||
* Create multiple StreamField blocks for different segments inline.
|
||||
|
||||
**Why you would want to use a different method**
|
||||
|
||||
* You need someone tech savvy to change the back-end implementation.
|
||||
|
||||
To create personalised StreamField blocks, first select the page you wan't to
|
||||
create the content for. Note that the personalisable StreamField blocks must be
|
||||
activated on the page by your developer.
|
||||
|
||||
Scroll down to the block containing the StreamField and add a personalisable
|
||||
block. The first input field in the block is a dropdown allowing you to select
|
||||
the segment this StreamField block is ment for.
|
||||
|
||||
.. figure:: ../_static/images/single_streamfield.png
|
||||
:alt: Create a new StreamField block and select the segment.
|
||||
|
||||
If you want, you can even add multiple blocks and change the segment to show
|
||||
different content between segments!
|
||||
|
||||
.. figure:: ../_static/images/dual_streamfield.png
|
||||
:alt: You can even create multiple variations of the same block!
|
||||
|
||||
Once saved, the page will selectively show StreamField blocks based on the
|
||||
visitor's segment.
|
||||
|
||||
|
||||
Method 3: Use a template block
|
||||
------------------------------
|
||||
|
||||
Setting up content in this manner is described in the Usage guide for
|
||||
developers. Please refer to :ref:`implementing_template_blocks` for more
|
||||
information.
|
|
@ -0,0 +1,84 @@
|
|||
Creating a segment
|
||||
==================
|
||||
|
||||
To create a segment, go to the "Segments dashboard" and click "Add segment".
|
||||
You can find the segments dashboard in the administration menu on the left of
|
||||
the page.
|
||||
|
||||
.. figure:: ../_static/images/segment_dashboard_header.png
|
||||
:alt: The segment dashboard header containing the "Add segment" button.
|
||||
|
||||
On this page you will be presented with two forms. One with specific information
|
||||
about your segment, the other allowing you to choose and configure your
|
||||
rules.
|
||||
|
||||
|
||||
Set segment specific options
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. figure:: ../_static/images/edit_segment_specifics.png
|
||||
:alt: The form that allows you to configure specific segment options.
|
||||
|
||||
1. Enter a name for your segment
|
||||
|
||||
Choose something meaningful like "Newsletter campaign visitors". This will
|
||||
ensure you'll have a general idea which visitors are in this segment in
|
||||
other parts of the administration interface.
|
||||
|
||||
2. Select the status of the segment *Optional*
|
||||
|
||||
You will generally keep this one **enabled**. If for some reason you want
|
||||
to disable the segment, you can change this to **disabled**.
|
||||
|
||||
3. Set the segment persistence. *Optional*
|
||||
|
||||
When persistence is **enabled**, your segment will stick to the visitor once
|
||||
applied, even if the rules no longer match the next visit.
|
||||
|
||||
4. Select whether to match any or all defined rules. *Optional*
|
||||
|
||||
**Match any** will result in a segment that is applied as soon as one of
|
||||
your rules matches the visitor. When **match all** is selected, all rules
|
||||
must match before the segment is applied.
|
||||
|
||||
5. The segment type *Required*
|
||||
|
||||
**Dynamic**: Users in this segment will change as more or less meet the
|
||||
rules specified in the segment.
|
||||
|
||||
**Static**: If the segment contains only static compatible rules the segment
|
||||
will contain the members that pass those rules when the segment is created.
|
||||
Mixed static segments or those containing entirely non static compatible
|
||||
rules will be populated using the count variable.
|
||||
|
||||
6. The segment count *Optional*
|
||||
|
||||
If this number is set for a static segment users will be added to the set
|
||||
until the number is reached. After this no more users will be added.
|
||||
|
||||
7. Randomisation percentage *Optional*
|
||||
|
||||
If this number is set each user matching the rules will have this percentage
|
||||
chance of being placed in the segment.
|
||||
|
||||
Defining rules
|
||||
^^^^^^^^^^^^^^
|
||||
|
||||
.. figure:: ../_static/images/edit_segment_rules.png
|
||||
:alt: The form that allows you to set the rules for a segment.
|
||||
|
||||
5. Choose the rules you want to use.
|
||||
|
||||
Wagxperience comes with a basic set of :doc:`../default_rules` that allow
|
||||
you to get started quickly. The rules you define will be evaluated once a
|
||||
visitor makes a request to your application.
|
||||
|
||||
The rules that come with Wagxperience are as follows:
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
../default_rules
|
||||
|
||||
Click "save" to store your segment. It will be enabled by default, unless
|
||||
otherwise defined.
|
|
@ -0,0 +1,13 @@
|
|||
Editor Guide
|
||||
============
|
||||
|
||||
The editor guide is meant for content editors and marketers using Wagxperience
|
||||
to offer a personalised experience to their visitors.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
introduction
|
||||
segments_dashboard
|
||||
creating_segments
|
||||
creating_personalised_content
|
|
@ -0,0 +1,22 @@
|
|||
Introduction
|
||||
============
|
||||
|
||||
Wagxperience_ is an open source module developed by `Lab Digital`_ for the
|
||||
Wagtail_ content management system. It allows editors and marketeers to create
|
||||
personalised experiences by harnessing the power of segmentation and rules.
|
||||
|
||||
.. _Wagxperience: http://wagxperience.io
|
||||
.. _Wagtail: https://wagtail.io
|
||||
.. _Lab Digital: http://labdigital.nl
|
||||
|
||||
In this guide, we'll take you step by step through the process of offering your
|
||||
visitors a tailor made online experience. The subjects covered are:
|
||||
|
||||
* Using the segments dashboard
|
||||
* Defining a new segment
|
||||
* Setting up rules used to match visitors to a segment
|
||||
* Personalize a page by creating a variant
|
||||
* Using the StreamField to personalize content blocks
|
||||
* And even more helpful stuff...
|
||||
|
||||
So without further ado, let's get started!
|
|
@ -0,0 +1,84 @@
|
|||
The segments dashboard
|
||||
======================
|
||||
|
||||
Wagxperience comes with two different views for it's segment dashboard. A "list
|
||||
view" and a "dashboard view". Where the dashboard view attempts to show all
|
||||
relevant information and statistics in a visually pleasing manner, the list view
|
||||
is more fitted for sites using large amounts of segments, as it may be
|
||||
considered more clear in these cases.
|
||||
|
||||
|
||||
Switching between views
|
||||
-----------------------
|
||||
|
||||
By default, Wagxperience's "dashboard view" is active on the segment dashboard.
|
||||
If you would like to switch between the dashboard view and list view, open the
|
||||
segment dashboard and click the "Switch view" button in the green header at the
|
||||
top of the page.
|
||||
|
||||
.. figure:: ../_static/images/segment_dashboard_header.png
|
||||
:alt: The header containing the "Switch view" button.
|
||||
|
||||
|
||||
Using the list view
|
||||
-------------------
|
||||
|
||||
Advantages of using the list view:
|
||||
|
||||
* Uses the familiar table view that is used on many other parts of the Wagtail
|
||||
administration interface.
|
||||
* Offers a better overview for large amounts of segments.
|
||||
* Allows for reordering based on fields, such as name or status.
|
||||
|
||||
.. figure:: ../_static/images/segment_list_view.png
|
||||
:alt: The segment list view.
|
||||
|
||||
|
||||
Definitions
|
||||
^^^^^^^^^^^
|
||||
|
||||
Name
|
||||
The name of your segment.
|
||||
|
||||
Persistent
|
||||
If this is disabled (default), whenever a visitor requests a page, the rules
|
||||
of this segment are reevaluated. This means that when the rules no longer
|
||||
match, the visitor is no longer a part of this segment. However, if
|
||||
persistence is enabled, this segment will "stick" with the visitor, even when
|
||||
the rules no longer apply.
|
||||
|
||||
Match any
|
||||
If this is disabled (default) all rules of this segment must match a visitor
|
||||
before the visitor is appointed to this segment. If this is enabled, only 1
|
||||
rule has to match before the visitor is appointed.
|
||||
|
||||
Status
|
||||
Indicates whether this segment is active (default) or inactive. If it has
|
||||
been set to 'inactive', visitors will not be appointed to this segment and no
|
||||
personalised content for this segment will be shown to visitors.
|
||||
|
||||
Page count
|
||||
The amount of pages that have variants using this segment.
|
||||
|
||||
Variant count
|
||||
The total amount of variants for this segment. Does not yet apply, as this
|
||||
will always match the amount of pages in the "Page count".
|
||||
|
||||
Statistics
|
||||
Shows the amount of visits of this segment and the days it has been
|
||||
enabled. If the segment is disabled and then re-enabled, these statistics
|
||||
will reset.
|
||||
|
||||
|
||||
Using the dashboard view
|
||||
------------------------
|
||||
|
||||
Advantages of using the dashboard view:
|
||||
|
||||
* Offers a more pleasing visual representation of segments.
|
||||
* Focused on giving insights about your segments at a glance.
|
||||
* Shows the actual rules of a segment.
|
||||
* Gives more wordy explanation about the information shown.
|
||||
|
||||
.. figure:: ../_static/images/segment_dashboard_view.png
|
||||
:alt: The segment dashboard view.
|
|
@ -1,32 +0,0 @@
|
|||
Getting started
|
||||
===============
|
||||
|
||||
|
||||
Installing Wagxperience
|
||||
-----------------------
|
||||
|
||||
Installing the module
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The Wagxperience app runs in the Wagtail CMS. You can find out more here_.
|
||||
|
||||
.. _here: http://docs.wagtail.io/en/latest/getting_started/tutorial.html
|
||||
|
||||
1. Install the module::
|
||||
|
||||
pip install wagtail-personalisation
|
||||
|
||||
2. Add the module and ``wagtail.contrib.modeladmin`` to your ``INSTALLED_APPS``::
|
||||
|
||||
INSTALLED_APPS = [
|
||||
# ...
|
||||
'wagtail.contrib.modeladmin',
|
||||
'wagtail_personalisation',
|
||||
# ...
|
||||
]
|
||||
|
||||
3. Update your database::
|
||||
|
||||
python manage.py migrate
|
||||
|
||||
Continue reading: :doc:`implementation`
|
|
@ -0,0 +1,8 @@
|
|||
Getting Started
|
||||
===============
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 3
|
||||
|
||||
installation
|
||||
sandbox
|
|
@ -0,0 +1,37 @@
|
|||
Installing Wagxperience
|
||||
=======================
|
||||
|
||||
Wagtail Personalisation requires Wagtail_ 2.0 or 2.1 and Django_ 1.11 or 2.0.
|
||||
|
||||
.. _Wagtail: https://github.com/wagtail/wagtail
|
||||
.. _Django: https://github.com/django/django
|
||||
|
||||
|
||||
To install the package with pip:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
pip install wagtail-personalisation
|
||||
|
||||
Next, include the ``wagtail_personalisation``, ``wagtail.contrib.modeladmin``
|
||||
and ``wagtailfontawesome`` apps in your project's ``INSTALLED_APPS``:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
INSTALLED_APPS = [
|
||||
# ...
|
||||
'wagtail.contrib.modeladmin',
|
||||
'wagtail_personalisation',
|
||||
'wagtailfontawesome',
|
||||
# ...
|
||||
]
|
||||
|
||||
Make sure that ``django.contrib.sessions.middleware.SessionMiddleware`` has
|
||||
been added in first, this is a prerequisite for this project.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
MIDDLEWARE = [
|
||||
'django.contrib.sessions.middleware.SessionMiddleware',
|
||||
# ...
|
||||
]
|
|
@ -0,0 +1,14 @@
|
|||
Using the sandbox
|
||||
=================
|
||||
|
||||
To experiment with the package you can use the sandbox provided in
|
||||
the repository_. It includes a couple of segments with rules, a personalisable
|
||||
page with a variant and a personalisable StreamField block.
|
||||
|
||||
To install this you will need to create and activate a
|
||||
virtualenv and then run ``make sandbox``. This will start a fresh Wagtail
|
||||
install, with the personalisation module enabled, on http://localhost:8000
|
||||
and http://localhost:8000/cms/. The superuser credentials are
|
||||
``superuser@example.com`` with the password ``testing``.
|
||||
|
||||
.. _repository: https://github.com/LabD/wagtail-personalisation
|
|
@ -1,87 +0,0 @@
|
|||
Implementation
|
||||
===============
|
||||
|
||||
Extending a page to be personalisable
|
||||
-------------------------------------
|
||||
Wagxperience offers a ``PersonalisablePage`` base class to extend from.
|
||||
This is a standard ``Page`` class with personalisation options added.
|
||||
|
||||
Creating a new personalisable page
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
Import and extend the ``personalisation.models.PersonalisablePage`` class to create a personalisable page.
|
||||
|
||||
A very simple example for a personalisable homepage::
|
||||
|
||||
from wagtail_personalisation.models import PersonalisablePage
|
||||
|
||||
class HomePage(PersonalisablePage):
|
||||
subtitle = models.CharField(max_length=255)
|
||||
body = RichTextField(blank=True, default='')
|
||||
|
||||
content_panels = PersonalisablePage.content_panels + [
|
||||
FieldPanel('subtitle'),
|
||||
FieldPanel('body'),
|
||||
]
|
||||
|
||||
It's just as simple as extending a standard ``Page`` class.
|
||||
|
||||
Migrating an existing page to be personalisable
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
|
||||
Creating custom rules
|
||||
---------------------
|
||||
|
||||
Rules consist of two important elements, the model's fields and the ``test_user`` function.
|
||||
|
||||
A very simple example of a rule would look something like this::
|
||||
|
||||
from django.db import models
|
||||
from wagtail.wagtailadmin.edit_handlers import FieldPanel
|
||||
from personalisation import AbstractBaseRule
|
||||
|
||||
class MyNewRule(AbstractBaseRule):
|
||||
field = models.BooleanField(default=False)
|
||||
|
||||
panels = [
|
||||
FieldPanel('field'),
|
||||
]
|
||||
|
||||
def __init__(self, *args, **kwargs):
|
||||
super(MyNewRule, self).__init__(*args, **kwargs)
|
||||
|
||||
def test_user(self, request):
|
||||
return self.field
|
||||
|
||||
As you can see, the only real requirement is the ``test_user`` function that will either return
|
||||
``True`` or ``False`` based on the model's fields and optionally the request object.
|
||||
|
||||
Below is the "Time rule" model included with the module, which offers more complex functionality::
|
||||
|
||||
@python_2_unicode_compatible
|
||||
class TimeRule(AbstractBaseRule):
|
||||
"""Time rule to segment users based on a start and end time"""
|
||||
start_time = models.TimeField(_("Starting time"))
|
||||
end_time = models.TimeField(_("Ending time"))
|
||||
|
||||
panels = [
|
||||
FieldRowPanel([
|
||||
FieldPanel('start_time'),
|
||||
FieldPanel('end_time'),
|
||||
]),
|
||||
]
|
||||
|
||||
def __init__(self, *args, **kwargs):
|
||||
super(TimeRule, self).__init__(*args, **kwargs)
|
||||
|
||||
def test_user(self, request=None):
|
||||
current_time = datetime.now().time()
|
||||
starting_time = self.start_time
|
||||
ending_time = self.end_time
|
||||
|
||||
return starting_time <= current_time <= ending_time
|
||||
|
||||
def __str__(self):
|
||||
return 'Time Rule'
|
||||
|
||||
Continue reading: :doc:`usage_guide`
|
|
@ -3,22 +3,49 @@
|
|||
You can adapt this file completely to your liking, but it should at least
|
||||
contain the root `toctree` directive.
|
||||
|
||||
Welcome to the Wagxperience documentation!
|
||||
==========================================
|
||||
Welcome to the Wagxperience documentation
|
||||
=========================================
|
||||
|
||||
.. image:: https://readthedocs.org/projects/wagtail-personalisation/badge/?version=latest
|
||||
:target: http://wagtail-personalisation.readthedocs.io/en/latest/?badge=latest
|
||||
|
||||
.. image:: https://travis-ci.org/wagtail/wagtail-personalisation.svg?branch=master
|
||||
:target: https://travis-ci.org/wagtail/wagtail-personalisation
|
||||
|
||||
.. image:: http://codecov.io/github/wagtail/wagtail-personalisation/coverage.svg?branch=master
|
||||
:target: http://codecov.io/github/wagtail/wagtail-personalisation?branch=master
|
||||
|
||||
.. image:: https://img.shields.io/pypi/v/wagtail-personalisation.svg
|
||||
:target: https://pypi.python.org/pypi/wagtail-personalisation/
|
||||
|
||||
|
||||
Wagxperience is a fully-featured personalisation module for Wagtail.
|
||||
It enables editors to create customised pages - or parts of pages - based on
|
||||
segments whose rules are configured directly in the admin interface.
|
||||
|
||||
|
||||
* **Get up and running**
|
||||
|
||||
* :doc:`getting_started/index`
|
||||
|
||||
|
||||
* **For developers**
|
||||
|
||||
* :doc:`usage_guide/index`
|
||||
|
||||
|
||||
* **For editors & marketeers**
|
||||
|
||||
* :doc:`editor_guide/index`
|
||||
|
||||
|
||||
Index
|
||||
-----
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:caption: Contents:
|
||||
|
||||
getting_started
|
||||
implementation
|
||||
usage_guide
|
||||
|
||||
getting_started/index
|
||||
usage_guide/index
|
||||
editor_guide/index
|
||||
default_rules
|
||||
|
||||
|
||||
Indices and tables
|
||||
==================
|
||||
|
||||
* :ref:`genindex`
|
||||
* :ref:`modindex`
|
||||
* :ref:`search`
|
||||
|
|
After Width: | Height: | Size: 110 KiB |
|
@ -1,95 +0,0 @@
|
|||
Usage guide
|
||||
===========
|
||||
|
||||
Creating a segment
|
||||
------------------
|
||||
|
||||
As soon as the installation is completed and configured, the module will be
|
||||
visible in the Wagtail administrative area.
|
||||
|
||||
To create a segment, go to the "Segments" page and click on "Add a new segment".
|
||||
|
||||
On this page you will be presented with a form. Follow these steps to create a
|
||||
new segment:
|
||||
|
||||
1. Enter a name for your segment.
|
||||
|
||||
2. (Optional) Select whether to match any or all defined rules.
|
||||
|
||||
``match any`` will result in a segment that is applied as soon as one of
|
||||
your rules matches the visitor. When ``match all`` is selected, all rules
|
||||
must match before the segment is applied.
|
||||
|
||||
3. (Optional) Set the segment persistence.
|
||||
|
||||
When persistence is enabled, your segment will stick to the visitor once
|
||||
applied, even if the rules no longer match on the next visit.
|
||||
|
||||
4. Define your segment rules.
|
||||
|
||||
Wagxperience comes with a basic set of :doc:`default_rules` that allow
|
||||
you to get started quickly. The rules you define will be evaluated once a
|
||||
visitor makes a request to your application.
|
||||
|
||||
5. Save your segment.
|
||||
|
||||
Click "save" to store your segment. It will be enabled by default,
|
||||
unless otherwise defined.
|
||||
|
||||
|
||||
Creating personalized content
|
||||
-----------------------------
|
||||
|
||||
Once you've created a segment you can start serving these visitors with
|
||||
personalised content. To do this, you can go one of two directions.
|
||||
|
||||
1. Create a copy of a page for your segment.
|
||||
|
||||
2. Create StreamField blocks only visible to your segment.
|
||||
|
||||
3. Create a template block only visible to your segment.
|
||||
|
||||
|
||||
Method 1: Create a copy
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
To create a copy from a page for a specific Segment (which you can change to
|
||||
your liking after copying it) simply go to the Explorer section and find the
|
||||
page you'd wish to personalize.
|
||||
|
||||
You'll notice a new "Variants" dropdown button has appeared. Click the button
|
||||
and select the segment you'd like to create personalized content for.
|
||||
|
||||
Once you've selected the segment, a copy of the page will be created with a
|
||||
title that includes the segment. Don't worry, your visitors won't be able to
|
||||
see this title.
|
||||
|
||||
You can change everything on this page you'd like. Visitors that are included in
|
||||
your segment, will automatically see the new page you've created for them.
|
||||
|
||||
|
||||
Method 2: Create a StreamField block
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
|
||||
Method 3: Create a template block
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
You can add a template block that only shows its contents to users of a
|
||||
specific segment. This is done using the "segment" block.
|
||||
|
||||
When editing templates make sure to load the ``wagtail_personalisation_tags``
|
||||
tags library in the template::
|
||||
|
||||
{% load wagtail_personalisation_tags %}
|
||||
|
||||
After that you can add a template block with the name of the segment you want
|
||||
the content to show up for::
|
||||
|
||||
{% segment name="My Segment" %}
|
||||
<p>Only users within "My Segment" see this!</p>
|
||||
{% endsegment %}
|
||||
|
||||
The template block currently only supports one segment at a time. If you want
|
||||
to target multiple segments you will have to make multiple blocks with the
|
||||
same content.
|
|
@ -0,0 +1,17 @@
|
|||
Creating custom rules
|
||||
=====================
|
||||
|
||||
Rules consist of two important elements, the model fields and the
|
||||
``test_user`` function. They should inherit the ``AbstractBaseRule`` class from
|
||||
``wagtail_personalisation.rules``.
|
||||
|
||||
A simple example of a rule could look something like this:
|
||||
|
||||
.. literalinclude:: ../../src/wagtail_personalisation/rules.py
|
||||
:pyobject: UserIsLoggedInRule
|
||||
|
||||
As you can see, the only real requirement is the ``test_user`` function that
|
||||
will either return ``True`` or ``False`` based on the model fields and
|
||||
optionally the request object.
|
||||
|
||||
That's it!
|
|
@ -0,0 +1,71 @@
|
|||
Implementation
|
||||
==============
|
||||
|
||||
Extending a page to be personalisable
|
||||
-------------------------------------
|
||||
Wagxperience offers a ``PersonalisablePage`` base class to extend from.
|
||||
This is a standard ``Page`` class with personalisation options added.
|
||||
|
||||
|
||||
Creating a new personalisable page
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Import and extend the ``personalisation.models.PersonalisablePage`` class to
|
||||
create a personalisable page.
|
||||
|
||||
A very simple example for a personalisable homepage:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from wagtail.wagtailcore.models import Page
|
||||
from wagtail_personalisation.models import PersonalisablePageMixin
|
||||
|
||||
class HomePage(PersonalisablePageMixin, Page):
|
||||
pass
|
||||
|
||||
All you need is the ``PersonalisablePageMixin`` mixin and a Wagtail ``Page``
|
||||
class of your liking.
|
||||
|
||||
|
||||
.. _implementing_streamfield_blocks:
|
||||
|
||||
Adding personalisable StreamField blocks
|
||||
----------------------------------------
|
||||
|
||||
Taking things a step further, you can also add personalisable StreamField blocks
|
||||
to your page models. Below is the full Homepage model used in the sandbox.
|
||||
|
||||
.. literalinclude:: ../../sandbox/sandbox/apps/home/models.py
|
||||
|
||||
|
||||
.. _implementing_template_blocks:
|
||||
|
||||
Using template blocks for personalisation
|
||||
-----------------------------------------
|
||||
|
||||
*Please note that using the personalisable template tag is not the recommended
|
||||
method for adding personalisation to your content, as it is largely decoupled
|
||||
from the administration interface. Use responsibly.*
|
||||
|
||||
You can add a template block that only shows its contents to users of a
|
||||
specific segment. This is done using the "segment" block.
|
||||
|
||||
When editing templates make sure to load the ``wagtail_personalisation_tags``
|
||||
tags library in the template:
|
||||
|
||||
.. code-block:: jinja
|
||||
|
||||
{% load wagtail_personalisation_tags %}
|
||||
|
||||
After that you can add a template block with the name of the segment you want
|
||||
the content to show up for:
|
||||
|
||||
.. code-block:: jinja
|
||||
|
||||
{% segment name="My Segment" %}
|
||||
<p>Only users within "My Segment" see this!</p>
|
||||
{% endsegment %}
|
||||
|
||||
The template block currently only supports one segment at a time. If you want
|
||||
to target multiple segments you will have to make multiple blocks with the
|
||||
same content.
|
|
@ -0,0 +1,8 @@
|
|||
Usage Guide
|
||||
===========
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 3
|
||||
|
||||
implementation
|
||||
custom_rules
|
BIN
logo.png
Before Width: | Height: | Size: 30 KiB After Width: | Height: | Size: 103 KiB |
After Width: | Height: | Size: 98 KiB |
|
@ -1,4 +1,4 @@
|
|||
Django>=2.0,<2.1
|
||||
wagtail>=2.0,<2.2
|
||||
wagtail>=2.1,<2.2
|
||||
django-debug-toolbar==1.9.1
|
||||
-e .[docs,test]
|
||||
|
|
|
@ -1,5 +1,5 @@
|
|||
[bumpversion]
|
||||
current_version = 0.11.3
|
||||
current_version = 0.12.0
|
||||
commit = true
|
||||
tag = true
|
||||
tag_name = {new_version}
|
||||
|
|