--- /dev/null
+WHAT IS IT?
+-----------
+
+These templatetags is a hack making possible to insert 'content' in
+some (maybe above the current or parent template) places.
+
+More specifically, when we use these tags, there are some Nodes called
+'containers' that are rendered after all other nodes are rendered, but placed
+in it's right posistion. Using this hack, 'containers' may render
+depending on variables in context that were generated by nodes placed anywhere in
+template (maybe after it).
+
+It's very useful in cases when you are reusing some template parts
+very often. For example displaying comment list and comment submit form.
+We write some template and put it into comments.html. Then every time
+we need comments we just {% include "comments.html" %}.
+But what if this part needs some js or css? Then we need to create
+some comments-jscss.html and override some {% block head %}. IMHO this
+is quite inconvenient.
+
+Using this tool we can insert js and css into head
+directly from comments.html
+
+MOTIVATION
+----------
+
+1. Create convenient way to include media resources in head of HTML page.
+2. Handle repetition of resource includes.
+3. Make it possible to require resources from included templates.
+4. Keep the order of resource includes from different places.
+
+INSTALL
+-------
+
+1. (required) add 'insert_above' in INSTALLED_APPS in your settings.py
+
+2. (optional) add these two lines of code somewhere in your project where
+they will run for sure. For example in urls.py
+
+~~~~
+from django.template.loader import add_to_builtins
+add_to_builtins('insert_above.templatetags.insert_tags')
+~~~~
+
+TAGS & FILTERS
+--------------
+
+1. {% insert_handler %}
+2. {% container name %}
+3. {% media_container name %}
+4. {% insert_str container str %}
+5. {% insert container %}{% endinsert %}
+6. media_tag filter simply converts `ga.js` into `<script type='text/javascript' src='/static/ga.js'></script>`
+
+RESTRICTIONS
+------------
+
+1. `{% container %}` or `{% media_container %}` tags must NOT be in other `{% block %}`.
+2. `{% insert_handler %}` ought to be at ther very beginning of base template.
+
+VARIABLES
+---------
+
+1. `IA_USE_MEDIA_PREFIX`, by default True
+2. `IA_MEDIA_PREFIX`, if not set `STATIC_URL` is used, if not set `MEDIA_URL` is used, if not set '/media/' is used
+3. `DEBUG`, if True logs how much time spent on rendering
+4. `IA_JS_FORMAT`, by default `<script type='text/javascript' src='{URL}'></script>`
+5. `IA_CSS_FORMAT`, by default `<link rel='stylesheet' href='{URL}' type='text/css' />`
+6. `IA_MEDIA_EXTENSION_FORMAT_MAP`, by default `{'css' : CSS_FORMAT, '.js' : JS_FORMAT}`
+
+EXAMPLE
+-------
+
+Let's analyze an example.
+
+base.html
+
+~~~~{.html}
+{% insert_handler %}
+<html>
+<head>
+<script>
+<script type='text/javascript' src='{{ MEDIA_URL }}js/jquery.min.js'></script>
+{% media_container media %}
+
+$(document).ready(function(){
+{% container ready %}
+});
+</script>
+</head>
+<body>
+{% block content %}
+{% endblock %}
+</body>
+</html>
+~~~~
+
+Base template creating blocks and containers..
+
+blog/base.html
+
+~~~~{.html}
+{% extends "base.html" %}
+
+{% block content %}
+{% insert_str media "js/mathjax.js" %}
+ {% block header %}{% endblock %}
+ {% block menu %}{% include "blog/menu.html" %}{% endblock %}
+ {% block text %}{% endblock %}
+ {% block footer %}{% endblock %}
+{% endblock %}
+~~~~
+
+Extending content block. Requiring js/mathjax.js resource into 'media' container.
+
+blog/menu.html
+
+~~~~{.html}
+{% insert_str media "js/animated.menu.js" %}
+{% insert_str media "css/animated.menu.css" %}
+{% insert ready %}
+ $('ul.menu').each(function(){
+ $(this).superanimation();
+ });
+{% endinsert %}
+<ul id='blog-menu' class='menu'>
+ <li>link</li>
+ <li>link</li>
+ <li>link</li>
+</ul>
+~~~~
+
+Requiring js/animated.menu.js and css/animated.menu.css into "media" container.
+Inserting javascript code into "ready" container.
+
+blog/post_detail.html
+
+~~~~{.html}
+{% extends "blog/base.html" %}
+
+{% block header %}{{ title }}{% endblock %}
+
+{% block text %}
+{% insert_str media "js/mathjax.js" %}
+{{ text }}
+{% endblock %}
+
+{% block footer %}
+<hr>
+{% endblock %}
+~~~~
+
+Implementing blocks and requiring js/mathjax.js into media.
+
+
+So if we render
+Template('blog/post_detail.html').render(Context({'title': 'Hello', 'text': 'World'}))
+we will get:
+
+~~~~{.html}
+<html>
+<head>
+<script>
+<script type='text/javascript' src='/media/js/jquery.min.js'></script>
+<script type='text/javascript' src='/media/js/mathjax.js'></script>
+<script type='text/javascript' src='/media/js/animated.menu.js'></script>
+<link rel="stylesheet" href="/media/css/animated.menu.css" type="text/css" />
+
+$(document).ready(function(){
+ $('ul.menu').each(function(){
+ $(this).superanimation();
+ });
+});
+</script>
+</head>
+<body>
+Hello
+<ul id='blog-menu' class='menu'>
+ <li>link</li>
+ <li>link</li>
+ <li>link</li>
+</ul>
+World
+<hr>
+</body>
+</html>
+~~~~
+
+What shall be noted?
+-------------------
+
+1. `js/mathjax.js` automatically becomes `<script type='text/javascript' src='/media/js/mathjax.js'></script>`
+and `css/animated.menu.css` becomes `<link rel="stylesheet" href="/media/css/animated.menu.css" type="text/css" />`
+2. inserting from included template is possible
+3. any text may be inserted to any container. Here we insert javascript code in `$(document).ready(function(){});`
+4. `js/mathjax.js` was required twice, but included only once.
+5. The order of included resources is kept.
+
+FIXTURES
+--------
+
+### version 1.0.2
+
+ + **fix MEDIA_URL setting**
+ if STATIC_URL is not set in settings, it's value is None by default in new versions of Django.
+ Now we check if STATIC_URL is None, then use MEDIA_URL
+
+### version 1.0.4
+
+ + added new tag `{% insert_form container form %}`
+ + added new tag `{% insert_form container form.media %}`
+
+## TODOs
+
+1. testing
+2. extending tags
+3. resource bulking
+
git://git.onelab.eu / myslice.git / blobdiff