Permalink
Browse files

Merge branch 'master' of git://github.com/philomat/django-cms-2.0

  • Loading branch information...
digi604 committed Apr 14, 2010
2 parents 22dc836 + db983e8 commit 21bd0448304ca10ac003f977b888b83cc628a9bd
View
@@ -21,8 +21,7 @@
from cms.utils.permissions import has_page_add_permission, \
has_page_change_permission, get_user_permission_level, \
has_global_change_permissions_permission
-from cms.utils.plugin import get_page_from_plugin_or_404
-from cms.utils.plugins import get_placeholders
+from cms.utils.plugins import get_placeholders, get_page_from_plugin_or_404
from cms.utils.placeholder import get_page_from_placeholder_if_exists
from copy import deepcopy
from django import template
View
@@ -8,124 +8,178 @@ To use any of the following templatetags you need to load them first at the top
placeholder
-----------
-The ``placeholder`` templatetag will be filled with plugins. The cms auto-detects all placeholders
-used in the template.
+The `placeholder` templatetag defines a placeholder on a page. All placeholders in a template will
+be auto-detected and can be filled with plugins when editing a page that is using said template.
+When rendering, the content of these plugins will appear where the `placeholder` tag was.
Example::
- {% placeholder "content" %}
-
-You can additionally give the placeholder a width attribute::
+ {% placeholder "content" %}
- {% placeholder "content" "230" %}
-
-If a width is provided every plugin recieves a "width" context variable when the plugin is rendered.
-The main use case of the width attribute is for automatically resizing images correctly.
+If you want additional content to be displayed in case the placeholder is empty, use the `or` argument and an additional `{% endplaceholder %}` closing tag. Everything between `{% placeholder "..." or %}` and `{% endplaceholder %}` is rendered instead if the placeholder has no plugins or the plugins do not generate any output.
-Also be sure to check out the ``PLACEHOLDER_CONF`` setting where you can change some of the behavior
-of the placeholders.
+Example::
-placeholderor
--------------
+ {% placeholder "content" or %}There is no content.{% endplaceholder %}
-The same as ``placeholder``, with additional content to be displayed in case the placeholder is empty:
-If the placeholder has no plugins or the plugins do not generate any output, everything between
-``{% placeholderor %}`` and ``{% endplaceholderor %}`` is rendered instead.
+If you want to add extra variables to the context of the placeholder, you should use Django's
+`with` tag. For instance, if you want to resize images from your templates according to a context
+variable called `width`, you can pass it as follows:
-Example::
+ {% with 320 as width %}{% placeholder "content" %}{% endwith %}
- {% placeholderor "content" %}There is no content.{% endplaceholderor %}
+See also the `PLACEHOLDER_CONF` setting where you can also add extra context variables and change some other placeholder behavior.
-show_placeholder_by_id
-----------------------
+show_placeholder
+----------------
-Displays the placeholder of a page with an id.
+Displays a specific placeholder from a given page. This is useful if you want to have some more or less static content that is shared among many pages, such as a footer.
-Attributes:
+Arguments:
-- placeholder_name
-- reverse_id
-- language (optional)
-- site (optional)
+- `placeholder_name`
+- `page_lookup` (see [Page Lookup](#page-lookup) for more information)
+- `language` (optional)
+- `site` (optional)
-Example::
+Examples::
+
+ {% show_placeholder "footer" "footer_container_page" %}
+ {% show_placeholder "content" request.current_page.parent_id %}
+ {% show_placeholder "teaser" request.current_page.get_root %}
+
+### Page Lookup <a id="page-lookup"></a> ###
+
+The `page_lookup` argument, passed to several templatetags to retrieve a page, can be of any of the
+following types:
- {% show_placeholder_by_id "content" "footer_page" %}
+- String: interpreted as the `reverse_id` field of the desired page, which can be set in the
+"Advanced" section when editing a page.
+- Integer: interpreted as the primary key (`pk` field) of the desired page
+- `dict`: a dictionary containing keyword arguments to find the desired page
+(for instance: `{'pk': 1}`)
+- `Page`: you can also pass a page object directly, in which case there will be no database lookup.
-show_uncached_placeholder_by_id
--------------------------------
+If you know the exact page you are referring to, it is a good idea to use a `reverse_id` (a string
+used to uniquely name a page) rather than a hard-coded numeric ID in your template. For example, you
+might have a help page that you want to link to or display parts of on all pages. To do this, you
+would first open the help page in the admin interface and enter an ID (such as `help`) under the
+'Advanced' tab of the form. Then you could use that `reverse_id` with the appropriate templatetags:
-The same as ``show_placeholder_by_id`` but is not cached.
+ {% show_placeholder "right-column" "help" %}
+ <a href="{% page_url "help" %}">Help page</a>
-Attributes:
+If you are referring to a page _relative_ to the current page, you'll probably have to use a
+numeric page ID or a page object. For instance, if you want the content of the parent page display
+on the current page, you can use:
-- placeholder_name
-- reverse_id
-- language (optional)
-- site (optional)
+ {% show_placeholder "content" request.current_page.parent_id %}
+
+Or, suppose you have a placeholder called `teaser` on a page that, unless a content editor has
+filled it with content specific to the current page, should inherit the content of its root-level ancestor:
+
+ {% placeholderor "teaser" %}
+ {% show_placeholder "teaser" request.current_page.get_root %}
+ {% endplaceholderor %}
+
+show_uncached_placeholder
+-------------------------
+
+The same as `show_placeholder`, but the placeholder contents will not be cached.
+
+Arguments:
+
+- `placeholder_name`
+- `page_lookup` (see [Page Lookup](#page-lookup) for more information)
+- `language` (optional)
+- `site` (optional)
Example::
- {% show_uncached_placeholder_by_id "content" "footer_page" %}
+ {% show_uncached_placeholder "footer" "footer_container_page" %}
plugins_media
-------------
-Returns all media that is used by plugins and is defined with a Media class
-You normally want to place this in your <head> tag.
+Outputs the appropriate tags to include all media that is used by the plugins on a page (defined
+using the `Media` class in the plugin class).
+
+You normally want to place this in your `<head>` tag.
-example::
+Example::
{% plugins_media %}
+
+Arguments::
+
+- `page_lookup` (optional; see [Page Lookup](#page-lookup) for more information)
+
+If you need to include the media from another page, for instance if you are using a placeholder from another page using the `show_placeholder` tag, you can supply the `page_lookup` attribute to indicate the page in question:
+
+ {% plugins_media "teaser" %}
-For a reference on what plugin media is used look in the plugin reference.
+For a reference on what plugin media is required by a specific plugin, look at that plugin's
+reference.
+
+page_url
+--------
+
+Displays the URL of a page in the current language.
+
+Arguments::
+
+- `page_lookup` (see [Page Lookup](#page-lookup) for more information)
+
+Example::
+
+ <a href="{% page_url "help" %}">Help page</a>
+ <a href="{% page_url request.current_page.parent %}">Parent page</a>
page_attribute
--------------
This templatetag is used to display an attribute of the current page in the current language.
-Example::
+Arguments:
- {% page_attribute page_title %}
-
-Possible attributes:
+- `attribute_name`
+- `page_lookup` (optional; see [Page Lookup](#page-lookup) for more information)
-- title
-- menu_title
-- page_title
-- slug
-- meta_description
-- meta_keywords
+Possible values for `attribute_name` are: `"title"`, `"menu_title"`, `"page_title"`, `"slug"`, `"meta_description"`, `"meta_keywords"` (note that you can also supply that argument without quotes,
+but this is deprecated because the argument might also be a template variable).
-As an optional second argument you can provide a page id. Page ids can be set in the advanced
-settings tab of a page.
+Example::
+
+ {% page_attribute "page_title" %}
+
+If you supply the optional `page_lookup` argument, you will get the page attribute from the page found by that argument.
Example::
- {% page_attribute page_title my_page_id %}
+ {% page_attribute "page_title" "my_page_reverse_id" %}
+ {% page_attribute "page_title" request.current_page.parent_id %}
+ {% page_attribute "slug" request.current_page.get_root %}
show_menu
---------
-``{& show_menu %}`` renders the navigation of the current page.
-You can overwrite the appearance and the HTML if you add a ``cms/menu.html``
+The `show_menu` tag renders the navigation of the current page.
+You can overwrite the appearance and the HTML if you add a `cms/menu.html`
template to your project or edit the one provided with django-cms.
-``show_menu`` takes four optional parameters: ``start_level``, ``end_level``,
-``extra_inactive``, and ``extra_active``.
+`show_menu` takes four optional parameters: `start_level`, `end_level`,
+`extra_inactive`, and `extra_active`.
-The first two parameters, ``start_level`` (default=0) and ``end_level`` (default=100) specify from what level to which level
+The first two parameters, `start_level` (default=0) and `end_level` (default=100) specify from what level to which level
should the navigation be rendered.
If you have a home as a root node and don't want to display home you can render the navigation only after level 1.
-The third parameter, ``extra_inactive`` (default=0), specifies how many levels of navigation should be displayed
+The third parameter, `extra_inactive` (default=0), specifies how many levels of navigation should be displayed
if a node is not a direct ancestor or descendant of the current active node.
-Finally, the fourth parameter, ``extra_active`` (default=100), specifies how many levels of
+Finally, the fourth parameter, `extra_active` (default=100), specifies how many levels of
descendants of the currently active node should be displayed.
-Some Examples:
-^^^^^^^^^^^^^^
+### Some Examples: ###
Complete navigation (as a nested list)::
@@ -167,7 +221,7 @@ has the id "meta"::
{% show_menu_below_id "meta" %}
</ul>
-You can give it the same optional parameters as ``show_menu``::
+You can give it the same optional parameters as `show_menu`::
<ul>
{% show_menu_below_id "meta" 0 100 100 100 "myapp/menu.html" %}
@@ -176,9 +230,9 @@ You can give it the same optional parameters as ``show_menu``::
show_sub_menu
-------------
-Display the sub menu of the current page (as a nested list).
+Displays the sub menu of the current page (as a nested list).
Takes one argument that specifies how many levels deep should the submenu be displayed.
-The template can be found at ``cms/sub_menu.html``::
+The template can be found at `cms/sub_menu.html`::
<ul>
{% show_sub_menu 1 %}
@@ -193,8 +247,8 @@ Or with a custom template::
show_breadcrumb
---------------
-Show the breadcrumb navigation of the current page.
-The template for the HTML can be found at ``cms/breadcrumb.html``.::
+Renders the breadcrumb navigation of the current page.
+The template for the HTML can be found at `cms/breadcrumb.html`.::
{% show_breadcrumb %}
@@ -243,8 +297,8 @@ For more information have a look in the i18n docs.
language_chooser
----------------
-The ``language_chooser`` template tag will display a language chooser for the current page.
-You can modify the template in ``cms/language_chooser.html`` or provide your own template if necessary.
+The `language_chooser` template tag will display a language chooser for the current page.
+You can modify the template in `cms/language_chooser.html` or provide your own template if necessary.
Example::
@@ -262,16 +316,3 @@ For more information have a look in the i18n docs.
#TODO: link to i18n
-page_id_url
------------
-
-This template tag returns the URL of a page that has a symbolic name, known as
-``id`` or ``reverse_id``. For example, you could have a help page that you want to display a link to
-on every page. To do this, you would go to the help page in the admin interface and
-enter a id (such as "help") in the 'Advanced' tab of the page's settings.
-You could then obtain a URL for the help page in a template like this::
-
- <a href="{% page_id_url "help" %}">help</a>
-
-
-
@@ -3,14 +3,13 @@
from django.forms.widgets import Media
import operator
-
class Placeholder(models.Model):
slot = models.CharField(_("slot"), max_length=50, db_index=True, editable=False)
default_width = models.PositiveSmallIntegerField(_("width"), null=True, editable=False)
-
+
def __unicode__(self):
return self.slot
-
+
class Meta:
app_label = 'cms'
@@ -19,13 +18,14 @@ def has_change_permission(self, request):
if request.user.is_superuser:
return True
return request.user.has_perm(opts.app_label + '.' + opts.get_change_permission())
-
+
def render(self, context, width):
- from cms.utils.plugin import render_plugins_for_context
+ from cms.plugin_rendering import render_placeholder
if not 'request' in context:
return '<!-- missing request -->'
- return render_plugins_for_context(self, context, width or self.default_width)
-
+ context.update({'width': width or self.default_width})
+ return render_placeholder(self, context)
+
def get_media(self, request, context):
from cms.plugins.utils import get_plugin_media
media_classes = [get_plugin_media(request, context, plugin) for plugin in self.cmsplugin_set.all()]
@@ -104,7 +104,7 @@ def render_plugin(self, context=None, placeholder=None, admin=False, processors=
instance, plugin = self.get_plugin_instance()
if instance and not (admin and not plugin.admin_preview):
context = PluginContext(context, instance, placeholder)
- context = plugin.render(context, instance, placeholder)
+ context = plugin.render(context, instance, placeholder.slot)
if plugin.render_plugin:
template = hasattr(instance, 'render_template') and instance.render_template or plugin.render_template
if not template:
Oops, something went wrong.

0 comments on commit 21bd044

Please sign in to comment.