diff --git a/README.md b/README.rst similarity index 72% rename from README.md rename to README.rst index 2f5a57f..cba8e99 100644 --- a/README.md +++ b/README.rst @@ -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 +~~~~~ + +:: -##### html5 +html5 +~~~~~ + +:: -##### xhtml +xhtml +~~~~~ + +:: -### 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. +:: + -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. + +:: -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:: -#### js +js +-- Renders a script tag with the correct include. +:: + {% js "myfile.js" %} -#### css +css +--- Renders a 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:: -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:: -### 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. \ No newline at end of file