summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorChris McDonough <chrism@plope.com>2015-06-23 15:10:23 -0400
committerChris McDonough <chrism@plope.com>2015-06-23 15:10:23 -0400
commitf3b0c71139da13c88a660ef6edbe4d37ecb9e508 (patch)
tree980843f9df248a84b0094ed9090edadd0a0e7dea /docs
parent713bc5f2785636327f4cee40d958bcff83afa9c5 (diff)
parent24b249c5afe5e3d97e327046252a0b3e42152580 (diff)
downloadpyramid-f3b0c71139da13c88a660ef6edbe4d37ecb9e508.tar.gz
pyramid-f3b0c71139da13c88a660ef6edbe4d37ecb9e508.tar.bz2
pyramid-f3b0c71139da13c88a660ef6edbe4d37ecb9e508.zip
Merge branch 'master' of github.com:Pylons/pyramid
Diffstat (limited to 'docs')
-rw-r--r--docs/narr/assets.rst87
-rw-r--r--docs/narr/viewconfig.rst4
-rw-r--r--docs/quick_tutorial/debugtoolbar.rst24
-rw-r--r--docs/quick_tutorial/ini.rst6
-rw-r--r--docs/tutorials/wiki2/authorization.rst12
5 files changed, 109 insertions, 24 deletions
diff --git a/docs/narr/assets.rst b/docs/narr/assets.rst
index d6bc8cbb8..fc02b3f7d 100644
--- a/docs/narr/assets.rst
+++ b/docs/narr/assets.rst
@@ -512,6 +512,93 @@ time at start up as a cachebust token:
.. index::
single: static assets view
+CSS and JavaScript source and cache busting
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Often one needs to refer to images and other static assets inside CSS and
+JavaScript files. If cache busting is active, the final static asset URL is
+not available until the static assets have been assembled. These URLs cannot
+be handwritten. Thus, when having static asset references in CSS and
+JavaScript, one needs to perform one of the following tasks.
+
+* Process the files by using a precompiler which rewrites URLs to their final
+ cache busted form.
+
+* Templatize JS and CSS, and call ``request.static_url()`` inside their
+ template code.
+
+* Pass static URL references to CSS and JavaScript via other means.
+
+Below are some simple approaches for CSS and JS programming which consider
+asset cache busting. These approaches do not require additional tools or
+packages.
+
+Relative cache busted URLs in CSS
++++++++++++++++++++++++++++++++++
+
+Consider a CSS file ``/static/theme/css/site.css`` which contains the
+following CSS code.
+
+.. code-block:: css
+
+ body {
+ background: url(/static/theme/img/background.jpg);
+ }
+
+Any changes to ``background.jpg`` would not appear to the visitor because the
+URL path is not cache busted as it is. Instead we would have to construct an
+URL to the background image with the default ``PathSegmentCacheBuster`` cache
+busting mechanism::
+
+ https://site/static/1eeb262c717/theme/img/background.jpg
+
+Every time the image is updated, the URL would need to be changed. It is not
+practical to write this non-human readable URL into a CSS file.
+
+However, the CSS file itself is cache busted and is located under the path for
+static assets. This lets us use relative references in our CSS to cache bust
+the image.
+
+.. code-block:: css
+
+ body {
+ background: url(../img/background.jpg);
+ }
+
+The browser would interpret this as having the CSS file hash in URL::
+
+ https://site/static/ab234b262c71/theme/css/../img/background.jpg
+
+The downside of this approach is that if the background image changes, one
+needs to bump the CSS file. The CSS file hash change signals the caches that
+the relative URL to the image in the CSS has been changed. When updating CSS
+and related image assets, updates usually happen hand in hand, so this does
+not add extra effort to theming workflow.
+
+Passing cache busted URLs to JavaScript
++++++++++++++++++++++++++++++++++++++++
+
+For JavaScript, one can pass static asset URLs as function arguments or
+globals. The globals can be generated in page template code, having access to
+the ``request.static_url()`` function.
+
+Below is a simple example of passing a cached busted image URL in the Jinja2
+template language. Put the following code into the ``<head>`` section of the
+relevant page.
+
+.. code-block:: html
+
+ <script>
+ window.assets.backgroundImage =
+ "{{ '/theme/img/background.jpg'|static_url() }}";
+ </script>
+
+Then in your main ``site.js`` file put the following code.
+
+.. code-block:: javascript
+
+ var image = new Image(window.assets.backgroundImage);
+
.. _advanced_static:
Advanced: Serving Static Assets Using a View Callable
diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst
index fc5ae6dc6..46b2c4f76 100644
--- a/docs/narr/viewconfig.rst
+++ b/docs/narr/viewconfig.rst
@@ -119,7 +119,7 @@ Non-Predicate Arguments
``renderer``
Denotes the :term:`renderer` implementation which will be used to construct
a :term:`response` from the associated view callable's return value.
-
+
.. seealso:: See also :ref:`renderers_chapter`.
This is either a single string term (e.g. ``json``) or a string implying a
@@ -1020,7 +1020,7 @@ there's a ``should_cache`` GET or POST variable:
@view_config(http_cache=3600)
def view(request):
response = Response()
- if not 'should_cache' in request.params:
+ if 'should_cache' not in request.params:
response.cache_control.prevent_auto = True
return response
diff --git a/docs/quick_tutorial/debugtoolbar.rst b/docs/quick_tutorial/debugtoolbar.rst
index a5623ae2a..f11abc493 100644
--- a/docs/quick_tutorial/debugtoolbar.rst
+++ b/docs/quick_tutorial/debugtoolbar.rst
@@ -89,24 +89,24 @@ temporarily.
Extra Credit
============
-# Why don't we add ``pyramid_debugtoolbar`` to the list of
- ``install_requires`` dependencies in ``debugtoolbar/setup.py``?
+#. Why don't we add ``pyramid_debugtoolbar`` to the list of
+ ``install_requires`` dependencies in ``debugtoolbar/setup.py``?
-# Introduce a bug into your application: Change:
+#. Introduce a bug into your application: Change:
- .. code-block:: python
+ .. code-block:: python
- def hello_world(request):
- return Response('<body><h1>Hello World!</h1></body>')
+ def hello_world(request):
+ return Response('<body><h1>Hello World!</h1></body>')
- to:
+ to:
- .. code-block:: python
+ .. code-block:: python
def hello_world(request):
return xResponse('<body><h1>Hello World!</h1></body>')
- Save, and visit http://localhost:6543/ again. Notice the nice
- traceback display. On the lowest line, click the "screen" icon to the
- right, and try typing the variable names ``request`` and ``Response``.
- What else can you discover?
+ Save, and visit http://localhost:6543/ again. Notice the nice
+ traceback display. On the lowest line, click the "screen" icon to the
+ right, and try typing the variable names ``request`` and ``Response``.
+ What else can you discover?
diff --git a/docs/quick_tutorial/ini.rst b/docs/quick_tutorial/ini.rst
index 4e062e575..36942c767 100644
--- a/docs/quick_tutorial/ini.rst
+++ b/docs/quick_tutorial/ini.rst
@@ -131,6 +131,8 @@ Extra Credit
#. The entry point in ``setup.py`` didn't mention ``__init__.py`` when
it declared ``tutorial:main`` function. Why not?
+#. What is the purpose of ``**settings``? What does the ``**`` signify?
+
.. seealso::
:ref:`project_narr`,
:ref:`scaffolding_chapter`,
@@ -138,7 +140,3 @@ Extra Credit
:ref:`environment_chapter`,
:ref:`paste_chapter`
-Extra Credit
-============
-
-#. What is the purpose of ``**settings``? What does the ``**`` signify?
diff --git a/docs/tutorials/wiki2/authorization.rst b/docs/tutorials/wiki2/authorization.rst
index d2ad7a9ca..1d810b05b 100644
--- a/docs/tutorials/wiki2/authorization.rst
+++ b/docs/tutorials/wiki2/authorization.rst
@@ -5,12 +5,12 @@ Adding authorization
====================
:app:`Pyramid` provides facilities for :term:`authentication` and
-::term:`authorization`. We'll make use of both features to provide security
-:to our application. Our application currently allows anyone with access to
-:the server to view, edit, and add pages to our wiki. We'll change that to
-:allow only people who are members of a *group* named ``group:editors`` to add
-:and edit wiki pages but we'll continue allowing anyone with access to the
-:server to view pages.
+:term:`authorization`. We'll make use of both features to provide security
+to our application. Our application currently allows anyone with access to
+the server to view, edit, and add pages to our wiki. We'll change that to
+allow only people who are members of a *group* named ``group:editors`` to add
+and edit wiki pages but we'll continue allowing anyone with access to the
+server to view pages.
We will also add a login page and a logout link on all the pages. The login
page will be shown when a user is denied access to any of the views that
generated by cgit v1.2.3 (git 2.25.1) at 2026-01-11 16:48:01 +0000