mirrors/wagtail
mirrors/wagtail
0
0
Fork 0
mirror of https://github.com/wagtail/wagtail.git synced 2024-12-01 11:41:20 +01:00
Code Issues Releases Wiki Activity

Merge pull request #1011 from kaedroho/docs-pages

Browse Source 
Pages docs changes
This commit is contained in:
Karl Hobley 2015-02-20 11:42:34 +00:00
commit 55575e622c
5 changed files with 69 additions and 133 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

110
docs/core_components/pages/creating_pages.rst
View File

@ -2,9 +2,16 @@
Creating page models
====================
Wagtail provides a ``Page`` class to represent types of page (a.k.a Content types). Developers should subclass ``Page`` for their own page models.
Each page type (a.k.a Content type) in Wagtail is represented by a Django model. All page models must inherit from the ``wagtail.wagtailcore.models.Page`` class.
``Page`` uses Django's model interface, so you can include any field type and field options that Django allows. Wagtail provides some field types of its own which simplify data entry in the Wagtail admin interface. Wagtail also wraps Django's field types and widgets with its own concept of "Edit Handlers" and "Panels". These further improve the data entry experience.
As all page types are Django models, you can use any field type that Django provides. See `Model field reference <https://docs.djangoproject.com/en/1.7/ref/models/fields/>`_ for a complete list of field types you can use. Wagtail also provides ``RichTextField`` which provides a WYSIWYG editor for editing rich-text content.
.. topic:: Django models
If you're not yet familiar with Django models, have a quick look at the following links to get you started:
`Creating models <https://docs.djangoproject.com/en/1.7/intro/tutorial01/#creating-models>`_
`Model syntax <https://docs.djangoproject.com/en/1.7/topics/db/models/>`_
An example Wagtail Page Model
@ -21,6 +28,7 @@ This example represents a typical blog post:
from wagtail.wagtailadmin.edit_handlers import FieldPanel
from wagtail.wagtailimages.edit_handlers import ImageChooserPanel
class BlogPage(Page):
body = RichTextField()
date = models.DateField("Post date")
@ -32,8 +40,6 @@ This example represents a typical blog post:
related_name='+'
)
BlogPage.content_panels = [
FieldPanel('title', classname="full title"),
FieldPanel('date'),
@ -81,73 +87,6 @@ Wagtail provides some fields for the ``Page`` class by default, which will be co
``show_in_menus`` (boolean)
Toggles whether the page should be considered for inclusion in any site-wide menus you create.
``go_live_at`` (datetime)
A datetime on which the page should be automatically made published (made publicly accessible)
``expire_at`` (datetime)
A datetime on which the page should be unpublished, rendering it inaccessible to the public.
Page Attributes, 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:: get_verbose_name
.. 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
.. attribute:: search_fields
A list of fields to be indexed by the search engine. See Search docs :ref:`wagtailsearch_indexing_fields`
.. attribute:: subpage_types
A whitelist of page models which can be created as children of this page type e.g a ``BlogIndex`` page might allow ``BlogPage``, but not ``JobPage`` e.g
.. code-block:: python
class BlogIndex(Page):
subpage_types = ['mysite.BlogPage', 'mysite.BlogArchivePage']
.. attribute:: password_required_template
Defines which template file should be used to render the login form for Protected pages using this model. This overrides the default, defined using ``PASSWORD_REQUIRED_TEMPLATE`` in your settings. See :ref:`private_pages`
Tips
~~~~
@ -165,32 +104,3 @@ Make your model names more friendly to users of Wagtail using Django's internal
verbose_name = "Homepage"
When users are given a choice of pages to create, the list of page types is generated by splitting your model names on each of their capital letters. Thus a ``HomePage`` model would be named "Home Page" which is a little clumsy. ``verbose_name`` as in the example above, would change this to read "Homepage" which is slightly more conventional.
Helpful model descriptions
--------------------------
As your site becomes more complex users may require some prompting in deciding which content type to use when creating a new page. Developers can add a description to their Models by extending Django's internal model ``Meta`` class.
Insert the following once at the top of your ``models.py``:
.. code-block:: python
import django.db.models.options as options
options.DEFAULT_NAMES = options.DEFAULT_NAMES + ('description',)
Then for each model as necessary, add a description option to the model ``Meta`` class
.. code-block:: python
class HomePage(Page):
...
class Meta:
description = "The top level homepage for your site"
verbose_name = "Homepage"
(This method can be used to extend the Model Meta class in various ways however Wagtail only supports the addition of a ``description`` option).

12
docs/core_components/pages/editing_api.rst
View File

@ -693,15 +693,3 @@ To begin, import the the ``Format`` class, ``register_image_format`` function, a
To unregister, call ``unregister_image_format`` with the string of the ``name`` of the ``Format`` as the only argument.
Content Index Pages (CRUD)
--------------------------
Custom Choosers
---------------
Tests
-----

21
docs/core_components/pages/model_recipes.rst
View File

@ -198,24 +198,3 @@ Here, ``blogs.filter(tags__name=tag)`` invokes a reverse Django queryset filter
Iterating through ``self.tags.all`` will display each tag associated with ``self``, while the link(s) back to the index make use of the filter option added to the ``BlogIndexPage`` model. A Django query could also use the ``tagged_items`` related name field to get ``BlogPage`` objects associated with a tag.
This is just one possible way of creating a taxonomy for Wagtail objects. With all of the components for a taxonomy available through Wagtail, you should be able to fulfill even the most exotic taxonomic schemes.
Custom Page Contexts by Overriding get_context()
------------------------------------------------
Load Alternate Templates by Overriding get_template()
-----------------------------------------------------
Preview Modes
-------------
preview_modes
serve_preview

1
docs/reference/index.rst
View File

@ -7,3 +7,4 @@ Reference
management_commands
project_template
page

58
docs/reference/page.rst Normal file
View File

@ -0,0 +1,58 @@
Page Attributes, 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:: get_verbose_name
.. 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
.. attribute:: search_fields
A list of fields to be indexed by the search engine. See Search docs :ref:`wagtailsearch_indexing_fields`
.. attribute:: subpage_types
A whitelist of page models which can be created as children of this page type e.g a ``BlogIndex`` page might allow ``BlogPage``, but not ``JobPage`` e.g
.. code-block:: python
class BlogIndex(Page):
subpage_types = ['mysite.BlogPage', 'mysite.BlogArchivePage']
.. attribute:: password_required_template
Defines which template file should be used to render the login form for Protected pages using this model. This overrides the default, defined using ``PASSWORD_REQUIRED_TEMPLATE`` in your settings. See :ref:`private_pages`