BookStack Code Mirror - bookstack/blob - dev/docs/javascript-code.md

   1 # BookStack JavaScript Code
   2
   3 BookStack is primarily server-side-rendered, but it uses JavaScript sparingly to drive any required dynamic elements. Most JavaScript is applied via a custom, and very thin, component interface to keep code organised and somewhat reusable.
   4
   5 JavaScript source code can be found in the `resources/js` directory. This gets bundled and transformed by `esbuild`, ending up in the `public/dist` folder for browser use. Read the [Development > "Building CSS & JavaScript Assets"](development.md#building-css-&-javascript-assets) documentation for details on this process.
   6
   7 ## Components
   8
   9 This section details the format for JavaScript components in BookStack. This is a really simple class-based setup with a few helpers provided.
  10
  11 ### Defining a Component in JS
  12
  13 ```js
  14 class Dropdown {
  15     setup() {
  16         this.container = this.$el;
  17         this.menu = this.$refs.menu;
  18         this.toggles = this.$manyRefs.toggle;
  19
  20         this.speed = parseInt(this.$opts.speed);
  21     }
  22 }
  23 ```
  24
  25 All usage of $refs, $manyRefs and $opts should be done at the top of the `setup` function so any requirements can be easily seen.
  26
  27 Once defined, the component has to be registered for use. This is done in the `resources/js/components/index.js` file. You'll need to import the component class then add it to `componentMapping` object, following the pattern of other components.
  28
  29 ### Using a Component in HTML
  30
  31 A component is used like so:
  32
  33 ```html
  34 <div component="dropdown"></div>
  35
  36 <!-- or, for multiple -->
  37
  38 <div components="dropdown image-picker"></div>
  39 ```
  40
  41 The names will be parsed and new component instance will be created if a matching name is found in the `components/index.js` componentMapping.
  42
  43 ### Element References
  44
  45 Within a component you'll often need to refer to other element instances. This can be done like so:
  46
  47 ```html
  48 <div component="dropdown">
  49     <span refs="dropdown@toggle othercomponent@handle">View more</span>
  50 </div>
  51 ```
  52
  53 You can then access the span element as `this.$refs.toggle` in your component.
  54
  55 Multiple elements of the same reference name can be accessed via a `this.$manyRefs` property within your component. For example, all the buttons in the below example could be accessed via `this.$manyRefs.buttons`.
  56
  57 ```html
  58 <div component="list">
  59     <button refs="list@button">Click here</button>
  60     <button refs="list@button">No, Click here</button>
  61     <button refs="list@button">This button is better</button>
  62 </div>
  63 ```
  64
  65 ### Component Options
  66
  67 ```html
  68 <div component="dropdown"
  69     option:dropdown:delay="500"
  70     option:dropdown:show>
  71 </div>
  72 ```
  73
  74 Will result with `this.$opts` being:
  75
  76 ```json
  77 {
  78     "delay": "500",
  79     "show": ""
  80 }
  81 ```
  82
  83 #### Component Properties
  84
  85 A component has the below shown properties available for use. As mentioned above, most of these should be used within the `setup()` function to make the requirements/dependencies of the component clear.
  86
  87 ```javascript
  88 // The root element that the compontent has been applied to.
  89 this.$el
  90
  91 // A map of defined element references within the compontent.
  92 // See "Element References" above.
  93 this.$refs
  94
  95 // A map of defined multi-element references within the compontent.
  96 // See "Element References" above.
  97 this.$manyRefs
  98
  99 // Options defined for the compontent.
 100 this.$opts
 101 ```
 102
 103 ## Global JavaScript Helpers
 104
 105 There are various global helper libraries in BookStack which can be accessed via the `window`. The below provides an overview of what's available.
 106
 107 ```js
 108 // HTTP service
 109 window.$http.get(url, params);
 110 window.$http.post(url, data);
 111 window.$http.put(url, data);
 112 window.$http.delete(url, data);
 113 window.$http.patch(url, data);
 114
 115 // Global event system
 116 // Emit a global event
 117 window.$events.emit(eventName, eventData);
 118 // Listen to a global event
 119 window.$events.listen(eventName, callback);
 120 // Show a success message
 121 window.$events.success(message);
 122 // Show an error message
 123 window.$events.error(message);
 124 // Show validation errors, if existing, as an error notification
 125 window.$events.showValidationErrors(error);
 126
 127 // Translator
 128 // Take the given plural text and count to decide on what plural option
 129 // to use, Similar to laravel's trans_choice function but instead
 130 // takes the direction directly instead of a translation key.
 131 window.trans_plural(translationString, count, replacements);
 132
 133 // Component System
 134 // Parse and initialise any components from the given root el down.
 135 window.components.init(rootEl);
 136 // Get the first active component of the given name
 137 window.components.first(name);
 138 ```