devtools/client/webconsole/README.md

   1 # WebConsole
   2
   3 The WebConsole (webconsole) shows you all the console API calls made by scripts and alerts
   4 you when javascript errors are thrown by a script.
   5 It can also display network logs, and you can evaluate expressions using the console
   6 input, a.k.a. JsTerm. You can read [more](https://firefox-source-docs.mozilla.org/devtools-user/web_console/) about it
   7 to learn all the features and how to use the tool.
   8
   9 ## Run WebConsole
  10
  11 If you want to build the WebConsole inside of the DevTools toolbox (Firefox Devtools Panels),
  12 follow the [simple Firefox build](https://firefox-source-docs.mozilla.org/devtools/getting-started/build.html)
  13 documentation. Start your compiled firefox and open the Firefox developer tool, you can
  14 then see the WebConsole tab.
  15
  16 ## Code Structure
  17
  18 Top level files are used to launch the WebConsole inside of the DevTools toolbox.
  19 The main files used to run the WebConsole are:
  20
  21 * `main.js` called by devtools toolbox to launch the WebConsole panel.
  22 * `index.html` panel UI and launch scripts.
  23
  24 ### UI
  25
  26 The WebConsole UI is built using [React](https://firefox-source-docs.mozilla.org/devtools/frontend/react.html)
  27 components (in `components/`).
  28
  29 The React application is rendered from `webconsole-wrapper.js`.
  30 It contains 4 top components:
  31 * **ConsoleOutput** (in `ConsoleOutput.js`) is the component where messages are rendered.
  32 * **FilterBar** (in `FilterBar.js`) is the component for the filter bars (filter input and toggle buttons).
  33 * **SideBar** (in `SideBar.js`) is the component that render the sidebar where objects can be placed in.
  34 * **JsTerm** (in `JsTerm.js`) is the component that render the console input.
  35
  36 We prefer stateless component (defined by function) instead of stateful component
  37 (defined by class) unless the component has to maintain its internal state.
  38
  39 ### State
  40
  41 Besides the UI, the WebConsole manages the app state via [Redux].
  42 The following locations define the app state:
  43
  44 * `src/constants.js` constants used across the tool including action and event names.
  45 * `src/actions/` for all actions that change the state.
  46 * `src/reducers/` for all reducers that change the state.
  47 * `src/selectors/` functions that return a formatted version of parts of the app state.
  48
  49 The redux state is a plain javascript object with the following properties:
  50 ```js
  51 {
  52   // State of the filter input and toggle buttons
  53   filters,
  54   // State of the input history
  55   history,
  56   // Console messages data and state (hidden, expanded, groups, …)
  57   messages,
  58   // State of notifications displayed on the output (e.g. self-XSS warning message)
  59   notifications,
  60   // Preferences (persist message, message limit, …)
  61   prefs,
  62   // Interface state (filter bar visible, sidebar visible, …)
  63   ui,
  64 }
  65 ```
  66
  67 ### Tests
  68
  69 [See test/README.md](test/README.md)