From 9b942a4bceb3efe98fbf5799d5e7aace33f9770c Mon Sep 17 00:00:00 2001 From: cewing Date: Tue, 7 Jun 2016 10:42:10 -0700 Subject: update asset specification section --- docs/narr/introduction.rst | 39 ++++++++++++++++++++------------------- 1 file changed, 20 insertions(+), 19 deletions(-) (limited to 'docs') diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst index 41d7d384e..b9771c5f3 100644 --- a/docs/narr/introduction.rst +++ b/docs/narr/introduction.rst @@ -235,25 +235,26 @@ Here's a few views defined as methods of a class instead: .. _intro_asset_specs: -Asset specifications -~~~~~~~~~~~~~~~~~~~~ - -Asset specifications are strings that contain both a Python package name and a -file or directory name, e.g., ``MyPackage:static/index.html``. Use of these -specifications is omnipresent in Pyramid. An asset specification can refer to -a template, a translation directory, or any other package-bound static -resource. This makes a system built on Pyramid extensible because you don't -have to rely on globals ("*the* static directory") or lookup schemes ("*the* -ordered set of template directories") to address your files. You can move -files around as necessary, and include other packages that may not share your -system's templates or static files without encountering conflicts. - -Because asset specifications are used heavily in Pyramid, we've also provided a -way to allow users to override assets. Say you love a system that someone else -has created with Pyramid but you just need to change "that one template" to -make it all better. No need to fork the application. Just override the asset -specification for that template with your own inside a wrapper, and you're good -to go. +Find *your* static assets +~~~~~~~~~~~~~~~~~~~~~~~~~ + +In many web frameworks, the static assets required by an application are kept +in a globally shared location, "the *static* directory". Others use a lookup +scheme, like an ordered set of template directories. Both of these approaches +have problems when it comes to customization. + +Pyramid takes a different approach. Static assets are located using *asset +specifications*, strings that contain reference both to a Python package name +and a file or directory name, e.g. ``MyPackage:static/index.html``. These +specifications are used for templates, JavaScript and CSS, translation files, +and any other package-bound static resource. By using asset specifications, +Pyramid makes it easy to extend your application with other packages without +worrying about conflicts. + +What happens if another Pyramid package you are using provides an asset you +need to customize? Maybe that page template needs better HTML, or you want to +update some CSS. With asset specifications you can override the assets from +other packages using simple wrappers. Examples: :ref:`asset_specifications` and :ref:`overriding_assets_section`. -- cgit v1.2.3