Django integration¶
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:
oembed()
for plain textoembed_html()
for htmlextract_oembed()
for extracting url data from plain textextract_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.
Django filter API¶
The following filters are exposed via the micawber.contrib.mcdjango
module:
-
micawber.contrib.mcdjango.
oembed
(text[, width_height=None])¶ Parse the given text, rendering URLs as rich media
Usage within a django template:
{{ blog_entry.body|oembed:"600x600" }}
Parameters: - text – the text to be parsed do not use HTML
- width_height – string containing maximum for width and optionally height, of format “WIDTHxHEIGHT” or “WIDTH”, e.g. “500x500” or “800”
Return type: parsed text with rich content embedded
-
micawber.contrib.mcdjango.
oembed_html
(html[, width_height=None])¶ Exactly the same as above except for usage with html
Usage within a django template:
{{ blog_entry.body|markdown|oembed_html:"600x600" }}
-
micawber.contrib.mcdjango.
extract_oembed
(text[, width_height=None])¶ Parse the given text, returning a list of 2-tuples containing url and metadata about the url.
Usage within a django template:
{% for url, metadata in blog_entry.body|extract_oembed:"600x600" %} <img src="{{ metadata.thumbnail_url }}" /> {% endfor %}
Parameters: - text – the text to be parsed do not use HTML
- width_height – string containing maximum for width and optionally height, of format “WIDTHxHEIGHT” or “WIDTH”, e.g. “500x500” or “800”
Return type: 2-tuples containing the URL and a dictionary of metadata
-
micawber.contrib.mcdjango.
extract_oembed_html
(html[, width_height=None])¶ Exactly the same as above except for usage with html
Extending the filters¶
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
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 micawber.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.
Additional settings¶
Providers¶
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
ProviderRegistry
instance - the module path to a callable which returns a
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/'))
Default settings for requests¶
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,
}
Trying it out in the python shell¶
>>> 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>'