mirror of
https://github.com/Hopiu/wagtail.git
synced 2026-05-04 13:34:46 +00:00
Merge pull request #1107 from kaedroho/docs-restructure-2
Docs restructure
This commit is contained in:
Karl Hobley
commit
c7f860f17a
11 changed files with 288 additions and 289 deletions
|
|
@ -7,15 +7,16 @@ Wagtail ships with a variety of extra optional modules.
|
|||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
static_site_generation
|
||||
sitemap_generation
|
||||
staticsitegen
|
||||
sitemaps
|
||||
frontendcache
|
||||
routablepage
|
||||
|
||||
|
||||
``wagtailmedusa``
|
||||
-----------------
|
||||
|
||||
:doc:`static_site_generation`
|
||||
:doc:`staticsitegen`
|
||||
|
||||
Provides a management command that turns a Wagtail site into a set of static HTML files.
|
||||
|
||||
|
|
@ -23,7 +24,7 @@ Provides a management command that turns a Wagtail site into a set of static HTM
|
|||
``wagtailsitemaps``
|
||||
-------------------
|
||||
|
||||
:doc:`sitemap_generation`
|
||||
:doc:`sitemaps`
|
||||
|
||||
Provides a view that generates a Google XML sitemap of your public wagtail content.
|
||||
|
||||
|
|
@ -34,3 +35,11 @@ Provides a view that generates a Google XML sitemap of your public wagtail conte
|
|||
:doc:`frontendcache`
|
||||
|
||||
A module for automatically purging pages from a cache (Varnish, Squid or Cloudflare) when their content is changed.
|
||||
|
||||
|
||||
``wagtailroutablepage``
|
||||
-----------------------
|
||||
|
||||
:doc:`routablepage`
|
||||
|
||||
Provides a way of embedding Django URLconfs into pages.
|
||||
|
|
|
|||
|
|
@ -14,7 +14,7 @@ Below are some useful links to help you get started with Wagtail.
|
|||
|
||||
* **Creating your Wagtail site**
|
||||
* :doc:`pages/creating_pages`
|
||||
* :doc:`Writing templates <pages/writing_templates>`
|
||||
* :doc:`pages/writing_templates`
|
||||
* :doc:`images/index`
|
||||
* :doc:`search/index`
|
||||
* :doc:`howto/third_party_tutorials`
|
||||
|
|
@ -33,7 +33,6 @@ Index
|
|||
:titlesonly:
|
||||
|
||||
getting_started/index
|
||||
sites
|
||||
pages/index
|
||||
images/index
|
||||
snippets
|
||||
|
|
|
|||
|
|
@ -1,10 +1,7 @@
|
|||
.. _editing-api:
|
||||
|
||||
Displaying fields with the Editing API
|
||||
======================================
|
||||
|
||||
.. note::
|
||||
This documentation is currently being written.
|
||||
Setting up the page editor interface
|
||||
====================================
|
||||
|
||||
Wagtail provides a highly-customizable editing interface consisting of several components:
|
||||
|
||||
|
|
@ -34,7 +31,7 @@ There are four basic types of panels:
|
|||
``InlinePanel( relation_name, panels=None, classname=None, label='', help_text='' )``
|
||||
This panel allows for the creation of a "cluster" of related objects over a join to a separate model, such as a list of related links or slides to an image carousel. This is a very powerful, but tricky feature which will take some space to cover, so we'll skip over it for now. For a full explanation on the usage of ``InlinePanel``, see :ref:`inline_panels`.
|
||||
|
||||
``FieldRowPanel( children, classname=None)``
|
||||
``FieldRowPanel( children, classname=None )``
|
||||
This panel is purely aesthetic. It creates a columnar layout in the editing interface, where each of the child Panels appears alongside each other rather than below. Use of FieldRowPanel particularly helps reduce the "snow-blindness" effect of seeing so many fields on the page, for complex models. It also improves the perceived association between fields of a similar nature. For example if you created a model representing an "Event" which had a starting date and ending date, it may be intuitive to find the start and end date on the same "row".
|
||||
|
||||
FieldRowPanel should be used in combination with ``col*`` classnames added to each of the child Panels of the FieldRowPanel. The Wagtail editing interface is layed out using a grid system, in which the maximum width of the editor is 12 columns wide. Classes ``col1``-``col12`` can be applied to each child of a FieldRowPanel. The class ``col3`` will ensure that field appears 3 columns wide or a quarter the width. ``col4`` would cause the field to be 4 columns wide, or a third the width.
|
||||
|
|
@ -425,277 +422,6 @@ hallo.js plugin names are prefixed with the ``"IKS."`` namespace, but the ``name
|
|||
|
||||
For information on developing custom hallo.js plugins, see the project's page: https://github.com/bergie/hallo
|
||||
|
||||
Edit Handler API
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
.. _admin_hooks:
|
||||
|
||||
Admin Hooks
|
||||
-----------
|
||||
|
||||
On loading, Wagtail will search for any app with the file ``wagtail_hooks.py`` and execute the contents. This provides a way to register your own functions to execute at certain points in Wagtail's execution, such as when a ``Page`` object is saved or when the main menu is constructed.
|
||||
|
||||
.. versionadded:: 0.5
|
||||
Decorator syntax was added in 0.5; earlier versions only supported ``hooks.register`` as an ordinary function call.
|
||||
|
||||
Registering functions with a Wagtail hook is done through the ``@hooks.register`` decorator:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from wagtail.wagtailcore import hooks
|
||||
|
||||
@hooks.register('name_of_hook')
|
||||
def my_hook_function(arg1, arg2...)
|
||||
# your code here
|
||||
|
||||
|
||||
Alternatively, ``hooks.register`` can be called as an ordinary function, passing in the name of the hook and a handler function defined elsewhere:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
hooks.register('name_of_hook', my_hook_function)
|
||||
|
||||
|
||||
The available hooks are:
|
||||
|
||||
.. _before_serve_page:
|
||||
|
||||
``before_serve_page``
|
||||
.. versionadded:: 0.4
|
||||
|
||||
Called when Wagtail is about to serve a page. The callable passed into the hook will receive the page object, the request object, and the args and kwargs that will be passed to the page's ``serve()`` method. If the callable returns an ``HttpResponse``, that response will be returned immediately to the user, and Wagtail will not proceed to call ``serve()`` on the page.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from wagtail.wagtailcore import hooks
|
||||
|
||||
@hooks.register('before_serve_page')
|
||||
def block_googlebot(page, request, serve_args, serve_kwargs):
|
||||
if request.META.get('HTTP_USER_AGENT') == 'GoogleBot':
|
||||
return HttpResponse("<h1>bad googlebot no cookie</h1>")
|
||||
|
||||
|
||||
.. _construct_wagtail_edit_bird:
|
||||
|
||||
``construct_wagtail_edit_bird``
|
||||
Add or remove items from the wagtail userbar. Add, edit, and moderation tools are provided by default. The callable passed into the hook must take the ``request`` object and a list of menu objects, ``items``. The menu item objects must have a ``render`` method which can take a ``request`` object and return the HTML string representing the menu item. See the userbar templates and menu item classes for more information.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from wagtail.wagtailcore import hooks
|
||||
|
||||
class UserbarPuppyLinkItem(object):
|
||||
def render(self, request):
|
||||
return '<li><a href="http://cuteoverload.com/tag/puppehs/" ' \
|
||||
+ 'target="_parent" class="action icon icon-wagtail">Puppies!</a></li>'
|
||||
|
||||
@hooks.register('construct_wagtail_edit_bird')
|
||||
def add_puppy_link_item(request, items):
|
||||
return items.append( UserbarPuppyLinkItem() )
|
||||
|
||||
|
||||
.. _construct_homepage_panels:
|
||||
|
||||
``construct_homepage_panels``
|
||||
Add or remove panels from the Wagtail admin homepage. The callable passed into this hook should take a ``request`` object and a list of ``panels``, objects which have a ``render()`` method returning a string. The objects also have an ``order`` property, an integer used for ordering the panels. The default panels use integers between ``100`` and ``300``.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from django.utils.safestring import mark_safe
|
||||
|
||||
from wagtail.wagtailcore import hooks
|
||||
|
||||
class WelcomePanel(object):
|
||||
order = 50
|
||||
|
||||
def render(self):
|
||||
return mark_safe("""
|
||||
<section class="panel summary nice-padding">
|
||||
<h3>No, but seriously -- welcome to the admin homepage.</h3>
|
||||
</section>
|
||||
""")
|
||||
|
||||
@hooks.register('construct_homepage_panels')
|
||||
def add_another_welcome_panel(request, panels):
|
||||
return panels.append( WelcomePanel() )
|
||||
|
||||
|
||||
.. _after_create_page:
|
||||
|
||||
``after_create_page``
|
||||
Do something with a ``Page`` object after it has been saved to the database (as a published page or a revision). The callable passed to this hook should take a ``request`` object and a ``page`` object. The function does not have to return anything, but if an object with a ``status_code`` property is returned, Wagtail will use it as a response object. By default, Wagtail will instead redirect to the Explorer page for the new page's parent.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from django.http import HttpResponse
|
||||
|
||||
from wagtail.wagtailcore import hooks
|
||||
|
||||
@hooks.register('after_create_page')
|
||||
def do_after_page_create(request, page):
|
||||
return HttpResponse("Congrats on making content!", content_type="text/plain")
|
||||
|
||||
|
||||
.. _after_edit_page:
|
||||
|
||||
``after_edit_page``
|
||||
Do something with a ``Page`` object after it has been updated. Uses the same behavior as ``after_create_page``.
|
||||
|
||||
.. _after_delete_page:
|
||||
|
||||
``after_delete_page``
|
||||
Do something after a ``Page`` object is deleted. Uses the same behavior as ``after_create_page``.
|
||||
|
||||
.. _register_admin_urls:
|
||||
|
||||
``register_admin_urls``
|
||||
Register additional admin page URLs. The callable fed into this hook should return a list of Django URL patterns which define the structure of the pages and endpoints of your extension to the Wagtail admin. For more about vanilla Django URLconfs and views, see `url dispatcher`_.
|
||||
|
||||
.. _url dispatcher: https://docs.djangoproject.com/en/dev/topics/http/urls/
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from django.http import HttpResponse
|
||||
from django.conf.urls import url
|
||||
|
||||
from wagtail.wagtailcore import hooks
|
||||
|
||||
def admin_view( request ):
|
||||
return HttpResponse( \
|
||||
"I have approximate knowledge of many things!", \
|
||||
content_type="text/plain")
|
||||
|
||||
@hooks.register('register_admin_urls')
|
||||
def urlconf_time():
|
||||
return [
|
||||
url(r'^how_did_you_almost_know_my_name/$', admin_view, name='frank' ),
|
||||
]
|
||||
|
||||
.. _register_admin_menu_item:
|
||||
|
||||
``register_admin_menu_item``
|
||||
.. versionadded:: 0.6
|
||||
|
||||
Add an item to the Wagtail admin menu. The callable passed to this hook must return an instance of ``wagtail.wagtailadmin.menu.MenuItem``. New items can be constructed from the ``MenuItem`` class by passing in a ``label`` which will be the text in the menu item, and the URL of the admin page you want the menu item to link to (usually by calling ``reverse()`` on the admin view you've set up). Additionally, the following keyword arguments are accepted:
|
||||
|
||||
:name: an internal name used to identify the menu item; defaults to the slugified form of the label. Also applied as a CSS class to the wrapping ``<li>``, as ``"menu-{name}"``.
|
||||
:classnames: additional classnames applied to the link, used to give it an icon
|
||||
:attrs: additional HTML attributes to apply to the link
|
||||
:order: an integer which determines the item's position in the menu
|
||||
|
||||
``MenuItem`` can be subclassed to customise the HTML output, specify Javascript files required by the menu item, or conditionally show or hide the item for specific requests (for example, to apply permission checks); see the source code (``wagtail/wagtailadmin/menu.py``) for details.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from django.core.urlresolvers import reverse
|
||||
|
||||
from wagtail.wagtailcore import hooks
|
||||
from wagtail.wagtailadmin.menu import MenuItem
|
||||
|
||||
@hooks.register('register_admin_menu_item')
|
||||
def register_frank_menu_item():
|
||||
return MenuItem('Frank', reverse('frank'), classnames='icon icon-folder-inverse', order=10000)
|
||||
|
||||
.. _register_settings_menu_item:
|
||||
|
||||
``register_settings_menu_item``
|
||||
.. versionadded:: 0.7
|
||||
|
||||
As ``register_admin_menu_item``, but registers menu items into the 'Settings' sub-menu rather than the top-level menu.
|
||||
|
||||
.. _construct_main_menu:
|
||||
|
||||
``construct_main_menu``
|
||||
Called just before the Wagtail admin menu is output, to allow the list of menu items to be modified. The callable passed to this hook will receive a ``request`` object and a list of ``menu_items``, and should modify ``menu_items`` in-place as required. Adding menu items should generally be done through the ``register_admin_menu_item`` hook instead - items added through ``construct_main_menu`` will be missing any associated Javascript includes, and their ``is_shown`` check will not be applied.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from wagtail.wagtailcore import hooks
|
||||
|
||||
@hooks.register('construct_main_menu')
|
||||
def hide_explorer_menu_item_from_frank(request, menu_items):
|
||||
if request.user.username == 'frank':
|
||||
menu_items[:] = [item for item in menu_items if item.name != 'explorer']
|
||||
|
||||
|
||||
.. _insert_editor_js:
|
||||
|
||||
``insert_editor_js``
|
||||
Add additional Javascript files or code snippets to the page editor. Output must be compatible with ``compress``, as local static includes or string.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from django.utils.html import format_html, format_html_join
|
||||
from django.conf import settings
|
||||
|
||||
from wagtail.wagtailcore import hooks
|
||||
|
||||
@hooks.register('insert_editor_js')
|
||||
def editor_js():
|
||||
js_files = [
|
||||
'demo/js/hallo-plugins/hallo-demo-plugin.js',
|
||||
]
|
||||
js_includes = format_html_join('\n', '<script src="{0}{1}"></script>',
|
||||
((settings.STATIC_URL, filename) for filename in js_files)
|
||||
)
|
||||
return js_includes + format_html(
|
||||
"""
|
||||
<script>
|
||||
registerHalloPlugin('demoeditor');
|
||||
</script>
|
||||
"""
|
||||
)
|
||||
|
||||
|
||||
.. _insert_editor_css:
|
||||
|
||||
``insert_editor_css``
|
||||
Add additional CSS or SCSS files or snippets to the page editor. Output must be compatible with ``compress``, as local static includes or string.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from django.utils.html import format_html
|
||||
from django.conf import settings
|
||||
|
||||
from wagtail.wagtailcore import hooks
|
||||
|
||||
@hooks.register('insert_editor_css')
|
||||
def editor_css():
|
||||
return format_html('<link rel="stylesheet" href="' \
|
||||
+ settings.STATIC_URL \
|
||||
+ 'demo/css/vendor/font-awesome/css/font-awesome.min.css">')
|
||||
|
||||
.. _construct_whitelister_element_rules:
|
||||
|
||||
``construct_whitelister_element_rules``
|
||||
.. versionadded:: 0.4
|
||||
|
||||
Customise the rules that define which HTML elements are allowed in rich text areas. By default only a limited set of HTML elements and attributes are whitelisted - all others are stripped out. The callables passed into this hook must return a dict, which maps element names to handler functions that will perform some kind of manipulation of the element. These handler functions receive the element as a `BeautifulSoup <http://www.crummy.com/software/BeautifulSoup/bs4/doc/>`_ Tag object.
|
||||
|
||||
The ``wagtail.wagtailcore.whitelist`` module provides a few helper functions to assist in defining these handlers: ``allow_without_attributes``, a handler which preserves the element but strips out all of its attributes, and ``attribute_rule`` which accepts a dict specifying how to handle each attribute, and returns a handler function. This dict will map attribute names to either True (indicating that the attribute should be kept), False (indicating that it should be dropped), or a callable (which takes the initial attribute value and returns either a final value for the attribute, or None to drop the attribute).
|
||||
|
||||
For example, the following hook function will add the ``<blockquote>`` element to the whitelist, and allow the ``target`` attribute on ``<a>`` elements:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from wagtail.wagtailcore import hooks
|
||||
from wagtail.wagtailcore.whitelist import attribute_rule, check_url, allow_without_attributes
|
||||
|
||||
@hooks.register('construct_whitelister_element_rules')
|
||||
def whitelister_element_rules():
|
||||
return {
|
||||
'blockquote': allow_without_attributes,
|
||||
'a': attribute_rule({'href': check_url, 'target': True}),
|
||||
}
|
||||
|
||||
.. _register_permissions:
|
||||
|
||||
``register_permissions``
|
||||
.. versionadded:: 0.7
|
||||
|
||||
Return a queryset of Permission objects to be shown in the Groups administration area.
|
||||
|
||||
|
||||
Image Formats in the Rich Text Editor
|
||||
-------------------------------------
|
||||
|
||||
|
|
|
|||
|
|
@ -1,9 +1,6 @@
|
|||
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.
|
||||
|
|
@ -20,6 +17,6 @@ The presentation of your content, the actual webpages, includes the normal use o
|
|||
model_recipes
|
||||
editing_api
|
||||
streamfield
|
||||
sites
|
||||
advanced_topics/queryset_methods
|
||||
advanced_topics/private_pages
|
||||
advanced_topics/routable_page_mixin
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
For Front End developers
|
||||
========================
|
||||
Writing templates
|
||||
=================
|
||||
|
||||
.. contents:: Contents
|
||||
:local:
|
||||
|
|
|
|||
267
docs/reference/hooks.rst
Normal file
267
docs/reference/hooks.rst
Normal file
|
|
@ -0,0 +1,267 @@
|
|||
|
||||
.. _admin_hooks:
|
||||
|
||||
Hooks
|
||||
-----
|
||||
|
||||
On loading, Wagtail will search for any app with the file ``wagtail_hooks.py`` and execute the contents. This provides a way to register your own functions to execute at certain points in Wagtail's execution, such as when a ``Page`` object is saved or when the main menu is constructed.
|
||||
|
||||
.. versionadded:: 0.5
|
||||
Decorator syntax was added in 0.5; earlier versions only supported ``hooks.register`` as an ordinary function call.
|
||||
|
||||
Registering functions with a Wagtail hook is done through the ``@hooks.register`` decorator:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from wagtail.wagtailcore import hooks
|
||||
|
||||
@hooks.register('name_of_hook')
|
||||
def my_hook_function(arg1, arg2...)
|
||||
# your code here
|
||||
|
||||
|
||||
Alternatively, ``hooks.register`` can be called as an ordinary function, passing in the name of the hook and a handler function defined elsewhere:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
hooks.register('name_of_hook', my_hook_function)
|
||||
|
||||
|
||||
The available hooks are:
|
||||
|
||||
.. _before_serve_page:
|
||||
|
||||
``before_serve_page``
|
||||
.. versionadded:: 0.4
|
||||
|
||||
Called when Wagtail is about to serve a page. The callable passed into the hook will receive the page object, the request object, and the args and kwargs that will be passed to the page's ``serve()`` method. If the callable returns an ``HttpResponse``, that response will be returned immediately to the user, and Wagtail will not proceed to call ``serve()`` on the page.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from wagtail.wagtailcore import hooks
|
||||
|
||||
@hooks.register('before_serve_page')
|
||||
def block_googlebot(page, request, serve_args, serve_kwargs):
|
||||
if request.META.get('HTTP_USER_AGENT') == 'GoogleBot':
|
||||
return HttpResponse("<h1>bad googlebot no cookie</h1>")
|
||||
|
||||
|
||||
.. _construct_wagtail_edit_bird:
|
||||
|
||||
``construct_wagtail_edit_bird``
|
||||
Add or remove items from the wagtail userbar. Add, edit, and moderation tools are provided by default. The callable passed into the hook must take the ``request`` object and a list of menu objects, ``items``. The menu item objects must have a ``render`` method which can take a ``request`` object and return the HTML string representing the menu item. See the userbar templates and menu item classes for more information.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from wagtail.wagtailcore import hooks
|
||||
|
||||
class UserbarPuppyLinkItem(object):
|
||||
def render(self, request):
|
||||
return '<li><a href="http://cuteoverload.com/tag/puppehs/" ' \
|
||||
+ 'target="_parent" class="action icon icon-wagtail">Puppies!</a></li>'
|
||||
|
||||
@hooks.register('construct_wagtail_edit_bird')
|
||||
def add_puppy_link_item(request, items):
|
||||
return items.append( UserbarPuppyLinkItem() )
|
||||
|
||||
|
||||
.. _construct_homepage_panels:
|
||||
|
||||
``construct_homepage_panels``
|
||||
Add or remove panels from the Wagtail admin homepage. The callable passed into this hook should take a ``request`` object and a list of ``panels``, objects which have a ``render()`` method returning a string. The objects also have an ``order`` property, an integer used for ordering the panels. The default panels use integers between ``100`` and ``300``.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from django.utils.safestring import mark_safe
|
||||
|
||||
from wagtail.wagtailcore import hooks
|
||||
|
||||
class WelcomePanel(object):
|
||||
order = 50
|
||||
|
||||
def render(self):
|
||||
return mark_safe("""
|
||||
<section class="panel summary nice-padding">
|
||||
<h3>No, but seriously -- welcome to the admin homepage.</h3>
|
||||
</section>
|
||||
""")
|
||||
|
||||
@hooks.register('construct_homepage_panels')
|
||||
def add_another_welcome_panel(request, panels):
|
||||
return panels.append( WelcomePanel() )
|
||||
|
||||
|
||||
.. _after_create_page:
|
||||
|
||||
``after_create_page``
|
||||
Do something with a ``Page`` object after it has been saved to the database (as a published page or a revision). The callable passed to this hook should take a ``request`` object and a ``page`` object. The function does not have to return anything, but if an object with a ``status_code`` property is returned, Wagtail will use it as a response object. By default, Wagtail will instead redirect to the Explorer page for the new page's parent.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from django.http import HttpResponse
|
||||
|
||||
from wagtail.wagtailcore import hooks
|
||||
|
||||
@hooks.register('after_create_page')
|
||||
def do_after_page_create(request, page):
|
||||
return HttpResponse("Congrats on making content!", content_type="text/plain")
|
||||
|
||||
|
||||
.. _after_edit_page:
|
||||
|
||||
``after_edit_page``
|
||||
Do something with a ``Page`` object after it has been updated. Uses the same behavior as ``after_create_page``.
|
||||
|
||||
.. _after_delete_page:
|
||||
|
||||
``after_delete_page``
|
||||
Do something after a ``Page`` object is deleted. Uses the same behavior as ``after_create_page``.
|
||||
|
||||
.. _register_admin_urls:
|
||||
|
||||
``register_admin_urls``
|
||||
Register additional admin page URLs. The callable fed into this hook should return a list of Django URL patterns which define the structure of the pages and endpoints of your extension to the Wagtail admin. For more about vanilla Django URLconfs and views, see `url dispatcher`_.
|
||||
|
||||
.. _url dispatcher: https://docs.djangoproject.com/en/dev/topics/http/urls/
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from django.http import HttpResponse
|
||||
from django.conf.urls import url
|
||||
|
||||
from wagtail.wagtailcore import hooks
|
||||
|
||||
def admin_view( request ):
|
||||
return HttpResponse( \
|
||||
"I have approximate knowledge of many things!", \
|
||||
content_type="text/plain")
|
||||
|
||||
@hooks.register('register_admin_urls')
|
||||
def urlconf_time():
|
||||
return [
|
||||
url(r'^how_did_you_almost_know_my_name/$', admin_view, name='frank' ),
|
||||
]
|
||||
|
||||
.. _register_admin_menu_item:
|
||||
|
||||
``register_admin_menu_item``
|
||||
.. versionadded:: 0.6
|
||||
|
||||
Add an item to the Wagtail admin menu. The callable passed to this hook must return an instance of ``wagtail.wagtailadmin.menu.MenuItem``. New items can be constructed from the ``MenuItem`` class by passing in a ``label`` which will be the text in the menu item, and the URL of the admin page you want the menu item to link to (usually by calling ``reverse()`` on the admin view you've set up). Additionally, the following keyword arguments are accepted:
|
||||
|
||||
:name: an internal name used to identify the menu item; defaults to the slugified form of the label. Also applied as a CSS class to the wrapping ``<li>``, as ``"menu-{name}"``.
|
||||
:classnames: additional classnames applied to the link, used to give it an icon
|
||||
:attrs: additional HTML attributes to apply to the link
|
||||
:order: an integer which determines the item's position in the menu
|
||||
|
||||
``MenuItem`` can be subclassed to customise the HTML output, specify Javascript files required by the menu item, or conditionally show or hide the item for specific requests (for example, to apply permission checks); see the source code (``wagtail/wagtailadmin/menu.py``) for details.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from django.core.urlresolvers import reverse
|
||||
|
||||
from wagtail.wagtailcore import hooks
|
||||
from wagtail.wagtailadmin.menu import MenuItem
|
||||
|
||||
@hooks.register('register_admin_menu_item')
|
||||
def register_frank_menu_item():
|
||||
return MenuItem('Frank', reverse('frank'), classnames='icon icon-folder-inverse', order=10000)
|
||||
|
||||
.. _register_settings_menu_item:
|
||||
|
||||
``register_settings_menu_item``
|
||||
.. versionadded:: 0.7
|
||||
|
||||
As ``register_admin_menu_item``, but registers menu items into the 'Settings' sub-menu rather than the top-level menu.
|
||||
|
||||
.. _construct_main_menu:
|
||||
|
||||
``construct_main_menu``
|
||||
Called just before the Wagtail admin menu is output, to allow the list of menu items to be modified. The callable passed to this hook will receive a ``request`` object and a list of ``menu_items``, and should modify ``menu_items`` in-place as required. Adding menu items should generally be done through the ``register_admin_menu_item`` hook instead - items added through ``construct_main_menu`` will be missing any associated Javascript includes, and their ``is_shown`` check will not be applied.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from wagtail.wagtailcore import hooks
|
||||
|
||||
@hooks.register('construct_main_menu')
|
||||
def hide_explorer_menu_item_from_frank(request, menu_items):
|
||||
if request.user.username == 'frank':
|
||||
menu_items[:] = [item for item in menu_items if item.name != 'explorer']
|
||||
|
||||
|
||||
.. _insert_editor_js:
|
||||
|
||||
``insert_editor_js``
|
||||
Add additional Javascript files or code snippets to the page editor. Output must be compatible with ``compress``, as local static includes or string.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from django.utils.html import format_html, format_html_join
|
||||
from django.conf import settings
|
||||
|
||||
from wagtail.wagtailcore import hooks
|
||||
|
||||
@hooks.register('insert_editor_js')
|
||||
def editor_js():
|
||||
js_files = [
|
||||
'demo/js/hallo-plugins/hallo-demo-plugin.js',
|
||||
]
|
||||
js_includes = format_html_join('\n', '<script src="{0}{1}"></script>',
|
||||
((settings.STATIC_URL, filename) for filename in js_files)
|
||||
)
|
||||
return js_includes + format_html(
|
||||
"""
|
||||
<script>
|
||||
registerHalloPlugin('demoeditor');
|
||||
</script>
|
||||
"""
|
||||
)
|
||||
|
||||
|
||||
.. _insert_editor_css:
|
||||
|
||||
``insert_editor_css``
|
||||
Add additional CSS or SCSS files or snippets to the page editor. Output must be compatible with ``compress``, as local static includes or string.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from django.utils.html import format_html
|
||||
from django.conf import settings
|
||||
|
||||
from wagtail.wagtailcore import hooks
|
||||
|
||||
@hooks.register('insert_editor_css')
|
||||
def editor_css():
|
||||
return format_html('<link rel="stylesheet" href="' \
|
||||
+ settings.STATIC_URL \
|
||||
+ 'demo/css/vendor/font-awesome/css/font-awesome.min.css">')
|
||||
|
||||
.. _construct_whitelister_element_rules:
|
||||
|
||||
``construct_whitelister_element_rules``
|
||||
.. versionadded:: 0.4
|
||||
|
||||
Customise the rules that define which HTML elements are allowed in rich text areas. By default only a limited set of HTML elements and attributes are whitelisted - all others are stripped out. The callables passed into this hook must return a dict, which maps element names to handler functions that will perform some kind of manipulation of the element. These handler functions receive the element as a `BeautifulSoup <http://www.crummy.com/software/BeautifulSoup/bs4/doc/>`_ Tag object.
|
||||
|
||||
The ``wagtail.wagtailcore.whitelist`` module provides a few helper functions to assist in defining these handlers: ``allow_without_attributes``, a handler which preserves the element but strips out all of its attributes, and ``attribute_rule`` which accepts a dict specifying how to handle each attribute, and returns a handler function. This dict will map attribute names to either True (indicating that the attribute should be kept), False (indicating that it should be dropped), or a callable (which takes the initial attribute value and returns either a final value for the attribute, or None to drop the attribute).
|
||||
|
||||
For example, the following hook function will add the ``<blockquote>`` element to the whitelist, and allow the ``target`` attribute on ``<a>`` elements:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from wagtail.wagtailcore import hooks
|
||||
from wagtail.wagtailcore.whitelist import attribute_rule, check_url, allow_without_attributes
|
||||
|
||||
@hooks.register('construct_whitelister_element_rules')
|
||||
def whitelister_element_rules():
|
||||
return {
|
||||
'blockquote': allow_without_attributes,
|
||||
'a': attribute_rule({'href': check_url, 'target': True}),
|
||||
}
|
||||
|
||||
.. _register_permissions:
|
||||
|
||||
``register_permissions``
|
||||
.. versionadded:: 0.7
|
||||
|
||||
Return a queryset of Permission objects to be shown in the Groups administration area.
|
||||
|
|
@ -6,5 +6,6 @@ Reference
|
|||
:maxdepth: 2
|
||||
|
||||
management_commands
|
||||
hooks
|
||||
project_template
|
||||
page
|
||||
|
|
|
|||
Loading…
Reference in a new issue