Styling Molly Bangor University 11 May 2011 Chris Northwood Lead Developer Oxford University Computing Services Mobile Oxford Molly ProjectUniversity of Oxford http://m.ox.ac.uk http://mollyproject.orghttp://www.ox.ac.uk @mobileox @mollyproject
TEMPLATE INHERITANCE• Template inheritance is used to deﬁne a base site template (base.html) which all pages can use to ensure consistent styling along the site
BLOCKS• Base templates deﬁne blocks, which are the areas of the template which can be overridden by child templates
TEMPLATE STRUCTURE base.html Molly comes with a complete set of generic templates which can be used to get a site up and running very quickly.library/base.html Any single template in the hierarchy can be replaced withlibrary/index.html one unique to your site.
CUSTOMISING A TEMPLATE base.html Your template is used library/base.html in preference to the built-in onemysite/templates/ library/index.htmllibrary/index.html
FINER GRAINED CONTROL• Replacing a whole template is often a coarse tool, especially if most of the code remains the same. You lose the beneﬁt of any upstream template improvements.• More useful is the ability to only replace part of the template.• We can do this by extending the original template and only overriding the part of it we’re interested in.
EXTENDING THE ORIGINAL TEMPLATE base.html library/base.htmllibrary/index.html library/index.html
EXTENDING THE ORIGINAL TEMPLATE• However, extending isn’t quite that simple, your replacement template hides the original, so you can’t address it in the traditional method• To get around this, Molly also exposes all of its templates under the preﬁx of ‘molly_default’
library/index.html (in Molly tree) library/index.html(in Mobile Oxford tree)
• This can be done at any point up the hierarchy• At the very least, most sites will want to customise base.html• Documentation for the full list of templates, and overrideable blocks within them is incomplete, the best way to determine what’s available is to read the code.
• Template paths from the point of view of Django are relative to the containing ‘templates’ folder, i.e., ‘molly/ apps/places/templates/places/entity_detail.html’ is referenced as ‘places/entity_detail.html’• Core templates (404.html, etc) are stored in the ‘templates’ subdirectory of Molly. Templates for apps are stored in the ‘templates’ subdirectory of that app.
• If a template isn’t customisable enough for you, raise an issue on http://issues.mollyproject.org and additional blocks will be added to the main Molly code.
SPECIAL FILES• Molly treats the ﬁles smart.css, dumb.css and smart.js specially - served to appropriate device classes• For serving, each app’s smart.css, etc, ﬁle is concatenated with all the other apps, to result in one smart.css, etc, for the entire site• This means there’s no need to reference these ﬁles speciﬁcally within your template
MINIFICATION• Well-understood and widely used• “Compresses” code by removing whitespace, replacing variable names with single letters, etc• Combined with gzip at server-time makes a signiﬁcant difference to ﬁle size• Obfuscates code and makes it hard to debug
DJANGO-COMPRESS• Disabled when debug mode is on• Any ﬁle ending ‘.css’ or ‘.js’ is miniﬁed• Adds a timestamp to the ﬁlename which allows for clients to aggressively cache ﬁles, whilst also working around cache breakages• Templates can access these ﬁles using the compress_css and compress_js template tags, rather than linking to the ﬁles directly
DJANGO-STATICFILES• An external library prior to Django 1.3, now part of core Django• Copies all media ﬁles from various places to a single ‘media’ directory in your site• Also allows for overriding of ﬁles - placing an image in your site_media folder will cause that ﬁle to be used, rather than the default one - useful for replacing logos, etc
WHERE MOLLY KEEPS FILES• Images, CSS and JS that are associated with an app are stored in the ‘static’ subdirectory of that app• The ‘media’ folder in the main Molly directory contains site-wide ﬁles - core icons, CSS, logos, etc• The ‘site_media’ folder in your site contains your manual overrides
BEWARE!• Django-staticﬁles copies all of the ﬁles to a ‘media’ folder in your site folder• This is where your webserver should serve the ﬁles from - but these are not the source ﬁles!• Files in here should not be edited, as they will be replaced the next time media is rebuilt - only edit the source ﬁles, or replace a core Molly ﬁle in your ‘site_media’ folder
HOW TO OVERRIDE A FILE• Find the relative path name of the image to be replaced (either through the documentation, exploring the source tree, or by looking at the URL of the item)• Place the ﬁle you would like to replace that ﬁle under the same path/ﬁlename in your ‘site_media’ folder• Rebuild the media (e.g., re-run the quickinstaller)