UsageΒΆ
To convert a Markdown document with Elements
contained within, you need to
first load the template tags:
{% load elements_markup %}
Currently there is both a tag and a filter that you can use to render the
Markdown content as HTML. The more powerful option is the template tag and
its usage is best explained with an example. Let’s pretend we’ve created a
FlatPage
who’s content
contains text written in Markdown with elements
contained within. We can render the page as HTML, assuming the FlatPage
object is referenced as flatpage
, like so:
{% markup_elements flatpage content %}
This template tag is more powerful than the filter described below, because
each element contained within this FlatPage
is “aware” of the context in
which is is being rendered. Again, this concept is more easily explained with
and example.
Let’s consider a very simple application, which we’ll call media
, that has
a very simple model:
from django.db import models
class MediaItem(models.Model):
title = models.CharField(max_length=255)
file = models.FileField()
caption = models.TextField(blank=True)
Now let’s also pretend that we’ve created an ElementType
for this model,
titled “Image”. This means that we can now add an “Image” into a
FlatPage
like so, assuming we’ve uploaded an image with pk=1
:
Here is some flatpage content. Let's go ahead an insert an image:
[[El('Image', id=1)]]
To recap what we’ve got currently:
- A
FlatPage
withpk=2
andcontent
shown above- An
ElementType
titled “Image”- An
MediaItem
withpk=1
from themedia
application
Now we can control how the Image
above is actually rendered into HTML
by defining various templates. Here is the order in which templates will
be searched:
elements/flatpages/flatpage/2/media_mediaitem_1.html
elements/flatpages/flatpage/2/media_mediaitem-image.html
elements/flatpages/flatpage/2/media_mediaitem.html
elements/flatpages/flatpage/2/media-image.html
elements/flatpages/flatpage/2/media.html
elements/flatpages/flatpage/2/default.html
elements/flatpages/flatpage/media_mediaitem_1.html
elements/flatpages/flatpage/media_mediaitem-image.html
elements/flatpages/flatpage/media_mediaitem.html
elements/flatpages/flatpage/media-image.html
elements/flatpages/flatpage/media.html
elements/flatpages/flatpage/default.html
elements/flatpages/media_mediaitem_1.html
elements/flatpages/media_mediaitem-image.html
elements/flatpages/media_mediaitem.html
elements/flatpages/media-image.html
elements/flatpages/media.html
elements/media_mediaitem-image.html
elements/media_mediaitem.html
elements/default.html
This means we can define a template that will dictate how this “Image” element
will render for this FlatPage
(and only this particular FlatPage
) via
the elements/flatpages/flatpage/2/media_mediaitem_1.html
, or we can
simply define a more generic template that will define how to render any
“Image” for any FlatPage
via the
elements/flatpages/flatpage/media_mediaitem-image.html
.