index.rst (12456B)
1 ================= 2 Custom Formatters 3 ================= 4 5 Custom formatters allow a website to control the display of variables within the :doc:`Web Console <../web_console/index>` and the :doc:`Debugger <../debugger/index>`. 6 7 This feature can be particularly useful for web applications that deal with complex object structures, or for JavaScript frameworks that define objects for native variables, or for frameworks that compile to JavaScript like ClojureScript. 8 9 Custom formatting enhances the debugging process by displaying a more intuitive and informative representation of their variables. 10 11 Enabling custom formatting 12 ************************** 13 14 To enable custom formatting, switch to the :doc:`Settings <../settings/index>` panel and check the option called "Enable custom formatters" under "Advanced settings". The setting takes effect the next time you open the DevTools. 15 16 .. image:: enable-custom-formatters-setting.png 17 18 API 19 *** 20 21 Once custom formatters are enabled, websites can customize how certain variables are displayed in the Web Console and the Debugger. This is achieved by defining custom formatters using a global array called ``devtoolsFormatters``. Each entry in this array represents a specific formatter that may handle a particular type of variable. If there's no formatter defined for a variable, it is displayed using its default formatting. 22 23 Custom formatter structure 24 -------------------------- 25 26 Each formatter must at least contain a ``header`` function. This function must either return a JsonML array or ``null``. If ``null`` is returned, the ``header`` function of the next entry in ``devtoolsFormatters`` will be called. If all ``header`` functions return ``null``, then the object will be displayed with the default rendering of the DevTools. 27 28 In addition to the ``header`` function, a formatter can contain a ``body`` function. The existence of a ``body`` is indicated by the ``hasBody`` function. If ``hasBody`` returns ``true``, the object can be expanded to show more details. The actual body is then returned by the ``body`` function. Like the ``header`` function, it can either return a JsonML object or ``null``. 29 30 All three functions take the object as the first parameter and an optional configuration object as the second parameter, which allows passing additional information. 31 32 Here's a more detailed description of the functions: 33 34 ``header(object, config)`` 35 Returns a JsonML array or ``null``. If ``null`` is returned, the default format is used to display the object. 36 The ``config`` parameter is optional. This parameter can be passed using the special ``object`` template (see :ref:`generating-child-elements`). 37 38 ``hasBody(object, config)`` 39 Returns a boolean indicating whether the object can be expanded to show more details. 40 The ``config`` parameter is optional. This parameter can be passed using the special ``object`` template (see :ref:`generating-child-elements`). 41 42 ``body(object, config)`` 43 Returns a JsonML array or ``null``. If ``null`` is returned, the default format is used to display the object. 44 The ``config`` parameter is optional. This parameter can be passed using the special ``object`` template (see :ref:`generating-child-elements`). 45 46 HTML template format 47 -------------------- 48 49 Each HTML template is encoded in a format based on the `JsonML <http://www.jsonml.org/>`_ standard. Each element is represented as list in the format 50 51 .. code-block:: javascript 52 53 [tagName, {"style": "name: value; ..."}, child1, …] 54 55 The following HTML tags are allowed: 56 57 ``<span>``, ``<div>``, ``<ol>``, ``<ul>``, ``<li>``, ``<table>``, ``<tr>``, and ``<td>``. 58 59 The optional ``style`` attribute may contain a string of CSS declarations. CSS properties that can be applied are: 60 61 - ``align*`` 62 - ``background*`` (``background-image`` only allows ``data:`` URLs) 63 - ``border*`` 64 - ``box*`` 65 - ``clear`` 66 - ``color`` 67 - ``cursor`` 68 - ``display`` 69 - ``float`` 70 - ``font*`` 71 - ``justify*`` 72 - ``line*`` 73 - ``margin*`` 74 - ``padding*`` 75 - ``position`` (only the values ``static`` and ``relative`` are accepted) 76 - ``text*`` 77 - ``transition*`` 78 - ``outline*`` 79 - ``vertical-align`` 80 - ``white-space`` 81 - ``word*`` 82 - ``writing*`` 83 - ``width`` 84 - ``min-width`` 85 - ``max-width`` 86 - ``height`` 87 - ``min-height`` 88 - ``max-height`` 89 90 A child can be another element, a string, or an object reference. 91 92 .. _generating-child-elements: 93 94 Generating child elements 95 ------------------------- 96 97 Child elements can be created by defining a special ``object`` template. The format of this template is: 98 99 .. code-block:: javascript 100 101 ["object", {"object": objectToInspect, "config": configObject}] 102 103 Examples 104 ******** 105 106 Simple example 107 -------------- 108 109 Let's take a look at a simple example to illustrate the concept of custom formatters: 110 111 .. code-block:: javascript 112 113 window.devtoolsFormatters = [ 114 { 115 header: variable => { 116 if (variable.hasOwnProperty('foo')) { 117 return [ 118 'span', { 119 'style': ` 120 font-family: "Comic Sans MS", fantasy; 121 font-size: 3rem; 122 color: green; 123 ` 124 }, 125 'foo' 126 ]; 127 } 128 return null; 129 } 130 } 131 ]; 132 133 In the example above, a custom formatter is defined for a variable. The `header` property of the formatter is a function that determines how the variable is displayed. In this case, if the variable has a property named `foo`, it will be rendered as a `<span>` element with a specific style. It will be logged to the Web Console like this: 134 135 .. image:: simple-custom-formatter-example.png 136 137 Complete example 138 ---------------- 139 140 For a more complex example, let's consider displaying a `Date` object: 141 142 .. code-block:: html 143 144 <!DOCTYPE html> 145 <html> 146 <head> 147 <title>Custom formatter for dates</title> 148 </head> 149 <body> 150 <script> 151 window.devtoolsFormatters = [ 152 { 153 header: obj => { 154 if (obj instanceof Date) { 155 return ['div', {'style': 'font-weight: bold;'}, 156 `Date: ${obj.toLocaleDateString()} ${obj.toLocaleTimeString()}` 157 ]; 158 } 159 return null; 160 }, 161 hasBody: obj => obj instanceof Date, 162 body: obj => { 163 if (obj instanceof Date) { 164 return ['div', {}, 165 ['div', {}, `Year: ${obj.getFullYear()}`], 166 ['div', {}, `Month: ${obj.getMonth() + 1}`], 167 ['div', {}, `Day: ${obj.getDate()}`], 168 ['div', {}, `Hour: ${obj.getHours()}`], 169 ['div', {}, `Minutes: ${obj.getMinutes()}`], 170 ['div', {}, `Seconds: ${obj.getSeconds()}`] 171 ]; 172 } 173 return null; 174 } 175 } 176 ]; 177 </script> 178 </body> 179 </html> 180 181 With this custom formatter, a ``Date`` object logged to the console will display the date and time in a formatted manner, along with separate breakdowns of its individual components. Within the console, the object will be logged like this: 182 183 .. image:: date-custom-formatter-example.png 184 185 Example with object references 186 ------------------------------ 187 188 .. code-block:: html 189 190 <!DOCTYPE html> 191 <html> 192 <head> 193 <meta charset="utf-8"/> 194 <title>Menu custom formatter</title> 195 <script> 196 const menu = [ 197 { 198 url: '/', 199 text: 'Home', 200 }, 201 { 202 url: '/nested', 203 text: 'Nested', 204 subitems: [ 205 { 206 url: '/nested/1', 207 text: 'Nested 1' 208 }, 209 { 210 url: '/nested/2', 211 text: 'Nested 2', 212 subitems: [ 213 { 214 url: '/nested/2/1', 215 text: 'Nested 2.1' 216 }, 217 { 218 url: '/nested/2/2', 219 text: 'Nested 2.2' 220 } 221 ] 222 }, 223 { 224 url: '/nested/3', 225 text: 'Nested 3' 226 } 227 ] 228 }, 229 { 230 url: '/about', 231 text: 'About' 232 }, 233 { 234 url: '/contact', 235 text: 'Contact' 236 } 237 ]; 238 239 window.devtoolsFormatters = [ 240 { 241 header: (obj, config) => { 242 if (obj instanceof Array && obj.every(item => item.hasOwnProperty('url') && item.hasOwnProperty('text'))) { 243 return ['div', {'style': 'font-weight: bold;'}, `Menu: ${obj.length} entries`]; 244 } 245 return null; 246 }, 247 hasBody: obj => obj instanceof Array && obj.every(item => item.hasOwnProperty('url') && item.hasOwnProperty('text')), 248 body: (obj, config) => { 249 const levelColors = ['red', 'blue', 'green']; 250 if (config === undefined) { 251 config = { level: 0 }; 252 } else { 253 config.level++; 254 } 255 256 return ['div', {'style': `margin-left: 15px; color: ${levelColors[config.level % levelColors.length]}`}, ...obj.map(item => { 257 const subitem = ['div', ['div', `${item.text}: ${item.url}`]]; 258 if (item.hasOwnProperty('subitems')) { 259 subitem.push(['object', {'object': item.subitems, config: {level: config.level}}]); 260 } 261 return subitem; 262 })]; 263 } 264 } 265 ]; 266 console.log(menu); 267 </script> 268 </head> 269 <body> 270 </body> 271 </html> 272 273 This example displays a menu object with nested subitems. The custom formatter is recursive, so it will display all subitems as well. The output of this example looks like this: 274 275 .. image:: menu.png 276 277 Debugging Custom Formatters 278 *************************** 279 280 If a custom formatter contains an error, an error message is logged to the console, explaining the issue. Whenever possible, the error message also includes a source link pointing to the exact location of the error within the code. 281 282 .. image:: custom-formatter-error.png 283 284 Further tips 285 ************ 286 287 - Analyze the structure and behavior of the variables you intend to format, understanding the key properties or class hierarchy that differentiate them. 288 - When testing for an object's type, use ``instanceof`` if the objects are instances of a specific class. If the objects are plain objects, use ``hasOwnProperty`` to check for particular properties. 289 - Test your formatters with different types of variables to ensure they function as expected and handle various cases accurately. 290 - Nest formatters by :ref:`generating-child-elements` to display complex objects in a more readable manner. 291 - Use the ``config`` parameter to pass additional information to the formatter, such as the current level of recursion. 292 - If you have multiple formatters, keep in mind to check for the type of the object in each formatter, and return ``null`` if the object is not of the expected type. Otherwise, the formatter will be applied to all objects, which may result in unexpected behavior. 293 - Choose your formatting wisely. For large objects it may be better to display only a summary of the object, and allow the user to expand it if needed. 294 - Each logged object will call the formatters hooks, which can have an impact on performance. So you should aim for small and fast hooks. 295 296 Existing Formatters 297 ******************* 298 299 There are existing formatters available that cover different needs. Some examples include: 300 301 - `andrewdavey/immutable-devtools <https://github.com/andrewdavey/immutable-devtools>`_: Custom formatter for Immutable-js values 302 - `disjukr/vector-devtools <https://github.com/disjukr/vector-devtools#vector-devtools>`_: Custom formatter for vector values 303 - `binaryage/cljs-devtools <https://github.com/binaryage/cljs-devtools#cljs-devtools---->`_: Collection of DevTools enhancements for ClojureScript developers 304 - Three.js object formatters: 305 306 - `twitter.com/thespite/status/656585905151545344 <https://twitter.com/thespite/status/656585905151545344>`_ 307 - `twitter.com/thespite/status/656499298230734849 <https://twitter.com/thespite/status/656499298230734849>`_