Skip to content

Commit e6f0b5a

Browse files
james-johnston-thumbtackbarryvdh
james-johnston-thumbtack
authored and
barryvdh
committed
Enable AssetProvider to support inline assets (php-debugbar#338)
Add new inline_css, inline_js, and inline_head keys on the AssetProvider::getAssets() function. This allows us to support collectors that require static assets that are not actually saved to a file. Then, update all the asset functions in JavascriptRenderer to support these new keys. An initial use case for this is supporting the HtmlDumper in Symfony’s VarDumper. HtmlDumper only provides the styles and scripts in inline HTML form. The static assets can be customized based on some configuration properties available on the HtmlDumper class. One can actually view the CSS/JS as a long PHP string/heredoc embedded in the HtmlDumper.php source code. They are only accessible via the getDumpHeader function, which returns the CSS/JS in a combined HTML string.
1 parent 4773b2f commit e6f0b5a

File tree

5 files changed

+215
-61
lines changed

5 files changed

+215
-61
lines changed

‎docs/data_collectors.md‎

Lines changed: 33 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -71,16 +71,31 @@ in `JavascriptRenderer::addControl($name, $options)` (see Rendering chapter).
7171

7272
This will have the result of adding a new indicator to the debug bar.
7373

74-
When implementing the Renderable interface, you may use widgets which are not provided
74+
When implementing the `Renderable` interface, you may use widgets which are not provided
7575
with the default install. You can add new assets by implementing the `DebugBar\DataCollector\AssetProvider` interface.
7676

77-
to implement it, you must define the `getAssets()` method. It must return an array with the
77+
To implement it, you must define the `getAssets()` method. It must return an array with the
7878
following keys:
7979

80-
- base\_path: base path of assets (optional, if omitted or null, will use the base path of the JavascriptRenderer)
81-
- base\_url: base url of assets (optional, same as base\_path)
82-
- css: an array of css filenames
83-
- js: an array of javascript filenames
80+
- `base_path`: base path of assets (optional, if omitted or null, will use the base path of the `JavascriptRenderer`)
81+
- `base_url`: base url of assets (optional, same as `base_path`)
82+
- `css`: an array of css filenames
83+
- `js`: an array of javascript filenames
84+
- `inline_css`: an array map of content ID to inline CSS content (not including `<style>` tag)
85+
- `inline_js`: an array map of content ID to inline JS content (not including `<script>` tag)
86+
- `inline_head`: an array map of content ID to arbitrary inline HTML content (typically
87+
`<style>`/`<script>` tags); it will be embedded within the `<head>` element
88+
89+
All keys are optional.
90+
91+
Ideally, you should store static assets in filenames that are returned via the normal `css`/`js`
92+
keys. However, the inline asset elements are useful when integrating with 3rd-party
93+
libraries that require static assets that are only available in an inline format.
94+
95+
The inline content arrays require special string array keys to identify the content: the debug bar
96+
will use them to deduplicate. This is particularly useful if multiple instances of the same asset
97+
provider are used. Inline assets from all collectors are merged together into the same array,
98+
so these content IDs effectively deduplicate the inline assets.
8499

85100
Example:
86101

@@ -104,7 +119,18 @@ Example:
104119
{
105120
return array(
106121
'css' => 'widgets/sqlqueries/widget.css',
107-
'js' => 'widgets/sqlqueries/widget.js'
122+
'js' => 'widgets/sqlqueries/widget.js',
123+
124+
// Ordinarily, inline assets like these should be avoided whenever possible:
125+
'inline_css' => array(
126+
'db_widget_css' => 'div.myelement { color: #000; }',
127+
),
128+
'inline_js' => array(
129+
'db_widget_js' => 'alert("Db widget asset loaded.");'
130+
),
131+
'inline_head' => array(
132+
'db_widget_head' => '<meta content="Arbitrary HTML content">'
133+
)
108134
);
109135
}
110136
}

‎docs/rendering.md‎

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Rendering
22

