|
1 | | -# Editable Demos in Codepen |
| 1 | +# Editable Demos in CodePen |
2 | 2 |
|
3 | 3 | ## Description |
4 | 4 |
|
5 | | -Users will be able to click a button on each demo to open in codepen |
6 | | -to edit. From there the user can edit, save or make other |
| 5 | +Users will be able to click a button on each demo to open in CodePen |
| 6 | +to edit. From there the user can edit, save, or make other |
7 | 7 | modifications to the example. |
8 | 8 |
|
9 | | -## Why Codepen? |
| 9 | +## Why CodePen? |
10 | 10 |
|
11 | | -Codepen appears to be one the most stable and active online sandboxes. |
12 | | -It has less accessibility problems then some of the other tools. |
| 11 | +CodePen appears to be one the most stable and active online sandboxes. |
| 12 | +It also has less accessibility problems than the other tools. |
13 | 13 |
|
14 | 14 | ## How does it work? |
15 | 15 |
|
16 | | -When the user clicks on the **'Edit on codepen'** button, all files including |
17 | | -html, css, js, templates are used to create the new codepen by posting |
18 | | -to the [Codepen API](http://blog.codepen.io/documentation/api/prefill/). An |
19 | | -additional script is appended to the example to initialize the |
| 16 | +When you click the **'Edit on CodePen'** button, all files including |
| 17 | +html, css, js, templates are used to create the new CodePen by posting |
| 18 | +to the [CodePen API](http://blog.codepen.io/documentation/api/prefill/). |
| 19 | +We append an additional script to the new CodePen to initialize the |
20 | 20 | [cache](#asset_cache), which is responsible for serving assets. |
21 | 21 |
|
22 | 22 | ## As a contributor, what do I need to know? |
23 | 23 |
|
24 | 24 | * [SVG images are served from a cache](#asset_cache) |
25 | 25 | * [Adding a new SVG requires a change to the asset cache](#build_cache) |
26 | | -* Anytime a new dependency is added to an example, the [svg-assets-cache.js](../app/svg-assets-cache.js) |
27 | | - will need to be updated with the new dependency and [uploaded to the |
28 | | - CDN](#update_cdn) |
| 26 | +* Anytime adding a new dependency to an example, the [svg-assets-cache.js](../app/svg-assets-cache.js) |
| 27 | + will need to be updated with the new dependency and [uploaded to the CDN](#update_cdn) |
29 | 28 | * Images used in demos must use full paths |
30 | | -* Code examples are modified prior to sending to codepen with the same |
| 29 | +* Code examples are modified prior to sending to CodePen with the same |
31 | 30 | module defined in the [svg-assets-cache.js](../app/svg-assets-cache.js) |
32 | | -* Additional HTML template files located in the demo directory are appended to your index file using `ng-template`. [See docs](https://docs.angularjs.org/api/ng/directive/script) |
| 31 | +* Additional HTML template files located in the demo directory are appended to your index file |
| 32 | + using `ng-template`. [See docs](https://docs.angularjs.org/api/ng/directive/script) |
33 | 33 |
|
34 | 34 | ## <a name="asset_cache"></a> Asset Cache |
35 | 35 |
|
36 | | -SVG images are stored in an asset cache using `$templateCache`. A |
37 | | -script is delivered to codepen that initializes the cache within the |
38 | | -demo module. |
| 36 | +We store SVG images in an asset cache using `$templateCache`. We send a script to CodePen that |
| 37 | +initializes the cache within the demo module. |
39 | 38 |
|
40 | | -### Why is an asset cache needed for Codepen? |
| 39 | +### Why is an asset cache needed for CodePen? |
41 | 40 |
|
42 | | -Components within AngularJS Material at times use icons or SVG. Images |
43 | | -are fetched over http. Without having a server that will allow cross |
44 | | -site scripting (`Access-Control-Allow-Origin: *`), the request will |
45 | | -fail with a [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS) |
46 | | -error. |
| 41 | +Components within AngularJS Material, at times, use icons or SVG images. Images |
| 42 | +fetched over HTTP, without having a server that will allow cross |
| 43 | +site scripting (`Access-Control-Allow-Origin: *`), will fail with a |
| 44 | +[CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS) error. |
47 | 45 |
|
48 | | -The asset cache is intended to bypass any http request for an image |
49 | | -and serve the cached content. |
| 46 | +We use the asset cache to bypass HTTP requests for images by instead serving the cached content. |
50 | 47 |
|
51 | 48 | ### <a name="build_cache"></a> How do I populate the cache? |
52 | 49 |
|
53 | | -* Make all changes necessary to add or update any svg images |
54 | | -* run `./scripts/build-asset-cache.sh | pbcopy` to add an object |
55 | | - literal to your paste buffer. |
56 | | -* paste object literal as `var assetMap = { ... }` in the |
57 | | - [svg-assets-cache.js](../app/svg-assets-cache.js) |
58 | | -* [update](#update_cdn) the CDN with the new script |
59 | | -* commit svg-assets-cache.js |
| 50 | +* Make all changes necessary to add or update any SVG images |
| 51 | +* Run `./scripts/build-asset-cache.sh | pbcopy` to add an object literal to your paste buffer. |
| 52 | +* Paste object literal as `var assetMap = { ... }` in the [svg-assets-cache.js](../app/svg-assets-cache.js) |
| 53 | +* [Update](#update_cdn) the CDN with the new script |
| 54 | +* Commit [svg-assets-cache.js](../app/svg-assets-cache.js) |
60 | 55 |
|
61 | | -### <a name="update_cdn"></a> Update Codepen Asset Cache |
| 56 | +### <a name="update_cdn"></a> Update CodePen Asset Cache |
62 | 57 |
|
63 | | -CDN is located on the Codepen PRO account. |
| 58 | +CDN is located on the CodePen PRO account. |
64 | 59 |
|
65 | | -* Follow the [instructions](http://blog.codepen.io/documentation/pro-features/asset-hosting/#asset-manager) on how to update the script. |
66 | | -* NOTE: be sure to update the script. DO NOT upload a new script. The URL should remain the same |
| 60 | +* Refer to the [instructions](https://blog.codepen.io/documentation/asset-hosting/#asset-manager) |
| 61 | + on how to edit the `svg-assets-cache.js` file. |
| 62 | +* "Edit" and "Save" the `svg-assets-cache.js` file. |
| 63 | + * This has been verified to work even though we no longer have a Pro account. |
| 64 | +* The URL should remain the same. |
| 65 | +* You will not be able to upload a new script since we no longer have a Pro account. |
67 | 66 |
|
68 | 67 | ## Deployment Considerations |
69 | 68 |
|
70 | | -The step to generate and deploy the svg-assets-cache.js is currently a |
71 | | -manual process. Keep in mind that if changes are made to |
72 | | -svg-assets-cache.js then you will need to follow the [steps](#update_cdn) |
73 | | -to update the cache on the CDN. |
| 69 | +The step to generate and deploy the `svg-assets-cache.js` is currently a |
| 70 | +manual process. Keep in mind, you need to follow the steps for [building](#build_cache) and |
| 71 | +[updating](#update_cdn) the asset cache on the CDN when making any changes to a SVG image used by |
| 72 | +a demo or, the docs site. |
0 commit comments