kopia lustrzana https://github.com/wagtail/wagtail
Tom Dyson
commit
ce71b7d010
|
Przed Szerokość: | Wysokość: | Rozmiar: 3.5 KiB Po Szerokość: | Wysokość: | Rozmiar: 3.5 KiB |
|
Przed Szerokość: | Wysokość: | Rozmiar: 3.7 KiB Po Szerokość: | Wysokość: | Rozmiar: 3.7 KiB |
|
Przed Szerokość: | Wysokość: | Rozmiar: 29 KiB Po Szerokość: | Wysokość: | Rozmiar: 29 KiB |
|
Przed Szerokość: | Wysokość: | Rozmiar: 67 KiB Po Szerokość: | Wysokość: | Rozmiar: 67 KiB |
|
Przed Szerokość: | Wysokość: | Rozmiar: 41 KiB Po Szerokość: | Wysokość: | Rozmiar: 41 KiB |
|
Przed Szerokość: | Wysokość: | Rozmiar: 44 KiB Po Szerokość: | Wysokość: | Rozmiar: 44 KiB |
|
Przed Szerokość: | Wysokość: | Rozmiar: 32 KiB Po Szerokość: | Wysokość: | Rozmiar: 32 KiB |
|
Przed Szerokość: | Wysokość: | Rozmiar: 6.9 KiB Po Szerokość: | Wysokość: | Rozmiar: 6.9 KiB |
|
Przed Szerokość: | Wysokość: | Rozmiar: 9.5 KiB Po Szerokość: | Wysokość: | Rozmiar: 9.5 KiB |
|
Przed Szerokość: | Wysokość: | Rozmiar: 11 KiB Po Szerokość: | Wysokość: | Rozmiar: 11 KiB |
|
Przed Szerokość: | Wysokość: | Rozmiar: 6.8 KiB Po Szerokość: | Wysokość: | Rozmiar: 6.8 KiB |
|
Przed Szerokość: | Wysokość: | Rozmiar: 37 KiB Po Szerokość: | Wysokość: | Rozmiar: 37 KiB |
|
Przed Szerokość: | Wysokość: | Rozmiar: 36 KiB Po Szerokość: | Wysokość: | Rozmiar: 36 KiB |
|
Przed Szerokość: | Wysokość: | Rozmiar: 3.9 KiB Po Szerokość: | Wysokość: | Rozmiar: 3.9 KiB |
|
Przed Szerokość: | Wysokość: | Rozmiar: 4.9 KiB Po Szerokość: | Wysokość: | Rozmiar: 4.9 KiB |
|
Przed Szerokość: | Wysokość: | Rozmiar: 3.8 KiB Po Szerokość: | Wysokość: | Rozmiar: 3.8 KiB |
|
Przed Szerokość: | Wysokość: | Rozmiar: 3.5 KiB Po Szerokość: | Wysokość: | Rozmiar: 3.5 KiB |
|
Przed Szerokość: | Wysokość: | Rozmiar: 4.0 KiB Po Szerokość: | Wysokość: | Rozmiar: 4.0 KiB |
|
Przed Szerokość: | Wysokość: | Rozmiar: 4.0 KiB Po Szerokość: | Wysokość: | Rozmiar: 4.0 KiB |
|
Przed Szerokość: | Wysokość: | Rozmiar: 3.9 KiB Po Szerokość: | Wysokość: | Rozmiar: 3.9 KiB |
|
Przed Szerokość: | Wysokość: | Rozmiar: 74 KiB Po Szerokość: | Wysokość: | Rozmiar: 74 KiB |
|
Przed Szerokość: | Wysokość: | Rozmiar: 68 KiB Po Szerokość: | Wysokość: | Rozmiar: 68 KiB |
|
Przed Szerokość: | Wysokość: | Rozmiar: 29 KiB Po Szerokość: | Wysokość: | Rozmiar: 29 KiB |
|
Przed Szerokość: | Wysokość: | Rozmiar: 6.3 KiB Po Szerokość: | Wysokość: | Rozmiar: 6.3 KiB |
|
Przed Szerokość: | Wysokość: | Rozmiar: 43 KiB Po Szerokość: | Wysokość: | Rozmiar: 43 KiB |
|
Przed Szerokość: | Wysokość: | Rozmiar: 111 KiB Po Szerokość: | Wysokość: | Rozmiar: 111 KiB |
|
Przed Szerokość: | Wysokość: | Rozmiar: 40 KiB Po Szerokość: | Wysokość: | Rozmiar: 40 KiB |
|
Przed Szerokość: | Wysokość: | Rozmiar: 216 KiB Po Szerokość: | Wysokość: | Rozmiar: 216 KiB |
|
Przed Szerokość: | Wysokość: | Rozmiar: 30 KiB Po Szerokość: | Wysokość: | Rozmiar: 30 KiB |
|
Przed Szerokość: | Wysokość: | Rozmiar: 19 KiB Po Szerokość: | Wysokość: | Rozmiar: 19 KiB |
|
Przed Szerokość: | Wysokość: | Rozmiar: 117 KiB Po Szerokość: | Wysokość: | Rozmiar: 117 KiB |
|
Przed Szerokość: | Wysokość: | Rozmiar: 10 KiB Po Szerokość: | Wysokość: | Rozmiar: 10 KiB |
|
Przed Szerokość: | Wysokość: | Rozmiar: 22 KiB Po Szerokość: | Wysokość: | Rozmiar: 22 KiB |
|
Przed Szerokość: | Wysokość: | Rozmiar: 6.2 KiB Po Szerokość: | Wysokość: | Rozmiar: 6.2 KiB |
|
Przed Szerokość: | Wysokość: | Rozmiar: 37 KiB Po Szerokość: | Wysokość: | Rozmiar: 37 KiB |
|
Przed Szerokość: | Wysokość: | Rozmiar: 10 KiB Po Szerokość: | Wysokość: | Rozmiar: 10 KiB |
|
Przed Szerokość: | Wysokość: | Rozmiar: 3.6 KiB Po Szerokość: | Wysokość: | Rozmiar: 3.6 KiB |
|
Przed Szerokość: | Wysokość: | Rozmiar: 25 KiB Po Szerokość: | Wysokość: | Rozmiar: 25 KiB |
|
Przed Szerokość: | Wysokość: | Rozmiar: 22 KiB Po Szerokość: | Wysokość: | Rozmiar: 22 KiB |
|
Przed Szerokość: | Wysokość: | Rozmiar: 35 KiB Po Szerokość: | Wysokość: | Rozmiar: 35 KiB |
|
Przed Szerokość: | Wysokość: | Rozmiar: 272 KiB Po Szerokość: | Wysokość: | Rozmiar: 272 KiB |
|
Przed Szerokość: | Wysokość: | Rozmiar: 194 KiB Po Szerokość: | Wysokość: | Rozmiar: 194 KiB |
|
Przed Szerokość: | Wysokość: | Rozmiar: 19 KiB Po Szerokość: | Wysokość: | Rozmiar: 19 KiB |
|
|
@ -1,17 +0,0 @@
|
|||
Advanced Topics
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
.. note::
|
||||
This documentation is currently being written.
|
||||
|
||||
replacing image processing backend
|
||||
|
||||
custom image processing tags?
|
||||
|
||||
wagtail user bar custom CSS option?
|
||||
|
||||
extending hallo editor plugins with editor_js()
|
||||
|
||||
injecting any JS into page edit with editor_js()
|
||||
|
||||
Custom content module (same level as docs or images)
|
||||
|
|
@ -1,428 +0,0 @@
|
|||
For Django developers
|
||||
=====================
|
||||
|
||||
.. contents:: Contents
|
||||
:local:
|
||||
|
||||
.. note::
|
||||
This documentation is currently being written.
|
||||
|
||||
Overview
|
||||
~~~~~~~~
|
||||
|
||||
Wagtail requires a little careful setup to define the types of content that you want to present through your website. The basic unit of content in Wagtail is the ``Page``, and all of your page-level content will inherit basic webpage-related properties from it. But for the most part, you will be defining content yourself, through the construction of Django models using Wagtail's ``Page`` as a base.
|
||||
|
||||
Wagtail organizes content created from your models in a tree, which can have any structure and combination of model objects in it. Wagtail doesn't prescribe ways to organize and interrelate your content, but here we've sketched out some strategies for organizing your models.
|
||||
|
||||
The presentation of your content, the actual webpages, includes the normal use of the Django template system. We'll cover additional functionality that Wagtail provides at the template level later on.
|
||||
|
||||
But first, we'll take a look at the ``Page`` class and model definitions.
|
||||
|
||||
|
||||
The Page Class
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
``Page`` uses Django's model interface, so you can include any field type and field options that Django allows. Wagtail provides some fields and editing handlers that simplify data entry in the Wagtail admin interface, so you may want to keep those in mind when deciding what properties to add to your models in addition to those already provided by ``Page``.
|
||||
|
||||
|
||||
Built-in Properties of the Page Class
|
||||
-------------------------------------
|
||||
|
||||
Wagtail provides some properties in the ``Page`` class which are common to most webpages. Since you'll be subclassing ``Page``, you don't have to worry about implementing them.
|
||||
|
||||
Public Properties
|
||||
`````````````````
|
||||
|
||||
``title`` (string, required)
|
||||
Human-readable title for the content
|
||||
|
||||
``slug`` (string, required)
|
||||
Machine-readable URL component for this piece of content. The name of the page as it will appear in URLs e.g ``http://domain.com/blog/[my-slug]/``
|
||||
|
||||
``seo_title`` (string)
|
||||
Alternate SEO-crafted title which overrides the normal title for use in the ``<head>`` of a page
|
||||
|
||||
``search_description`` (string)
|
||||
A SEO-crafted description of the content, used in both internal search indexing and for the meta description read by search engines
|
||||
|
||||
The ``Page`` class actually has alot more to it, but these are probably the only built-in properties you'll need to worry about when creating templates for your models.
|
||||
|
||||
|
||||
Anatomy of a Wagtail Model
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
So what does a Wagtail model definition look like? Here's a model representing a typical blog post:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from django.db import models
|
||||
|
||||
from wagtail.wagtailcore.models import Page
|
||||
from wagtail.wagtailcore.fields import RichTextField
|
||||
from wagtail.wagtailadmin.edit_handlers import FieldPanel
|
||||
from wagtail.wagtailimages.edit_handlers import ImageChooserPanel
|
||||
from wagtail.wagtailimages.models import Image
|
||||
|
||||
class BlogPage(Page):
|
||||
body = RichTextField()
|
||||
date = models.DateField("Post date")
|
||||
feed_image = models.ForeignKey(
|
||||
'wagtailimages.Image',
|
||||
null=True,
|
||||
blank=True,
|
||||
on_delete=models.SET_NULL,
|
||||
related_name='+'
|
||||
)
|
||||
|
||||
BlogPage.content_panels = [
|
||||
FieldPanel('title', classname="full title"),
|
||||
FieldPanel('date'),
|
||||
FieldPanel('body', classname="full"),
|
||||
]
|
||||
|
||||
BlogPage.promote_panels = [
|
||||
FieldPanel('slug'),
|
||||
FieldPanel('seo_title'),
|
||||
FieldPanel('show_in_menus'),
|
||||
FieldPanel('search_description'),
|
||||
ImageChooserPanel('feed_image'),
|
||||
]
|
||||
|
||||
To keep track of your ``Page``-derived models, it might be helpful to include "Page" as the last part of your class name. ``BlogPage`` defines three properties: ``body``, ``date``, and ``feed_image``. These are a mix of basic Django models (``DateField``), Wagtail fields (``RichTextField``), and a pointer to a Wagtail model (``Image``).
|
||||
|
||||
Next, the ``content_panels`` and ``promote_panels`` lists define the capabilities and layout of the Wagtail admin page edit interface. The lists are filled with "panels" and "choosers", which will provide a fine-grain interface for inputting the model's content. The ``ImageChooserPanel``, for instance, lets one browse the image library, upload new images, and input image metadata. The ``RichTextField`` is the basic field for creating web-ready website rich text, including text formatting and embedded media like images and video. The Wagtail admin offers other choices for fields, Panels, and Choosers, with the option of creating your own to precisely fit your content without workarounds or other compromises.
|
||||
|
||||
Your models may be even more complex, with methods overriding the built-in functionality of the ``Page`` to achieve webdev magic. Or, you can keep your models simple and let Wagtail's built-in functionality do the work.
|
||||
|
||||
Now that we have a basic idea of how our content is defined, lets look at relationships between pieces of content.
|
||||
|
||||
|
||||
Introduction to Trees
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
If you're unfamiliar with trees as an abstract data type, you might want to `review the concepts involved. <http://en.wikipedia.org/wiki/Tree_(data_structure)>`_
|
||||
|
||||
As a web developer, though, you probably already have a good understanding of trees as filesystem directories or paths. Wagtail pages can create the same structure, as each page in the tree has its own URL path, like so::
|
||||
|
||||
/
|
||||
people/
|
||||
nien-nunb/
|
||||
laura-roslin/
|
||||
events/
|
||||
captain-picard-day/
|
||||
winter-wrap-up/
|
||||
|
||||
The Wagtail admin interface uses the tree to organize content for editing, letting you navigate up and down levels in the tree through its Explorer menu. This method of organization is a good place to start in thinking about your own Wagtail models.
|
||||
|
||||
|
||||
Nodes and Leaves
|
||||
----------------
|
||||
|
||||
It might be handy to think of the ``Page``-derived models you want to create as being one of two node types: parents and leaves. Wagtail isn't prescriptive in this approach, but it's a good place to start if you're not experienced in structuring your own content types.
|
||||
|
||||
|
||||
Nodes
|
||||
`````
|
||||
Parent nodes on the Wagtail tree probably want to organize and display a browse-able index of their descendants. A blog, for instance, needs a way to show a list of individual posts.
|
||||
|
||||
A Parent node could provide its own function returning its descendant objects.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
class EventPageIndex(Page):
|
||||
# ...
|
||||
def events(self):
|
||||
# Get list of live event pages that are descendants of this page
|
||||
events = EventPage.objects.live().descendant_of(self)
|
||||
|
||||
# Filter events list to get ones that are either
|
||||
# running now or start in the future
|
||||
events = events.filter(date_from__gte=date.today())
|
||||
|
||||
# Order by date
|
||||
events = events.order_by('date_from')
|
||||
|
||||
return events
|
||||
|
||||
This example makes sure to limit the returned objects to pieces of content which make sense, specifically ones which have been published through Wagtail's admin interface (``live()``) and are children of this node (``descendant_of(self)``). By setting a ``subpage_types`` class property in your model, you can specify which models are allowed to be set as children, but Wagtail will allow any ``Page``-derived model by default. Regardless, it's smart for a parent model to provide an index filtered to make sense.
|
||||
|
||||
|
||||
Leaves
|
||||
``````
|
||||
Leaves are the pieces of content itself, a page which is consumable, and might just consist of a bunch of properties. A blog page leaf might have some body text and an image. A person page leaf might have a photo, a name, and an address.
|
||||
|
||||
It might be helpful for a leaf to provide a way to back up along the tree to a parent, such as in the case of breadcrumbs navigation. The tree might also be deep enough that a leaf's parent won't be included in general site navigation.
|
||||
|
||||
The model for the leaf could provide a function that traverses the tree in the opposite direction and returns an appropriate ancestor:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
class EventPage(Page):
|
||||
# ...
|
||||
def event_index(self):
|
||||
# Find closest ancestor which is an event index
|
||||
return self.get_ancestors().type(EventIndexPage).last()
|
||||
|
||||
If defined, ``subpage_types`` will also limit the parent models allowed to contain a leaf. If not, Wagtail will allow any combination of parents and leafs to be associated in the Wagtail tree. Like with index pages, it's a good idea to make sure that the index is actually of the expected model to contain the leaf.
|
||||
|
||||
|
||||
Other Relationships
|
||||
```````````````````
|
||||
Your ``Page``-derived models might have other interrelationships which extend the basic Wagtail tree or depart from it entirely. You could provide functions to navigate between siblings, such as a "Next Post" link on a blog page (``post->post->post``). It might make sense for subtrees to interrelate, such as in a discussion forum (``forum->post->replies``) Skipping across the hierarchy might make sense, too, as all objects of a certain model class might interrelate regardless of their ancestors (``events = EventPage.objects.all``). It's largely up to the models to define their interrelations, the possibilities are really endless.
|
||||
|
||||
|
||||
.. _anatomy_of_a_wagtail_request:
|
||||
|
||||
Anatomy of a Wagtail Request
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
For going beyond the basics of model definition and interrelation, it might help to know how Wagtail handles requests and constructs responses. In short, it goes something like:
|
||||
|
||||
#. Django gets a request and routes through Wagtail's URL dispatcher definitions
|
||||
#. Wagtail checks the hostname of the request to determine which ``Site`` record will handle this request.
|
||||
#. Starting from the root page of that site, Wagtail traverses the page tree, calling the ``route()`` method and letting each page model decide whether it will handle the request itself or pass it on to a child page.
|
||||
#. The page responsible for handling the request returns a ``RouteResult`` object from ``route()``, which identifies the page along with any additional args/kwargs to be passed to ``serve()``.
|
||||
#. Wagtail calls ``serve()``, which constructs a context using ``get_context()``
|
||||
#. ``serve()`` finds a template to pass it to using ``get_template()``
|
||||
#. A response object is returned by ``serve()`` and Django responds to the requester.
|
||||
|
||||
You can apply custom behavior to this process by overriding ``Page`` class methods such as ``route()`` and ``serve()`` in your own models. For examples, see :ref:`model_recipes`.
|
||||
|
||||
|
||||
Page Properties and Methods Reference
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
In addition to the model fields provided, ``Page`` has many properties and methods that you may wish to reference, use, or override in creating your own models. Those listed here are relatively straightforward to use, but consult the Wagtail source code for a full view of what's possible.
|
||||
|
||||
.. automodule:: wagtail.wagtailcore.models
|
||||
.. autoclass:: Page
|
||||
|
||||
.. autoattribute:: specific
|
||||
|
||||
.. autoattribute:: specific_class
|
||||
|
||||
.. autoattribute:: url
|
||||
|
||||
.. autoattribute:: full_url
|
||||
|
||||
.. automethod:: relative_url
|
||||
|
||||
.. automethod:: is_navigable
|
||||
|
||||
.. automethod:: route
|
||||
|
||||
.. automethod:: serve
|
||||
|
||||
.. automethod:: get_context
|
||||
|
||||
.. automethod:: get_template
|
||||
|
||||
.. autoattribute:: preview_modes
|
||||
|
||||
.. automethod:: serve_preview
|
||||
|
||||
.. automethod:: get_ancestors
|
||||
|
||||
.. automethod:: get_descendants
|
||||
|
||||
.. automethod:: get_siblings
|
||||
|
||||
.. automethod:: search
|
||||
|
||||
|
||||
Page Queryset Reference
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
All models that inherit from ``Page`` are given some extra Queryset methods accessible from their ``.objects`` attribute.
|
||||
|
||||
Examples:
|
||||
|
||||
- Selecting only live pages
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
live_pages = Page.objects.live()
|
||||
|
||||
- Selecting published EventPages that are descendants of events_index
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
events = EventPage.objects.live().descendant_of(events_index)
|
||||
|
||||
- Getting a list of menu items
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# This gets a queryset of live children of the homepage with ``show_in_menus`` set
|
||||
menu_items = homepage.get_children().live().in_menu()
|
||||
|
||||
|
||||
.. automodule:: wagtail.wagtailcore.query
|
||||
.. autoclass:: PageQuerySet
|
||||
|
||||
.. automethod:: live
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
published_pages = Page.objects.live()
|
||||
|
||||
.. automethod:: not_live
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
unpublished_pages = Page.objects.not_live()
|
||||
|
||||
.. automethod:: in_menu
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# Build a menu from live pages that are children of the homepage
|
||||
menu_items = homepage.get_children().live().in_menu()
|
||||
|
||||
|
||||
.. note::
|
||||
|
||||
To put your page in menus, set the show_in_menus flag to true:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# Add 'my_page' to the menu
|
||||
my_page.show_in_menus = True
|
||||
|
||||
.. automethod:: page
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# Append an extra page to a queryset
|
||||
new_queryset = old_queryset | Page.objects.page(page_to_add)
|
||||
|
||||
.. automethod:: not_page
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# Remove a page from a queryset
|
||||
new_queryset = old_queryset & Page.objects.not_page(page_to_remove)
|
||||
|
||||
.. automethod:: descendant_of
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# Get EventPages that are under the special_events Page
|
||||
special_events = EventPage.objects.descendant_of(special_events_index)
|
||||
|
||||
# Alternative way
|
||||
special_events = special_events_index.get_descendants()
|
||||
|
||||
.. automethod:: not_descendant_of
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# Get EventPages that are not under the archived_events Page
|
||||
non_archived_events = EventPage.objects.not_descendant_of(archived_events_index)
|
||||
|
||||
.. automethod:: child_of
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# Get a list of sections
|
||||
sections = Page.objects.child_of(homepage)
|
||||
|
||||
# Alternative way
|
||||
sections = homepage.get_children()
|
||||
|
||||
.. automethod:: ancestor_of
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# Get the current section
|
||||
current_section = Page.objects.ancestor_of(current_page).child_of(homepage).first()
|
||||
|
||||
# Alternative way
|
||||
current_section = current_page.get_ancestors().child_of(homepage).first()
|
||||
|
||||
.. automethod:: not_ancestor_of
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# Get the other sections
|
||||
other_sections = Page.objects.not_ancestor_of(current_page).child_of(homepage)
|
||||
|
||||
.. automethod:: sibling_of
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# Get list of siblings
|
||||
siblings = Page.objects.sibling_of(current_page)
|
||||
|
||||
# Alternative way
|
||||
siblings = current_page.get_siblings()
|
||||
|
||||
.. automethod:: public
|
||||
|
||||
See: :ref:`private_pages`
|
||||
|
||||
.. note::
|
||||
|
||||
This doesn't filter out unpublished pages. If you want to only have published public pages, use ``.live().public()``
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# Find all the pages that are viewable by the public
|
||||
all_pages = Page.objects.live().public()
|
||||
|
||||
.. automethod:: search
|
||||
|
||||
See: :ref:`wagtailsearch_for_python_developers`
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# Search future events
|
||||
results = EventPage.objects.live().filter(date__gt=timezone.now()).search("Hello")
|
||||
|
||||
|
||||
.. _wagtail_site_admin:
|
||||
|
||||
Site
|
||||
~~~~
|
||||
|
||||
Django's built-in admin interface provides the way to map a "site" (hostname or domain) to any node in the wagtail tree, using that node as the site's root.
|
||||
|
||||
Access this by going to ``/django-admin/`` and then "Home › Wagtailcore › Sites." To try out a development site, add a single site with the hostname ``localhost`` at port ``8000`` and map it to one of the pieces of content you have created.
|
||||
|
||||
Wagtail's developers plan to move the site settings into the Wagtail admin interface.
|
||||
|
||||
|
||||
.. _redirects:
|
||||
|
||||
Redirects
|
||||
~~~~~~~~~
|
||||
|
||||
Wagtail provides a simple interface for creating arbitrary redirects to and from any URL.
|
||||
|
||||
.. image:: ../images/screen_wagtail_redirects.png
|
||||
|
|
@ -1,11 +0,0 @@
|
|||
Building your site
|
||||
==================
|
||||
|
||||
.. note::
|
||||
This documentation is currently incomplete.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 3
|
||||
|
||||
djangodevelopers
|
||||
frontenddevelopers
|
||||
|
|
@ -0,0 +1,11 @@
|
|||
Contrib components
|
||||
==================
|
||||
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
static_site_generation
|
||||
sitemap_generation
|
||||
frontend_cache_purging
|
||||
|
||||
|
|
@ -0,0 +1,11 @@
|
|||
Core components
|
||||
===============
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
pages/index
|
||||
snippets
|
||||
search/index
|
||||
form_builder
|
||||
|
||||
|
|
@ -0,0 +1,180 @@
|
|||
=====================
|
||||
Page Queryset Methods
|
||||
=====================
|
||||
|
||||
All models that inherit from ``Page`` are given some extra Queryset methods accessible from their ``.objects`` attribute.
|
||||
|
||||
|
||||
Examples
|
||||
========
|
||||
|
||||
- Selecting only live pages
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
live_pages = Page.objects.live()
|
||||
|
||||
- Selecting published EventPages that are descendants of events_index
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
events = EventPage.objects.live().descendant_of(events_index)
|
||||
|
||||
- Getting a list of menu items
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# This gets a queryset of live children of the homepage with ``show_in_menus`` set
|
||||
menu_items = homepage.get_children().live().in_menu()
|
||||
|
||||
|
||||
Reference
|
||||
=========
|
||||
|
||||
.. automodule:: wagtail.wagtailcore.query
|
||||
.. autoclass:: PageQuerySet
|
||||
|
||||
.. automethod:: live
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
published_pages = Page.objects.live()
|
||||
|
||||
.. automethod:: not_live
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
unpublished_pages = Page.objects.not_live()
|
||||
|
||||
.. automethod:: in_menu
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# Build a menu from live pages that are children of the homepage
|
||||
menu_items = homepage.get_children().live().in_menu()
|
||||
|
||||
|
||||
.. note::
|
||||
|
||||
To put your page in menus, set the show_in_menus flag to true:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# Add 'my_page' to the menu
|
||||
my_page.show_in_menus = True
|
||||
|
||||
.. automethod:: page
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# Append an extra page to a queryset
|
||||
new_queryset = old_queryset | Page.objects.page(page_to_add)
|
||||
|
||||
.. automethod:: not_page
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# Remove a page from a queryset
|
||||
new_queryset = old_queryset & Page.objects.not_page(page_to_remove)
|
||||
|
||||
.. automethod:: descendant_of
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# Get EventPages that are under the special_events Page
|
||||
special_events = EventPage.objects.descendant_of(special_events_index)
|
||||
|
||||
# Alternative way
|
||||
special_events = special_events_index.get_descendants()
|
||||
|
||||
.. automethod:: not_descendant_of
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# Get EventPages that are not under the archived_events Page
|
||||
non_archived_events = EventPage.objects.not_descendant_of(archived_events_index)
|
||||
|
||||
.. automethod:: child_of
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# Get a list of sections
|
||||
sections = Page.objects.child_of(homepage)
|
||||
|
||||
# Alternative way
|
||||
sections = homepage.get_children()
|
||||
|
||||
.. automethod:: ancestor_of
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# Get the current section
|
||||
current_section = Page.objects.ancestor_of(current_page).child_of(homepage).first()
|
||||
|
||||
# Alternative way
|
||||
current_section = current_page.get_ancestors().child_of(homepage).first()
|
||||
|
||||
.. automethod:: not_ancestor_of
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# Get the other sections
|
||||
other_sections = Page.objects.not_ancestor_of(current_page).child_of(homepage)
|
||||
|
||||
.. automethod:: sibling_of
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# Get list of siblings
|
||||
siblings = Page.objects.sibling_of(current_page)
|
||||
|
||||
# Alternative way
|
||||
siblings = current_page.get_siblings()
|
||||
|
||||
.. automethod:: public
|
||||
|
||||
See: :ref:`private_pages`
|
||||
|
||||
.. note::
|
||||
|
||||
This doesn't filter out unpublished pages. If you want to only have published public pages, use ``.live().public()``
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# Find all the pages that are viewable by the public
|
||||
all_pages = Page.objects.live().public()
|
||||
|
||||
.. automethod:: search
|
||||
|
||||
See: :ref:`wagtailsearch_for_python_developers`
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# Search future events
|
||||
results = EventPage.objects.live().filter(date__gt=timezone.now()).search("Hello")
|
||||
|
|
@ -0,0 +1,134 @@
|
|||
====================
|
||||
Creating page models
|
||||
====================
|
||||
|
||||
|
||||
The Page Class
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
``Page`` uses Django's model interface, so you can include any field type and field options that Django allows. Wagtail provides some fields and editing handlers that simplify data entry in the Wagtail admin interface, so you may want to keep those in mind when deciding what properties to add to your models in addition to those already provided by ``Page``.
|
||||
|
||||
|
||||
Built-in Properties of the Page Class
|
||||
-------------------------------------
|
||||
|
||||
Wagtail provides some properties in the ``Page`` class which are common to most webpages. Since you'll be subclassing ``Page``, you don't have to worry about implementing them.
|
||||
|
||||
Public Properties
|
||||
`````````````````
|
||||
|
||||
``title`` (string, required)
|
||||
Human-readable title for the content
|
||||
|
||||
``slug`` (string, required)
|
||||
Machine-readable URL component for this piece of content. The name of the page as it will appear in URLs e.g ``http://domain.com/blog/[my-slug]/``
|
||||
|
||||
``seo_title`` (string)
|
||||
Alternate SEO-crafted title which overrides the normal title for use in the ``<head>`` of a page
|
||||
|
||||
``search_description`` (string)
|
||||
A SEO-crafted description of the content, used in both internal search indexing and for the meta description read by search engines
|
||||
|
||||
The ``Page`` class actually has alot more to it, but these are probably the only built-in properties you'll need to worry about when creating templates for your models.
|
||||
|
||||
|
||||
Anatomy of a Wagtail Model
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
So what does a Wagtail model definition look like? Here's a model representing a typical blog post:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from django.db import models
|
||||
|
||||
from wagtail.wagtailcore.models import Page
|
||||
from wagtail.wagtailcore.fields import RichTextField
|
||||
from wagtail.wagtailadmin.edit_handlers import FieldPanel
|
||||
from wagtail.wagtailimages.edit_handlers import ImageChooserPanel
|
||||
from wagtail.wagtailimages.models import Image
|
||||
|
||||
class BlogPage(Page):
|
||||
body = RichTextField()
|
||||
date = models.DateField("Post date")
|
||||
feed_image = models.ForeignKey(
|
||||
'wagtailimages.Image',
|
||||
null=True,
|
||||
blank=True,
|
||||
on_delete=models.SET_NULL,
|
||||
related_name='+'
|
||||
)
|
||||
|
||||
BlogPage.content_panels = [
|
||||
FieldPanel('title', classname="full title"),
|
||||
FieldPanel('date'),
|
||||
FieldPanel('body', classname="full"),
|
||||
]
|
||||
|
||||
BlogPage.promote_panels = [
|
||||
FieldPanel('slug'),
|
||||
FieldPanel('seo_title'),
|
||||
FieldPanel('show_in_menus'),
|
||||
FieldPanel('search_description'),
|
||||
ImageChooserPanel('feed_image'),
|
||||
]
|
||||
|
||||
To keep track of your ``Page``-derived models, it might be helpful to include "Page" as the last part of your class name. ``BlogPage`` defines three properties: ``body``, ``date``, and ``feed_image``. These are a mix of basic Django models (``DateField``), Wagtail fields (``RichTextField``), and a pointer to a Wagtail model (``Image``).
|
||||
|
||||
Next, the ``content_panels`` and ``promote_panels`` lists define the capabilities and layout of the Wagtail admin page edit interface. The lists are filled with "panels" and "choosers", which will provide a fine-grain interface for inputting the model's content. The ``ImageChooserPanel``, for instance, lets one browse the image library, upload new images, and input image metadata. The ``RichTextField`` is the basic field for creating web-ready website rich text, including text formatting and embedded media like images and video. The Wagtail admin offers other choices for fields, Panels, and Choosers, with the option of creating your own to precisely fit your content without workarounds or other compromises.
|
||||
|
||||
Your models may be even more complex, with methods overriding the built-in functionality of the ``Page`` to achieve webdev magic. Or, you can keep your models simple and let Wagtail's built-in functionality do the work.
|
||||
|
||||
Now that we have a basic idea of how our content is defined, lets look at relationships between pieces of content.
|
||||
|
||||
|
||||
Page Properties and Methods Reference
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
In addition to the model fields provided, ``Page`` has many properties and methods that you may wish to reference, use, or override in creating your own models. Those listed here are relatively straightforward to use, but consult the Wagtail source code for a full view of what's possible.
|
||||
|
||||
.. automodule:: wagtail.wagtailcore.models
|
||||
.. autoclass:: Page
|
||||
|
||||
.. autoattribute:: specific
|
||||
|
||||
.. autoattribute:: specific_class
|
||||
|
||||
.. autoattribute:: url
|
||||
|
||||
.. autoattribute:: full_url
|
||||
|
||||
.. automethod:: relative_url
|
||||
|
||||
.. automethod:: is_navigable
|
||||
|
||||
.. automethod:: route
|
||||
|
||||
.. automethod:: serve
|
||||
|
||||
.. automethod:: get_context
|
||||
|
||||
.. automethod:: get_template
|
||||
|
||||
.. autoattribute:: preview_modes
|
||||
|
||||
.. automethod:: serve_preview
|
||||
|
||||
.. automethod:: get_ancestors
|
||||
|
||||
.. automethod:: get_descendants
|
||||
|
||||
.. automethod:: get_siblings
|
||||
|
||||
.. automethod:: search
|
||||
|
||||
|
||||
.. _wagtail_site_admin:
|
||||
|
||||
Site
|
||||
~~~~
|
||||
|
||||
Django's built-in admin interface provides the way to map a "site" (hostname or domain) to any node in the wagtail tree, using that node as the site's root.
|
||||
|
||||
Access this by going to ``/django-admin/`` and then "Home › Wagtailcore › Sites." To try out a development site, add a single site with the hostname ``localhost`` at port ``8000`` and map it to one of the pieces of content you have created.
|
||||
|
||||
Wagtail's developers plan to move the site settings into the Wagtail admin interface.
|
||||
|
|
@ -0,0 +1,24 @@
|
|||
Pages
|
||||
=====
|
||||
|
||||
.. note::
|
||||
This documentation is currently being written.
|
||||
|
||||
Wagtail requires a little careful setup to define the types of content that you want to present through your website. The basic unit of content in Wagtail is the ``Page``, and all of your page-level content will inherit basic webpage-related properties from it. But for the most part, you will be defining content yourself, through the construction of Django models using Wagtail's ``Page`` as a base.
|
||||
|
||||
Wagtail organizes content created from your models in a tree, which can have any structure and combination of model objects in it. Wagtail doesn't prescribe ways to organize and interrelate your content, but here we've sketched out some strategies for organizing your models.
|
||||
|
||||
The presentation of your content, the actual webpages, includes the normal use of the Django template system. We'll cover additional functionality that Wagtail provides at the template level later on.
|
||||
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
theory
|
||||
creating_pages
|
||||
writing_templates
|
||||
model_recipes
|
||||
editing_api
|
||||
advanced_topics/queryset_methods
|
||||
advanced_topics/private_pages
|
||||
advanced_topics/routable_page
|
||||
|
|
@ -1,8 +1,8 @@
|
|||
|
||||
.. _model_recipes:
|
||||
|
||||
Model Recipes
|
||||
=============
|
||||
Recipes
|
||||
=======
|
||||
|
||||
Overriding the serve() Method
|
||||
-----------------------------
|
||||
|
|
@ -0,0 +1,95 @@
|
|||
======
|
||||
Theory
|
||||
======
|
||||
|
||||
|
||||
Introduction to Trees
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
If you're unfamiliar with trees as an abstract data type, you might want to `review the concepts involved. <http://en.wikipedia.org/wiki/Tree_(data_structure)>`_
|
||||
|
||||
As a web developer, though, you probably already have a good understanding of trees as filesystem directories or paths. Wagtail pages can create the same structure, as each page in the tree has its own URL path, like so::
|
||||
|
||||
/
|
||||
people/
|
||||
nien-nunb/
|
||||
laura-roslin/
|
||||
events/
|
||||
captain-picard-day/
|
||||
winter-wrap-up/
|
||||
|
||||
The Wagtail admin interface uses the tree to organize content for editing, letting you navigate up and down levels in the tree through its Explorer menu. This method of organization is a good place to start in thinking about your own Wagtail models.
|
||||
|
||||
|
||||
Nodes and Leaves
|
||||
----------------
|
||||
|
||||
It might be handy to think of the ``Page``-derived models you want to create as being one of two node types: parents and leaves. Wagtail isn't prescriptive in this approach, but it's a good place to start if you're not experienced in structuring your own content types.
|
||||
|
||||
|
||||
Nodes
|
||||
`````
|
||||
Parent nodes on the Wagtail tree probably want to organize and display a browse-able index of their descendants. A blog, for instance, needs a way to show a list of individual posts.
|
||||
|
||||
A Parent node could provide its own function returning its descendant objects.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
class EventPageIndex(Page):
|
||||
# ...
|
||||
def events(self):
|
||||
# Get list of live event pages that are descendants of this page
|
||||
events = EventPage.objects.live().descendant_of(self)
|
||||
|
||||
# Filter events list to get ones that are either
|
||||
# running now or start in the future
|
||||
events = events.filter(date_from__gte=date.today())
|
||||
|
||||
# Order by date
|
||||
events = events.order_by('date_from')
|
||||
|
||||
return events
|
||||
|
||||
This example makes sure to limit the returned objects to pieces of content which make sense, specifically ones which have been published through Wagtail's admin interface (``live()``) and are children of this node (``descendant_of(self)``). By setting a ``subpage_types`` class property in your model, you can specify which models are allowed to be set as children, but Wagtail will allow any ``Page``-derived model by default. Regardless, it's smart for a parent model to provide an index filtered to make sense.
|
||||
|
||||
|
||||
Leaves
|
||||
``````
|
||||
Leaves are the pieces of content itself, a page which is consumable, and might just consist of a bunch of properties. A blog page leaf might have some body text and an image. A person page leaf might have a photo, a name, and an address.
|
||||
|
||||
It might be helpful for a leaf to provide a way to back up along the tree to a parent, such as in the case of breadcrumbs navigation. The tree might also be deep enough that a leaf's parent won't be included in general site navigation.
|
||||
|
||||
The model for the leaf could provide a function that traverses the tree in the opposite direction and returns an appropriate ancestor:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
class EventPage(Page):
|
||||
# ...
|
||||
def event_index(self):
|
||||
# Find closest ancestor which is an event index
|
||||
return self.get_ancestors().type(EventIndexPage).last()
|
||||
|
||||
If defined, ``subpage_types`` will also limit the parent models allowed to contain a leaf. If not, Wagtail will allow any combination of parents and leafs to be associated in the Wagtail tree. Like with index pages, it's a good idea to make sure that the index is actually of the expected model to contain the leaf.
|
||||
|
||||
|
||||
Other Relationships
|
||||
```````````````````
|
||||
Your ``Page``-derived models might have other interrelationships which extend the basic Wagtail tree or depart from it entirely. You could provide functions to navigate between siblings, such as a "Next Post" link on a blog page (``post->post->post``). It might make sense for subtrees to interrelate, such as in a discussion forum (``forum->post->replies``) Skipping across the hierarchy might make sense, too, as all objects of a certain model class might interrelate regardless of their ancestors (``events = EventPage.objects.all``). It's largely up to the models to define their interrelations, the possibilities are really endless.
|
||||
|
||||
|
||||
.. _anatomy_of_a_wagtail_request:
|
||||
|
||||
Anatomy of a Wagtail Request
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
For going beyond the basics of model definition and interrelation, it might help to know how Wagtail handles requests and constructs responses. In short, it goes something like:
|
||||
|
||||
#. Django gets a request and routes through Wagtail's URL dispatcher definitions
|
||||
#. Wagtail checks the hostname of the request to determine which ``Site`` record will handle this request.
|
||||
#. Starting from the root page of that site, Wagtail traverses the page tree, calling the ``route()`` method and letting each page model decide whether it will handle the request itself or pass it on to a child page.
|
||||
#. The page responsible for handling the request returns a ``RouteResult`` object from ``route()``, which identifies the page along with any additional args/kwargs to be passed to ``serve()``.
|
||||
#. Wagtail calls ``serve()``, which constructs a context using ``get_context()``
|
||||
#. ``serve()`` finds a template to pass it to using ``get_template()``
|
||||
#. A response object is returned by ``serve()`` and Django responds to the requester.
|
||||
|
||||
You can apply custom behavior to this process by overriding ``Page`` class methods such as ``route()`` and ``serve()`` in your own models. For examples, see :ref:`model_recipes`.
|
||||
|
|
@ -3,14 +3,14 @@ Documents
|
|||
|
||||
Documents such as PDFs can be managed from the Documents interface, available in the left-hand menu. This interface allows you to add documents to and remove documents from the CMS.
|
||||
|
||||
.. image:: ../../images/screen29_documents_page.png
|
||||
.. image:: ../../_static/images/screen29_documents_page.png
|
||||
|
||||
* Add documents by clicking the *Add document* button in the top-right.
|
||||
* Search for documents in the CMS by entering your search term in the search bar. The results will be automatically updated as you type.
|
||||
* You can also filter the results by *Popular tags*. Click on a tag to update the search results listing.
|
||||
* Edit the details of a document by clicking the document title.
|
||||
|
||||
.. image:: ../../images/screen30_documents_edit_page.png
|
||||
.. image:: ../../_static/images/screen30_documents_edit_page.png
|
||||
|
||||
* When editing a document you can replace the file associated with that document record. This means you can update documents without having to update the pages on which they are placed. Changing the file will change it on all pages that use the document.
|
||||
* Add or remove tags using the Tags field.
|
||||
|
|
|
|||
|
|
@ -3,11 +3,11 @@ Images
|
|||
|
||||
If you want to edit, add or remove images from the CMS outside of the individual pages you can do so from the Images interface. This is accessed from the left-hand menu.
|
||||
|
||||
.. image:: ../../images/screen31_images_page.png
|
||||
.. image:: ../../_static/images/screen31_images_page.png
|
||||
|
||||
* Clicking an image will allow you to edit the data associated with it. This includes the Alt text, the photographers credit, the medium of the subject matter and much more. **NOTE:** changing the alt text here will alter it for all occurrences of the image in carousels, but not in inline images, where the alt text can be set separately.
|
||||
|
||||
.. image:: ../../images/screen32_image_edit_page.png
|
||||
.. image:: ../../_static/images/screen32_image_edit_page.png
|
||||
|
||||
* When editing an image you can replace the file associated with that image record. This means you can update images without having to update the pages on which they are placed. Changing the file will change it on all pages that use the image.
|
||||
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@ There are two ways that you can access the edit screen of an existing page:
|
|||
* Clicking the title of the page in an `Explorer page <the_explorer_page.html>`_ or in `search results <using_search.html>`_.
|
||||
* Clicking the *Edit* link below the title in either of the situations above.
|
||||
|
||||
.. image:: ../images/screen12_edit_screen_overview.png
|
||||
.. image:: ../_static/images/screen12_edit_screen_overview.png
|
||||
|
||||
* When editing an existing page the title of the page being edited is displayed at the top of the page.
|
||||
* The current status of the page is displayed in the top-right.
|
||||
|
|
|
|||
|
|
@ -11,7 +11,7 @@ The Dashboard provides information on:
|
|||
|
||||
You can return to the Dashboard at any time by clicking the Wagtail log in the top-left of the screen.
|
||||
|
||||
.. image:: ../../images/screen02_dashboard_editor.png
|
||||
.. image:: ../../_static/images/screen02_dashboard_editor.png
|
||||
|
||||
- Clicking the logo returns you to your Dashboard.
|
||||
- Thes stats at the top of the page describe the total amount of content on the CMS (just for fun!).
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
The Explorer menu
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. image:: ../../images/screen03_explorer_menu.png
|
||||
.. image:: ../../_static/images/screen03_explorer_menu.png
|
||||
|
||||
* Click the Explorer button in the sidebar to open the site explorer. This allows you to navigate through the tree-structure of the site.
|
||||
* Clicking the name of a page will take you to the Explorer page for that section (see below). NOTE: The site explorer only displays pages which themselves have child pages. To see and edit the child pages you should click the name of the parent page in the site explorer.
|
||||
|
|
|
|||
|
|
@ -4,20 +4,20 @@ The Explorer page
|
|||
The Explorer page allows you to view the a page's children and perform actions on them. From here you can publish/unpublish pages, move pages to other sections, drill down further into the content tree, or reorder pages under the parent for the purposes of display in menus.
|
||||
|
||||
|
||||
.. image:: ../../images/screen05_explorer_page.png
|
||||
.. image:: ../../_static/images/screen05_explorer_page.png
|
||||
|
||||
* The name of the section you are looking at is displayed below the breadcrumb (the row of page names beginning with the home icon). Each section is also itself a page (in this case the homepage). Clicking the title of the section takes you to the Edit screen for the section page.
|
||||
* As the heading suggests, below are the child pages of the section. Clicking the titles of each child page will take you to its Edit screen.
|
||||
|
||||
.. image:: ../../images/screen06_explorer_page_arrow.png
|
||||
.. image:: ../../_static/images/screen06_explorer_page_arrow.png
|
||||
|
||||
* Clicking the arrows will display a further level of child pages.
|
||||
|
||||
.. image:: ../../images/screen07_explorer_page_breadcrumb.png
|
||||
.. image:: ../../_static/images/screen07_explorer_page_breadcrumb.png
|
||||
|
||||
* As you drill down through the site the breadcrumb (the row of pages beginning with the home icon) will display the path you have taken. Clicking on the page titles in the breadcrumb will take you to the Explorer screen for that page.
|
||||
|
||||
.. image:: ../../images/screen08_add_page_button.png
|
||||
.. image:: ../../_static/images/screen08_add_page_button.png
|
||||
|
||||
* To add further child pages press the Add child page button below the parent page title. You can view the parent page on the live site by pressing the View live button. The Move button will take you to the Move page screen where you can reposition the page and all its child pages in the site structure.
|
||||
* Similar buttons are available for each child page. These are made visible on hover.
|
||||
|
|
@ -25,7 +25,7 @@ The Explorer page allows you to view the a page's children and perform actions o
|
|||
Reordering pages
|
||||
________________
|
||||
|
||||
.. image:: ../../images/screen08.5_reorder_page_handles.png
|
||||
.. image:: ../../_static/images/screen08.5_reorder_page_handles.png
|
||||
|
||||
* Clicking the icon to the far left of the child pages table will enable the reordering handles. This allows you to reorder the way that content displays in the main menu of your website.
|
||||
* Reorder by dragging the pages by the handles on the far left (the icon made up of 8 dots).
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
Using search
|
||||
~~~~~~~~~~~~
|
||||
|
||||
.. image:: ../../images/screen04_search_screen.png
|
||||
.. image:: ../../_static/images/screen04_search_screen.png
|
||||
|
||||
* A very easy way to find the page that you want is to use the main search feature, accessible from the left-hand menu.
|
||||
* Simply type in part or all of the name of the page you are looking for, and the results below will automatically update as you type.
|
||||
|
|
|
|||
|
|
@ -15,4 +15,4 @@ __________
|
|||
* Access this by adding **/admin** onto the end of your root URL (e.g. www.example.com/admin).
|
||||
* Enter your username and password and click **Sign in**.
|
||||
|
||||
.. image:: ../images/screen01_login.png
|
||||
.. image:: ../_static/images/screen01_login.png
|
||||
|
|
@ -3,15 +3,15 @@ Adding multiple items
|
|||
|
||||
A common feature of Wagtail is the ability to add more than one of a particular type of field or item. For example, you can add as many carousel items or related links as you wish.
|
||||
|
||||
.. image:: ../../images/screen24_multiple_items_closed.png
|
||||
.. image:: ../../_static/images/screen24_multiple_items_closed.png
|
||||
|
||||
* Whenever you see the white cross in the green circle illustrated here it means you can add multiple objects or items to a page. Clicking the icon will display the fields required for that piece of content. The image below demonstrates this with a *Related link* item.
|
||||
|
||||
.. image:: ../../images/screen25_multiple_items_open.png
|
||||
.. image:: ../../_static/images/screen25_multiple_items_open.png
|
||||
|
||||
* You can delete an individual item by pressing the trash can in the top-right.
|
||||
* You can add more items by clicking the link with the white cross again.
|
||||
|
||||
.. image:: ../../images/screen26_reordering_multiple_items.png
|
||||
.. image:: ../../_static/images/screen26_reordering_multiple_items.png
|
||||
|
||||
4. You can reorder your multiple items using the up and down arrows. Doing this will affect the order in which they are display on the live page.
|
||||
|
|
@ -7,34 +7,34 @@ There are two types of text entry fields you will see when creating a page. Some
|
|||
|
||||
So, when you click into certain fields, for example the *Body* field, you will be presented with a set of tools which allow you to format and style your text. These tools also allow you to insert links, images, videos clips and links to documents.
|
||||
|
||||
.. image:: ../../images/screen11_rich_text_field.png
|
||||
.. image:: ../../_static/images/screen11_rich_text_field.png
|
||||
|
||||
Below is a summary of what the different buttons represent:
|
||||
|
||||
.. image:: ../../images/screen11.1_bold_italic.png
|
||||
.. image:: ../../_static/images/screen11.1_bold_italic.png
|
||||
|
||||
**Bold / Italic:** Either click then type for bold or italic, or highlight and select to convert existing text to bold or italic.
|
||||
|
||||
.. image:: ../../images/screen11.2_formatting_options.png
|
||||
.. image:: ../../_static/images/screen11.2_formatting_options.png
|
||||
|
||||
**Paragraph / heading levels:** Clicking into a paragraph and selecting one of these options will change the level of the text. H1 is not included as this is reserved for the page title.
|
||||
|
||||
.. image:: ../../images/screen11.3_lists.png
|
||||
.. image:: ../../_static/images/screen11.3_lists.png
|
||||
|
||||
**Bulleted and numbered lists**
|
||||
|
||||
.. image:: ../../images/screen11.4_horizontal_rule.png
|
||||
.. image:: ../../_static/images/screen11.4_horizontal_rule.png
|
||||
|
||||
**Horizontal rule:** Creates a horizontal line at the position of the cursor. If inserted inside a paragraph it will split the paragraph into two seperate paragraphs.
|
||||
|
||||
.. image:: ../../images/screen11.5_undo_redo.png
|
||||
.. image:: ../../_static/images/screen11.5_undo_redo.png
|
||||
|
||||
**Undo / redo:** As expected will undo or redo the latest actions. Never use the your browser's back button when attempting to undo changes as this could lead to errors. Either use this undo button, or the usual keyboard shortcut, CTRL+Z.
|
||||
|
||||
.. image:: ../../images/screen11.6_images_videos.png
|
||||
.. image:: ../../_static/images/screen11.6_images_videos.png
|
||||
|
||||
**Insert image / video:** Allows you to insert an image or video into the rich text field. See Inserting images and videos section for more details. .. insert links for images and videos here>>
|
||||
|
||||
.. image:: ../../images/screen11.7_links_docs.png
|
||||
.. image:: ../../_static/images/screen11.7_links_docs.png
|
||||
|
||||
**Insert link / document:** Allows you to insert a link or a document into the rich text field. See Inserting links and Inserting documents for more details. .. insert links to Links and documents sections>>
|
||||
|
|
@ -1,7 +1,7 @@
|
|||
Creating new pages
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. image:: ../../images/screen08_add_page_button.png
|
||||
.. image:: ../../_static/images/screen08_add_page_button.png
|
||||
|
||||
Create new pages by clicking the Add child page. This creates a child page of the section you are currently in. In this case a child page of the Homepage.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,10 +1,10 @@
|
|||
Inserting links to documents into body text
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. image:: ../../images/screen27_docs_icon.png
|
||||
.. image:: ../../_static/images/screen27_docs_icon.png
|
||||
|
||||
It is possible to insert links to documents held in the CMS into the body text of a web page by clicking the button above in the Body field.
|
||||
|
||||
The process for doing this is the same as when inserting an image. You are given the choice of either choosing a document from the CMS, or uploading a new document.
|
||||
|
||||
.. image:: ../../images/screen28_docs_form.png
|
||||
.. image:: ../../_static/images/screen28_docs_form.png
|
||||
|
|
@ -11,11 +11,11 @@ __________________________________
|
|||
|
||||
The carousel is where the main, featured images and videos associated with a page should be displayed.
|
||||
|
||||
.. image:: ../../images/screen14_add_carousel_button.png
|
||||
.. image:: ../../_static/images/screen14_add_carousel_button.png
|
||||
|
||||
* To insert a carousel item click the Add carousel content link in the Carousel content section.
|
||||
|
||||
.. image:: ../../images/screen15_carousel_form.png
|
||||
.. image:: ../../_static/images/screen15_carousel_form.png
|
||||
|
||||
* You can then insert an image by clicking the *Choose an image* button.
|
||||
* It is also possible to add videos to a carousel. Simply copy and paste the web address for the video (either YouTube or Vimeo) into the *Embed URL* field and click Insert. A poster image for the video can also be uploaded or selected from the CMS. This is the image displayed before a user has clicked play on the video.
|
||||
|
|
@ -38,7 +38,7 @@ When you click the *Choose an image* button you will be presented with a pop-up
|
|||
|
||||
The image below demonstrates finding and inserting an image that is already present in the CMS image library.
|
||||
|
||||
.. image:: ../../images/screen16_selecting_image_from_library.png
|
||||
.. image:: ../../_static/images/screen16_selecting_image_from_library.png
|
||||
|
||||
#. Typing into the search box will automatically display the results below.
|
||||
#. Clicking one of the Popular tags will filter the search results by that tag.
|
||||
|
|
@ -46,7 +46,7 @@ The image below demonstrates finding and inserting an image that is already pre
|
|||
|
||||
**Uploading a new image to the CMS**
|
||||
|
||||
.. image:: ../../images/screen17_upload_image.png
|
||||
.. image:: ../../_static/images/screen17_upload_image.png
|
||||
|
||||
#. You must include an image title for your uploaded image
|
||||
#. Click the *Choose file* button to choose an image from your computer.
|
||||
|
|
@ -60,7 +60,7 @@ Images can also be inserted into the body text of a page. When editing the Body
|
|||
|
||||
In addition, the Wagtail Demo site allows you to chose an aligmnent for you image.
|
||||
|
||||
.. image:: ../../images/screen18_image_alignment.png
|
||||
.. image:: ../../_static/images/screen18_image_alignment.png
|
||||
|
||||
#. You can select how the image is displayed by selecting one of the format options.
|
||||
#. In the Wagtail Demo site, images inserted into the body text do not have embeded captions (these should be added as regular body text). However you must still provide specific alt text for your image.
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@ Similar to images, there are a variety of points at which you will want to add l
|
|||
|
||||
Whichever way you insert a link, you will be presented with the form displayed below.
|
||||
|
||||
.. image:: ../../images/screen19_link_form.png
|
||||
.. image:: ../../_static/images/screen19_link_form.png
|
||||
|
||||
* Search for an existing page to link to using the search bar at the top of the pop-up.
|
||||
* Below the search bar you can select the type of link you want to insert. The following types are available:
|
||||
|
|
|
|||
|
|
@ -6,10 +6,10 @@ Inserting videos into body content
|
|||
|
||||
As well as inserting videos into a carousel, Wagtail's rich text fields allow you to add videos into the body of a page by clicking the *Add video* button in the toolbar.
|
||||
|
||||
.. image:: ../../images/screen20_insert_video_form.png
|
||||
.. image:: ../../_static/images/screen20_insert_video_form.png
|
||||
|
||||
* Copy and paste the web address for the video (either YouTube or Vimeo) into the URL field and click Insert.
|
||||
|
||||
.. image:: ../../images/screen21_video_in_editor.png
|
||||
.. image:: ../../_static/images/screen21_video_in_editor.png
|
||||
|
||||
* A placeholder with the name of the video and a screenshot will be inserted into the text area. Clicking the X in the top corner will remove the video.
|
||||
|
|
|
|||
|
|
@ -9,4 +9,4 @@ The Save/Preview/Submit for moderation menu is always present at the bottom of t
|
|||
* **Publish/Unpublish:** Clicking either the *Publish* or *Unpublish* buttons will take you to a confirmation screen asking you to confirm that you wish to publish or unpublish this page. If a page is published it will be accessible from its specific URL and will also be displayed in site search results. (moderators and administrators only)
|
||||
* **Delete:** Clicking this button will take you to a confirmation screen asking you to confirm that you wish to delete the current page. Be sure that this is actually what you want to do, as deleted pages are not recoverable. In many situations simply unpublishing the page will be enough. (moderators and administrators only)
|
||||
|
||||
.. image:: ../../images/screen13_publish_menu.png
|
||||
.. image:: ../../_static/images/screen13_publish_menu.png
|
||||
|
|
|
|||
|
|
@ -3,9 +3,9 @@ Required fields
|
|||
|
||||
* Fields marked with an asterisk are required. You will not be able to save a draft or submit the page for moderation without these fields being completed.
|
||||
|
||||
.. image:: ../../images/screen22_required_field.png
|
||||
.. image:: ../../_static/images/screen22_required_field.png
|
||||
|
||||
* If you try to save/submit the page with some required fields not filled out, you will see the error displayed here.
|
||||
* The number of validation errors for each of the *Promote* and *Content* tabs will appear in a red circle, and the text, 'This field is required', will appear below each field that must be completed.
|
||||
|
||||
.. image:: ../../images/screen23_validation_error.png
|
||||
.. image:: ../../_static/images/screen23_validation_error.png
|
||||
|
|
|
|||
|
|
@ -1,12 +1,12 @@
|
|||
Selecting a page type
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. image:: ../../images/screen09_page_type_selection.png
|
||||
.. image:: ../../_static/images/screen09_page_type_selection.png
|
||||
|
||||
* On the left of the page chooser screen are listed all the types of pages that you can create. Clicking the page type name will take you to the Create new page screen for that page type (see below).
|
||||
* Clicking the *View all … pages* links on the right will display all the pages that exist on the website of this type. This is to help you judge what type of page you will need to complete your task.
|
||||
|
||||
.. image:: ../../images/screen10_blank_page_edit_screen.png
|
||||
.. image:: ../../_static/images/screen10_blank_page_edit_screen.png
|
||||
|
||||
* Once you’ve selected a page type you will be presented with a blank New page screen.
|
||||
* Click into the areas below each field's heading to start entering content.
|
||||
|
|
@ -4,7 +4,7 @@ Deploying Wagtail
|
|||
On your server
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
Wagtail is straightforward to deploy on modern Linux-based distributions, but see the section on :doc:`performance </performance>` for the non-Python services we recommend. If you are running Debian or Ubuntu, this installation script for our Vagrant box may be useful:
|
||||
Wagtail is straightforward to deploy on modern Linux-based distributions, but see the section on :doc:`performance </howto/performance>` for the non-Python services we recommend. If you are running Debian or Ubuntu, this installation script for our Vagrant box may be useful:
|
||||
|
||||
`github.com/torchbox/wagtaildemo/blob/master/etc/install/install.sh <https://github.com/torchbox/wagtaildemo/blob/master/etc/install/install.sh>`_
|
||||
|
||||
|
|
@ -18,4 +18,4 @@ On Gondor
|
|||
On other PAASs and IAASs
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
We know of Wagtail sites running on `Heroku <http://spapas.github.io/2014/02/13/wagtail-tutorial/>`_, Digital Ocean and elsewhere. If you have successfully installed Wagtail on your platform or infrastructure, please :doc:`contribute </contributing>` your notes to this documentation!
|
||||
We know of Wagtail sites running on `Heroku <http://spapas.github.io/2014/02/13/wagtail-tutorial/>`_, Digital Ocean and elsewhere. If you have successfully installed Wagtail on your platform or infrastructure, please :doc:`contribute </howto/contributing>` your notes to this documentation!
|
||||
|
|
@ -0,0 +1,11 @@
|
|||
How to
|
||||
======
|
||||
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
settings
|
||||
deploying
|
||||
performance
|
||||
contributing
|
||||
|
|
@ -9,24 +9,10 @@ It supports Django 1.6.2+ on Python 2.6, 2.7, 3.2, 3.3 and 3.4. Django 1.7 suppo
|
|||
:maxdepth: 3
|
||||
|
||||
gettingstarted
|
||||
settings
|
||||
building_your_site/index
|
||||
editing_api
|
||||
snippets
|
||||
search/index
|
||||
form_builder
|
||||
model_recipes
|
||||
routable_page
|
||||
advanced_topics
|
||||
deploying
|
||||
performance
|
||||
private_pages
|
||||
static_site_generation
|
||||
frontend_cache_purging
|
||||
sitemap_generation
|
||||
management_commands
|
||||
contributing
|
||||
core_components/index
|
||||
contrib_components/index
|
||||
howto/index
|
||||
reference/index
|
||||
support
|
||||
roadmap
|
||||
editor_manual/index
|
||||
releases/index
|
||||
|
|
|
|||
|
|
@ -0,0 +1,8 @@
|
|||
=========
|
||||
Reference
|
||||
=========
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
management_commands
|
||||
|
|
@ -4,6 +4,7 @@ Release notes
|
|||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
roadmap
|
||||
0.5
|
||||
0.4.1
|
||||
0.4
|
||||
|
|
|
|||
Ładowanie…
Reference in New Issue