mirror of
https://github.com/kennethreitz-archive/django-mediasync.git
synced 2026-06-05 23:40:18 +00:00
converted readme to rst. gross.
This commit is contained in:
Jeremy Carbaugh
+152
-84
@@ -1,4 +1,7 @@
|
||||
# django-mediasync
|
||||
|
||||
================
|
||||
django-mediasync
|
||||
================
|
||||
|
||||
One of the more significant development roadblocks we have relates to local vs.
|
||||
deployed media. Ideally all media (graphics, css, scripts) development would
|
||||
@@ -20,53 +23,48 @@ All code is under a BSD-style license, see LICENSE for details.
|
||||
|
||||
Source: http://github.com/sunlightlabs/django-mediasync/
|
||||
|
||||
## Requirements
|
||||
|
||||
- python >= 2.4 (with zlib)
|
||||
------------
|
||||
Requirements
|
||||
------------
|
||||
|
||||
- django >= 1.0
|
||||
|
||||
- boto >= 1.8d
|
||||
* python >= 2.4 (with zlib)
|
||||
* django >= 1.0
|
||||
* boto >= 1.8d
|
||||
|
||||
|
||||
## Installation
|
||||
|
||||
To install run
|
||||
|
||||
python setup.py install
|
||||
|
||||
which will install the application into python's site-packages directory.
|
||||
-------------
|
||||
Configuration
|
||||
-------------
|
||||
|
||||
|
||||
## Configuration
|
||||
settings.py
|
||||
===========
|
||||
|
||||
|
||||
### settings.py
|
||||
|
||||
Add to INSTALLED_APPS:
|
||||
Add to *INSTALLED_APPS*::
|
||||
|
||||
'mediasync'
|
||||
|
||||
Add the proper __MEDIA\_ROOT__ setting:
|
||||
Add the proper *MEDIA_ROOT* setting::
|
||||
|
||||
MEDIA_ROOT = '/path/to/media'
|
||||
|
||||
Additionally, replace the existing __MEDIA\_URL__ setting with:
|
||||
Additionally, replace the existing *MEDIA_URL* setting with::
|
||||
|
||||
MEDIA_URL = '/devmedia/'
|
||||
|
||||
__MEDIA\_URL__ is the URL that will be used in debug mode. Otherwise,
|
||||
the __MEDIA\_URL__ will be loaded from the backend settings.
|
||||
*MEDIA_URL* is the URL that will be used in debug mode. Otherwise,
|
||||
the *MEDIA_URL* will be loaded from the backend settings.
|
||||
|
||||
The following settings dict must also be added::
|
||||
|
||||
The following settings dict must also be added:
|
||||
|
||||
MEDIASYNC = {
|
||||
'BACKEND': 'path.to.backend',
|
||||
}
|
||||
|
||||
If you want to use a different media URL than that specified
|
||||
in __settings.MEDIA\_URL__, you can add __MEDIA\_URL__ to the __MEDIASYNC__
|
||||
settings dict:
|
||||
in *settings.MEDIA_URL*, you can add *MEDIA_URL* to the *MEDIASYNC*
|
||||
settings dict::
|
||||
|
||||
MEDIASYNC = {
|
||||
...
|
||||
@@ -74,7 +72,7 @@ settings dict:
|
||||
...
|
||||
}
|
||||
|
||||
Same goes for __MEDIA\_ROOT__:
|
||||
Same goes for *MEDIA_ROOT*::
|
||||
|
||||
MEDIASYNC = {
|
||||
...
|
||||
@@ -87,81 +85,105 @@ the provided backends as well as directions on implementing your own.
|
||||
|
||||
If the client supports media expiration, all files are set to expire 365 days
|
||||
after the file was synced. You may override this value by adding
|
||||
__EXPIRATION\_DAYS__ to the MEDIASYNC settings dict.
|
||||
*EXPIRATION_DAYS* to the MEDIASYNC settings dict.
|
||||
|
||||
::
|
||||
|
||||
'EXPIRATION_DAYS': 365 * 10, # expire in 10 years
|
||||
|
||||
The media URL is selected based on the __DEBUG__ attribute in settings.py.
|
||||
The media URL is selected based on the *DEBUG* attribute in settings.py.
|
||||
When *True*, media will be served locally instead of from S3. Sometimes it is
|
||||
necessary to serve media from S3 even when __DEBUG__ is *True*. To force remote
|
||||
serving of media, set __SERVE\_REMOTE__ to *True*.
|
||||
necessary to serve media from S3 even when *DEBUG* is *True*. To force remote
|
||||
serving of media, set *SERVE_REMOTE* to *True*.
|
||||
|
||||
::
|
||||
|
||||
'SERVE_REMOTE': True,
|
||||
|
||||
#### DOCTYPE
|
||||
DOCTYPE
|
||||
-------
|
||||
|
||||
link and script tags are written using XHTML syntax. The rendering can be
|
||||
overridden by using the __DOCTYPE__ setting. Allowed values are *'html4'*,
|
||||
overridden by using the *DOCTYPE* setting. Allowed values are *'html4'*,
|
||||
*'html5'*, or *'xhtml'*.
|
||||
|
||||
::
|
||||
|
||||
'DOCTYPE': 'xhtml',
|
||||
|
||||
For each doctype, the following tags are rendered:
|
||||
|
||||
##### html4
|
||||
html4
|
||||
~~~~~
|
||||
|
||||
::
|
||||
|
||||
<link rel="stylesheet" href="..." type="text/css" media="...">
|
||||
<script type="text/javascript" charset="utf-8" src="..."></script>
|
||||
|
||||
##### html5
|
||||
html5
|
||||
~~~~~
|
||||
|
||||
::
|
||||
|
||||
<link rel="stylesheet" href="..." type="text/css" media="...">
|
||||
<script src="..."></script>
|
||||
|
||||
##### xhtml
|
||||
xhtml
|
||||
~~~~~
|
||||
|
||||
::
|
||||
|
||||
<link rel="stylesheet" href="..." type="text/css" media="..." />
|
||||
<script type="text/javascript" charset="utf-8" src="..."></script>
|
||||
|
||||
|
||||
### Backends
|
||||
Backends
|
||||
========
|
||||
|
||||
mediasync now supports pluggable backends. A backend is a Python module that
|
||||
contains a Client class that implements a mediasync-provided BaseClient class.
|
||||
|
||||
#### S3
|
||||
S3
|
||||
--
|
||||
|
||||
::
|
||||
|
||||
'BACKEND': 'mediasync.backends.s3',
|
||||
|
||||
##### Settings
|
||||
Settings
|
||||
~~~~~~~~
|
||||
|
||||
The following settings are required in the mediasync settings dict.
|
||||
The following settings are required in the mediasync settings dict::
|
||||
|
||||
'AWS_KEY': "s3_key",
|
||||
'AWS_SECRET': "s3_secret",
|
||||
'AWS_BUCKET': "bucket_name",
|
||||
|
||||
Optionally you may specify a path prefix:
|
||||
Optionally you may specify a path prefix::
|
||||
|
||||
'AWS_PREFIX': "key_prefix",
|
||||
|
||||
Assuming a correct DNS CNAME entry, setting __AWS\_BUCKET__ to
|
||||
__assets.sunlightlabs.com__ and __AWS\_PREFIX__ to __myproject/media__ would
|
||||
Assuming a correct DNS CNAME entry, setting *AWS_BUCKET* to
|
||||
*assets.sunlightlabs.com* and *AWS_PREFIX* to *myproject/media* would
|
||||
sync the media directory to http://assets.sunlightlabs.com/myproject/media/.
|
||||
|
||||
Amazon allows users to create DNS CNAME entries to map custom domain names
|
||||
to an AWS bucket. MEDIASYNC can be configured to use the bucket as the media
|
||||
URL by setting __AWS\_BUCKET\_CNAME__ to *True*.
|
||||
URL by setting *AWS_BUCKET_CNAME* to *True*.
|
||||
|
||||
::
|
||||
|
||||
'AWS_BUCKET_CNAME': True,
|
||||
|
||||
##### Tips
|
||||
Tips
|
||||
~~~~
|
||||
|
||||
Since files are given a far future expires header, one needs a way to do
|
||||
"cache busting" when you want the browser to fetch new files before the expire
|
||||
date arrives. One of the best and easiest ways to accomplish this is to alter
|
||||
the path to the media files with some sort of version string using the key
|
||||
prefix setting:
|
||||
prefix setting::
|
||||
|
||||
'AWS_PREFIX': "myproject/media/v20001201",
|
||||
|
||||
@@ -170,27 +192,30 @@ up being http://assets.sunlightlabs.com/myproject/media/v20001201/. Whenever
|
||||
you need to update the media files, simply update the key prefix with a new
|
||||
versioned string.
|
||||
|
||||
A __CACHE\_BUSTER__ settings can be added to the main __MEDIASYNC__ settings
|
||||
A *CACHE_BUSTER* settings can be added to the main *MEDIASYNC* settings
|
||||
dict to add a query string parameter to all media URLs. The cache buster can
|
||||
either be a value or a callable which is passed the media URL as a parameter.
|
||||
|
||||
::
|
||||
|
||||
'CACHE_BUSTER': 1234567890,
|
||||
|
||||
The above setting will generate a media path similar to:
|
||||
The above setting will generate a media path similar to::
|
||||
|
||||
http://yourhost.com/url/to/media/image.png?1234567890
|
||||
|
||||
#### Custom backends
|
||||
Custom backends
|
||||
---------------
|
||||
|
||||
You can create a custom backend by creating a Python module containing a Client
|
||||
class. This class must inherit from mediasync.backends.BaseClient. Additionally,
|
||||
you must implement two methods:
|
||||
you must implement two methods::
|
||||
|
||||
def remote_media_url(self, with_ssl):
|
||||
...
|
||||
|
||||
remote\_media\_url returns the full base URL for remote media. This can be
|
||||
either a static URL or one generated from mediasync settings.
|
||||
*remote_media_url* returns the full base URL for remote media. This can be
|
||||
either a static URL or one generated from mediasync settings::
|
||||
|
||||
def put(self, filedata, content_type, remote_path, force=False):
|
||||
...
|
||||
@@ -198,15 +223,18 @@ either a static URL or one generated from mediasync settings.
|
||||
put is responsible for pushing a file to the backend storage.
|
||||
|
||||
* filedata - the contents of the file
|
||||
* content\_type - the mime type of the file
|
||||
* remote\_path - the remote path (relative from remote\_media\_url) to which
|
||||
* content_type - the mime type of the file
|
||||
* remote_path - the remote path (relative from remote_media_url) to which
|
||||
the file should be written
|
||||
* force - if True, write file to remote storage even if it already exists
|
||||
|
||||
### urls.py
|
||||
urls.py
|
||||
=======
|
||||
|
||||
Add a reference to mediasync.urls in your main urls.py file.
|
||||
|
||||
::
|
||||
|
||||
urlpatterns = ('',
|
||||
...
|
||||
url(r'^', include('mediasync.urls)),
|
||||
@@ -214,23 +242,29 @@ Add a reference to mediasync.urls in your main urls.py file.
|
||||
)
|
||||
|
||||
|
||||
## Features
|
||||
--------
|
||||
Features
|
||||
--------
|
||||
|
||||
### Ignored Directories
|
||||
Ignored Directories
|
||||
===================
|
||||
|
||||
Any directory in __MEDIA\_ROOT__ that is hidden or starts with an underscore
|
||||
Any directory in *MEDIA_ROOT* that is hidden or starts with an underscore
|
||||
will be ignored during syncing.
|
||||
|
||||
|
||||
### Template Tags
|
||||
Template Tags
|
||||
=============
|
||||
|
||||
When referring to media in HTML templates you can use custom template tags.
|
||||
These tags can by accessed by loading the media template tag collection.
|
||||
|
||||
::
|
||||
|
||||
{% load media %}
|
||||
|
||||
If you'd like to make the mediasync tags global, you can add the following to
|
||||
your master urls.py file:
|
||||
your master urls.py file::
|
||||
|
||||
from django.template import add_to_builtins
|
||||
add_to_builtins('mediasync.templatetags.media')
|
||||
@@ -238,128 +272,161 @@ your master urls.py file:
|
||||
Some backends (S3) support https URLs when the requesting page is secure.
|
||||
In order for the https to be detected, the request must be placed in the
|
||||
template context with the key 'request'. This can be done automatically by adding
|
||||
'django.core.context_processors.request' to __TEMPLATE\_CONTEXT\_PROCESSORS__
|
||||
'django.core.context_processors.request' to *TEMPLATE_CONTEXT_PROCESSORS*
|
||||
in settings.py
|
||||
|
||||
#### media_url
|
||||
media_url
|
||||
---------
|
||||
|
||||
Renders the MEDIA_URL from settings.py with trailing slashes removed.
|
||||
|
||||
::
|
||||
|
||||
<img src="{% media_url %}/images/stuff.png">
|
||||
|
||||
MEDIA\_URL takes an optional argument that is the media path. Using the argument allows mediasync to add the CACHE_BUSTER to the URL if one is specified.
|
||||
MEDIA_URL takes an optional argument that is the media path. Using the argument allows mediasync to add the CACHE_BUSTER to the URL if one is specified.
|
||||
|
||||
::
|
||||
|
||||
<img src="{% media_url '/images/stuff.png' %}">
|
||||
|
||||
If __CACHE\_BUSTER__ is set to 12345, the above example will render as:
|
||||
If *CACHE_BUSTER* is set to 12345, the above example will render as::
|
||||
|
||||
<img src="http://assets.example.com/path/to/media/images/stuff.png?12345">
|
||||
|
||||
|
||||
#### js
|
||||
js
|
||||
--
|
||||
|
||||
Renders a script tag with the correct include.
|
||||
|
||||
::
|
||||
|
||||
{% js "myfile.js" %}
|
||||
|
||||
|
||||
#### css
|
||||
css
|
||||
---
|
||||
|
||||
Renders a <link> tag to include the stylesheet. It takes an optional second
|
||||
parameter for the media attribute; the default media is "screen, projector".
|
||||
|
||||
::
|
||||
|
||||
{% css "myfile.css" %}
|
||||
{% css "myfile.css" "screen" %}
|
||||
|
||||
|
||||
#### css_print
|
||||
css_print
|
||||
---------
|
||||
|
||||
Shortcut to render as a print stylesheet.
|
||||
|
||||
::
|
||||
|
||||
{% css_print "myfile.css" %}
|
||||
|
||||
which is equivalent to
|
||||
|
||||
::
|
||||
|
||||
{% css "myfile.css" "print" %}
|
||||
|
||||
### Writing Style Sheets
|
||||
Writing Style Sheets
|
||||
====================
|
||||
|
||||
Users are encouraged to write stylesheets using relative URLS. The media
|
||||
directory is synced with S3 as is, so relative local paths will still work
|
||||
when pushed remotely.
|
||||
|
||||
::
|
||||
|
||||
background: url(../images/arrow_left.png);
|
||||
|
||||
|
||||
### Joined files
|
||||
Joined files
|
||||
============
|
||||
|
||||
When serving media in production, it is beneficial to combine JavaScript and
|
||||
CSS into single files. This reduces the number of connections the browser needs
|
||||
to make to the web server. Fewer connections can dramatically decrease page
|
||||
load times and reduce the server-side load.
|
||||
|
||||
Joined files are specified in the __MEDIASYNC__ dict using __JOINED__. This is
|
||||
Joined files are specified in the *MEDIASYNC* dict using *JOINED*. This is
|
||||
a dict that maps individual media to an alias for the joined files.
|
||||
|
||||
::
|
||||
|
||||
'JOINED': {
|
||||
'styles/joined.css': ['styles/reset.css','styles/text.css'],
|
||||
'scripts/joined.js': ['scripts/jquery.js','scripts/processing.js'],
|
||||
},
|
||||
|
||||
Files listed in __JOINED__ will be combined and pushed to S3 with the name of
|
||||
Files listed in *JOINED* will be combined and pushed to S3 with the name of
|
||||
the alias. The individual CSS files will also be pushed to S3. Aliases must end
|
||||
in either .css or .js in order for the content-type to be set appropriately.
|
||||
|
||||
The existing template tags may be used to refer to the joined media. Simply use
|
||||
the joined alias as the argument:
|
||||
the joined alias as the argument::
|
||||
|
||||
{% css_print "joined.css" %}
|
||||
|
||||
When served locally, template tags will render an HTML tag for each of the files
|
||||
that make up the joined file:
|
||||
that make up the joined file::
|
||||
|
||||
<link rel="stylesheet" href="/media/styles/reset.css" type="text/css" media="screen, projection" />
|
||||
<link rel="stylesheet" href="/media/styles/text.css" type="text/css" media="screen, projection" />
|
||||
|
||||
When served remotely, one HTML tag will be rendered with the name of the joined file:
|
||||
When served remotely, one HTML tag will be rendered with the name of the joined file::
|
||||
|
||||
<link rel="stylesheet" href="http://bucket.s3.amazonaws.com/styles/joined.css" type="text/css" media="screen, projection" />
|
||||
|
||||
### Media Path Shortcuts
|
||||
Media Path Shortcuts
|
||||
====================
|
||||
|
||||
In some cases, all CSS and JS files will be in their own directory. It can be a
|
||||
pain to write full paths from __MEDIA\_ROOT__ when they can be inferred from the
|
||||
pain to write full paths from *MEDIA_ROOT* when they can be inferred from the
|
||||
type of media being used. Shortcuts can be used in template tags and the joined
|
||||
files configuration if the default paths to JS and CSS files are set.
|
||||
|
||||
::
|
||||
|
||||
'CSS_PATH': 'styles',
|
||||
'JS_PATH': 'scripts',
|
||||
|
||||
When these paths are set, you can leave them off of the media paths in template
|
||||
tags. Using the above path settings, _styles/reset.css_ and _scripts/jquery.js_
|
||||
can be referred to using:
|
||||
tags. Using the above path settings, styles/reset.css and scripts/jquery.js
|
||||
can be referred to using::
|
||||
|
||||
{% css 'reset.css' %}
|
||||
{% js 'jquery.js' %}
|
||||
|
||||
|
||||
## Running MEDIASYNC
|
||||
-----------------
|
||||
Running MEDIASYNC
|
||||
-----------------
|
||||
|
||||
::
|
||||
|
||||
./manage.py syncmedia
|
||||
|
||||
## Change Log
|
||||
----------
|
||||
Change Log
|
||||
----------
|
||||
|
||||
### 2.0 (in progress)
|
||||
2.0 (in progress)
|
||||
=================
|
||||
|
||||
* add pluggable backends
|
||||
* settings refactor
|
||||
* allow override of __settings.MEDIA\_URL__
|
||||
* allow override of *settings.MEDIA_URL*
|
||||
* Improvements to the logic that decides which files to sync. Safely ignore
|
||||
a wider variety of hidden files/directories.
|
||||
* Make template tags aware of whether the current page is SSL-secured. If it
|
||||
is, ask the backend for an SSL media URL (if implemented by your backend).
|
||||
|
||||
### 1.0.1
|
||||
1.0.1
|
||||
=====
|
||||
|
||||
* add application/javascript and application/x-javascript to JavaScript mimetypes
|
||||
* break out of CSS and JS mimetypes
|
||||
@@ -368,6 +435,7 @@ can be referred to using:
|
||||
|
||||
Thanks to Rob Hudson and Peter Sanchez for the changes in this release.
|
||||
|
||||
### 1.0
|
||||
1.0
|
||||
===
|
||||
|
||||
Initial release.
|
||||
Reference in New Issue
Block a user