From 0a33f1262d5e494c341738fc16532954b4b283d2 Mon Sep 17 00:00:00 2001
From: Tim Otten <totten@civicrm.org>
Date: Tue, 20 Jun 2017 14:59:33 -0700
Subject: [PATCH] asset-builder.md - Copy-edits
---
docs/framework/asset-builder.md | 39 +++++++++++++++++----------------
1 file changed, 20 insertions(+), 19 deletions(-)
diff --git a/docs/framework/asset-builder.md b/docs/framework/asset-builder.md
index 2aa66ff4..b77e46fb 100644
--- a/docs/framework/asset-builder.md
+++ b/docs/framework/asset-builder.md
@@ -1,13 +1,17 @@
# Asset Builder
The `AssetBuilder` manages lazily-generated assets, such as aggregated
-JS/CSS files. Lazy assets are simultaneously:
+JS/CSS files. The first time you request a lazy asset, the `AssetBuilder`
+fires a hook which builds the content. The content is stored in a cache
+file, and subsequent requests use the cache file.
+
+Lazy assets are simultaneously dynamic and static:
* __Dynamic__: They vary depending on the current system configuration.
- You cannot lock-in a correct version of the asset because each
- installation may need a slightly different version.
- * __Static__: Within a given site, the asset is not likely to change.
- It could even be served directly by the web-server (without the overhead
+ You cannot lock-in a singular version of the asset because each
+ deployment may need a slightly different version.
+ * __Static__: Within a given deployment, the asset is not likely to change.
+ It can even be served directly by the web-server (without the overhead
of PHP/CMS/Civi bootstrap)
!!! note "Example: Batch loading Angular HTML"
@@ -16,19 +20,16 @@ JS/CSS files. Lazy assets are simultaneously:
bigger file and reduce the number of round-trip HTTP requests.
This asset is _dynamic_ because extensions can add or modify HTML
- templates. Two different sites would have different HTML templates
- (depending on the mix of extensions). Yet, within a particular
- site/configuration, the content is _static_ because the HTML doesn't
+ templates. Two different deployments would have different HTML
+ templates (depending on the mix of extensions). Yet, within a
+ particular deployment, the content is _static_ because the HTML doesn't
actually change at runtime.
-The `AssetBuilder` addresses this use-case with *lazy* building. Assets are
-not distributed as part of `git` or `tar.gz`. Rather, the first time you
-use an asset, it fires off a hook which builds the content. The content is
-stored in a cache file.
-
!!! tip "Tip: Caching and development"
If you are developing or patching assets, then the caching behavior may
- get distracting. To bypass the cache, enable **debug mode**.
+ get distracting. To bypass the cache, navigate to
+ __Administer > System Settings > Debugging__ and enable debugging.
+
## Usage: Simple asset
@@ -112,12 +113,12 @@ function mymodule_civicrm_buildAsset($asset, $params, &$mimeType, &$content) {
```
!!! note "Note: Parmaters and caching"
- Each combination of ($asset,$params) will be cached separately.
+ Each combination of (`$asset`,`$params`) will be cached separately.
-!!! tip "Tip: Economize parameter size"
- In debug mode, all parameters are passed as part of the URL. `AssetBuilder`
- will try to compress them, but fundamentally: long `$params` will produce
- long URLs.
+!!! tip "Tip: Economize on parameters"
+ In debug mode, all parameters are passed as part of the URL.
+ `AssetBuilder` will try to compress them, but it can only do so much.
+ Fundamentally, long `$params` will produce long URLs.
## Other considerations
--
GitLab