First be sure you have added micawber.contrib.mcdjango
to INSTALLED_APPS
so that we can use the template filters it defines.
# settings.py
INSTALLED_APPS = [
# ...
'micawber.contrib.mcdjango',
]
micawber provides 4 template filters for converting URLs contained within text or HTML to rich content:
- :py
~micawber.contrib.mcdjango.oembed
for plain text - :py
~micawber.contrib.mcdjango.oembed_html
for html - :py
~micawber.contrib.mcdjango.extract_oembed
for extracting url data from plain text - :py
~micawber.contrib.mcdjango.extract_oembed_html
for extracting url data from html
These filters are registered in the micawber_tags
library, which can be invoked in your templates:
{% load micawber_tags %}
<p>{{ object.body|oembed:"600x600" }}</p>
Each filter accepts one argument and one optional argument, due to django's template filters being wack.
Piping a string through the oembed
filter (or oembed_html
) will convert URLs to things like youtube videos into video players. A couple things to understand about the parsers:
- the plaintext parser (
oembed
) will convert URLs on their own line into full images/video-players/etc. URLs that are interspersed within text will simply be converted into clickable links so as not to disrupt the flow of text. - the HTML parser (
oembed_html
) will convert URLs that are not already links into full images/video-players/etc. URLs within block elements along with other text will be converted into clickable links as this would likely disrupt the flow of text or produce invalid HTML.
Note
You can control how things are rendered -- check out the default templates for reference implementations.
The following filters are exposed via the :pymicawber.contrib.mcdjango
module:
For simplicity, micawber provides a setting allowing you to create custom template filters. An example use case would be to add a template filter that could embed rich content, but did not automatically "urlize" all links.
Extensions are configured in the settings
module and take the form of a list of 2-tuples containing:
- the name for the custom filter
- a dictionary of keyword arguments to pass in to the
parse
function
MICAWBER_TEMPLATE_EXTENSIONS = [
('oembed_no_urlize', {'urlize_all': False}),
]
Assume this is our template:
{% load micawber_tags %}
DEFAULT:
{{ "http://foo.com/ and http://bar.com/"|oembed }}
CUSTOM:
{{ "http://foo.com/ and http://bar.com/"|oembed_no_urlize }}
Rendering the above template will produce the following output:
DEFAULT:
<a href="http://foo.com/">http://foo.com/</a> and <a href="http://bar.com/">http://bar.com/</a>
CUSTOM:
http://foo.com/ and http://bar.com/
Some examples of keyword arguments to override are:
- providers: a :py
~micawber.providers.ProviderRegistry
instance - urlize_all (default
True
): whether to convert all URLs to clickable links - html (default
False
): whether to parse as plaintext or html - handler: function used to render metadata as markup
- block_handler: function used to render inline links with rich metadata
- text_fn: function to use when parsing text
- html_fn: function to use when parsing html
The magic happens in :pymicawber.contrib.mcdjango.extension
-- check out the source code for more details.
Note
The MICAWBER_EXTENSIONS
setting can also be a string path to a module and an attribute containing a similar data structure.
The most important setting to configure is the module / attribute path to the providers you wish to use. The attribute can either be a ProviderRegistry instance or a callable. The default is:
MICAWBER_PROVIDERS = 'micawber.contrib.mcdjango.providers.bootstrap_basic'
You can use the bootstrap embedly function, but beware this may take a few seconds to load up:
MICAWBER_PROVIDERS = 'micawber.contrib.mcdjango.providers.bootstrap_embedly'
If you want to use the embedly endpoints and have an API key, you can specify that in the settings:
MICAWBER_EMBEDLY_KEY = 'foo'
You can also customize this with your own set of providers. This must be either
- the module path to a :py
~micawber.providers.ProviderRegistry
instance - the module path to a callable which returns a :py
~micawber.providers.ProviderRegistry
instance
Here is a quick example showing a custom ProviderRegistry
:
# settings.py
MICAWBER_PROVIDERS = 'my_app.micawber_providers.oembed_providers'
# my_app/micawber_providers.py
from django.core.cache import cache
from micawber.providers import Provider, bootstrap_basic
oembed_providers = boostrap_basic(cache)
# add a custom provider
oembed_providers.register('http://example.com/\S*', Provider('http://example.com/oembed/'))
Because of the limitations of django's template filters, we do not have the flexibility to pass in multiple arguments to the filters. Default arguments need to be specified in the settings:
MICAWBER_DEFAULT_SETTINGS = {
'key': 'your-embedly-api-key',
'maxwidth': 600,
'maxheight': 600,
}
>>> from django.template import Template, Context
>>> t = Template('{% load micawber_tags %}{{ "http://www.youtube.com/watch?v=mQEWI1cn7HY"|oembed }}')
>>> t.render(Context())
u'<iframe width="480" height="270" src="http://www.youtube.com/embed/mQEWI1cn7HY?fs=1&feature=oembed" frameborder="0" allowfullscreen></iframe>'