3-
Rendering is performed using the `DebugBar\JavascriptRenderer̀ class. It contains
3+
Rendering is performed using the `DebugBar\JavascriptRenderer` class. It contains
44
all the useful functions to included the needed assets and generate a debug bar.
55

66
$renderer = $debugbar->getJavascriptRenderer();
@@ -9,15 +9,16 @@ all the useful functions to included the needed assets and generate a debug bar.
99

1010
The debug bar relies on some css and javascript files which needs to be included
1111
into your webpage. They are located in the *src/DebugBar/Resources* folder.
12-
This can be done in four ways:
12+
Additionally, asset providers may provide inline assets that have to be embedded
13+
directly in the HTML. This can be done in four ways:
1314

1415
- Using `JavascriptRenderer::renderHead()` which will returns a string with
1516
the needed script and link tags
1617
- Using [Assetic](https://github.com/kriswallsmith/assetic) and
1718
`JavascriptRenderer::getAsseticCollection()`
18-
- Dumping the assets yourself using `JavascriptRenderer::dumpCssAssets()` and
19-
`JavascriptRenderer::dumpJsAssets()`
20-
- Retrieving the list filenames of assets using `JavascriptRenderer::getAssets()`
19+
- Dumping the assets yourself using `JavascriptRenderer::dumpCssAssets()`,
20+
`JavascriptRenderer::dumpJsAssets()`, and `JavascriptRenderer::dumpHeadAssets()`.
21+
- Retrieving filenames and inline content of assets using `JavascriptRenderer::getAssets()`
2122
and doing something with it
2223

2324
I would recommend using the second method as Assetic is a very powerful asset
@@ -40,7 +41,7 @@ Using `renderHead()`:
4041

4142
Using Assetic:
4243

43-
list($cssCollection, $jsCollection) = $renderer->getAsseticCollection();
44+
list($cssCollection, $jsCollection, $inlineHeadCollection) = $renderer->getAsseticCollection();
4445

4546
Dumping the assets:
4647

@@ -49,7 +50,7 @@ Dumping the assets:
4950

5051
Retrieving the assets:
5152

52-
list($cssFiles, $jsFiles) = $renderer->getAssets();
53+
list($cssFiles, $jsFiles, $inlineCss, $inlineJs, $inlineHead) = $renderer->getAssets();
5354

5455
Note that you can only use the debug bar assets and manage the dependencies by yourself
5556
using `$renderer->setIncludeVendors(false)`. Instead of false, *css* or *js* may be used
@@ -100,7 +101,7 @@ the first argument of ̀render()`.
100101
### Controlling object initialization
101102

102103
You can further control the initialization of the javascript object using `setInitialization()`.
103-
It takes a bitwise value made out of the constants ̀INITIALIZE_CONSTRUCTOR` and `INITIALIZE_CONTROLS`.
104+
It takes a bitwise value made out of the constants `INITIALIZE_CONSTRUCTOR` and `INITIALIZE_CONTROLS`.
104105
The first one controls whether to initialize the variable (ie. `var debugbar = new DebugBar()`). The
105106
second one whether to initialize all the controls (ie. adding tab and indicators as well as data mapping).
106107

‎src/DebugBar/DataCollector/AssetProvider.php‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,21 @@ interface AssetProvider
2121
* - base_url
2222
* - css: an array of filenames
2323
* - js: an array of filenames
24+
* - inline_css: an array map of content ID to inline CSS content (not including <style> tag)
25+
* - inline_js: an array map of content ID to inline JS content (not including <script> tag)
26+
* - inline_head: an array map of content ID to arbitrary inline HTML content (typically
27+
* <style>/<script> tags); it must be embedded within the <head> element
28+
*
29+
* All keys are optional.
30+
*
31+
* Ideally, you should store static assets in filenames that are returned via the normal css/js
32+
* keys. However, the inline asset elements are useful when integrating with 3rd-party
33+
* libraries that require static assets that are only available in an inline format.
34+
*
35+
* The inline content arrays require special string array keys: the caller of this function
36+
* will use them to deduplicate content. This is particularly useful if multiple instances of
37+
* the same asset provider are used. Inline assets from all collectors are merged together into
38+
* the same array, so these content IDs effectively deduplicate the inline assets.
2439
*
2540
* @return array
2641
*/

0 commit comments

Comments
 (0)