diff options
author | Thomas Waldmann <tw AT waldmann-edv DOT de> | 2014-03-24 14:16:27 +0100 |
---|---|---|
committer | Thomas Waldmann <tw AT waldmann-edv DOT de> | 2014-03-24 14:16:27 +0100 |
commit | 71de4fa7c526e5b7e2dd42157ff35315c8dc5c64 (patch) | |
tree | 4a5a3e2f56e0bcc3fdc548632db21a79f48942b4 | |
parent | 7df7707345584d2538871208c73f732d35d3d701 (diff) | |
download | xstatic-71de4fa7c526e5b7e2dd42157ff35315c8dc5c64.tar.gz |
add usage docs
-rw-r--r-- | docs/source/using.rst | 58 |
1 files changed, 57 insertions, 1 deletions
diff --git a/docs/source/using.rst b/docs/source/using.rst index f915434..d464734 100644 --- a/docs/source/using.rst +++ b/docs/source/using.rst @@ -1,4 +1,60 @@ Using XStatic ============= -... + +The XStatic package does only offer the most fundamental functions for +dealing with static files (and this is very much the point of XStatic: +being low-fat). + +The only bit of code is in XStatic.main, class XStatic. + +When you instantiate an object of this class, it'll read the uppercase +attributes from the xstatic module you give to it and make them available +as lowercase instance attributes. + +E.g. (we use the xstatic-jquery package as example, see also the code +example below): + +* xstatic.pkg.jquery.NAME -> xs.name +* xstatic.pkg.jquery.BASE_DIR -> xs.base_dir + +Thus, you have all the metadata that came with the xstatic-jquery package +easily available. + +Example code to setup local file serving +---------------------------------------- + +:: + + from xstatic.main import XStatic + # names below must be package names + mod_names = [ + 'jquery', 'bootstrap', 'font_awesome', + ] + pkg = __import__('xstatic.pkg', fromlist=mod_names) + for mod_name in mod_names: + mod = getattr(pkg, mod_name) + xs = XStatic(mod, root_url='/static', provider='local', protocol='http') + serve_files.update([(xs.name, xs.base_dir)]) + + # now, serve_files has the mapping name -> base_dir for all the xstatic + # packages you want to use. you can use it in your python code to set + # up the static file serving. + + +In this example, we wanted to use the local static files we got within the +xstatic-* packages. + +For some packages there is also a CDN available, you can use it by giving the +appropriate provider (not 'local') and protocol (see the xstatic-* package metadata about which cdnnames and protocols are available for the package): + +:: + xs = XStatic(mod, provider='cdnname', protocol='https') + print xs.base_url + +Note: base_url is often a str (as you maybe have expected). But it also can +be a dict (which maps relative pathes to full urls) - we needed that for some +CDNs where one can not just compute the full url from base url + relative path. + +The Xstatic class also has a simple url_for(relative_path) method which +computes the full url - for local URLs as well as for CDN URLs. |