docs/api/javascript-api.md
# ReactOnRails JavaScript API
## CSRF protection
Rails has built-in protection for Cross-Site Request Forgery (CSRF), see [Rails Documentation](http://guides.rubyonrails.org/security.html#cross-site-request-forgery-csrf). To nicely utilize this feature in JavaScript requests, React on Rails provides two helpers that can be used as following for POST, PUT or DELETE requests:
```js
import ReactOnRails from 'react-on-rails';
// reads from DOM csrf token generated by Rails in <%= csrf_meta_tags %>
csrfToken = ReactOnRails.authenticityToken();
// compose Rails specific request header as following { X-CSRF-Token: csrfToken, X-Requested-With: XMLHttpRequest }
header = ReactOnRails.authenticityHeaders(otherHeader);
```
If you are using [jquery-ujs](https://github.com/rails/jquery-ujs) for AJAX calls, then these helpers are not needed because the [jquery-ujs](https://github.com/rails/jquery-ujs) library updates header automatically, see [jquery-ujs documentation](https://robots.thoughtbot.com/a-tour-of-rails-jquery-ujs#cross-site-request-forgery-protection).
## API
The best source of docs is the main [ReactOnRails.js](https://github.com/shakacode/react_on_rails/node_package/src/ReactOnRails.js) file. Here's a quick summary. No guarantees that this won't be outdated!
```js
/**
* Main entry point to using the react-on-rails npm package. This is how Rails will be able to
* find you components for rendering. Components get called with props, or you may use a
* "Render-Function" to return a React component or an object with the following shape:
* { renderedHtml, redirectLocation, error }.
* For server rendering, if you wish to return multiple HTML strings from a Render-Function,
* you may return an Object from your Render-Function with a single top level property of
* renderedHtml. Inside this Object, place a key called componentHtml, along with any other
* needed keys. This is useful when you using side effects libraries like react helmet.
* Your Ruby code with get this Object as a Hash containing keys componentHtml and any other
* custom keys that you added:
* { renderedHtml: { componentHtml, customKey1, customKey2 } }
* See the example in https://www.shakacode.com/react-on-rails/docs/javascript/react-helmet
* @param components (key is component name, value is component)
*/
register(components)
/**
* Allows registration of store generators to be used by multiple react components on one Rails
* view. store generators are functions that take one arg, props, and return a store. Note that
* the setStore API is different in tha it's the actual store hydrated with props.
* @param stores (key is store name, value is the store generator)
*/
registerStore(stores)
/**
* Allows retrieval of the store by name. This store will be hydrated by any Rails form props.
* Pass optional param throwIfMissing = false if you want to use this call to get back null if the
* store with name is not registered.
* @param name
* @param throwIfMissing Defaults to true. Set to false to have this call return undefined if
* there is no store with the given name.
* @returns Redux Store, possibly hydrated
*/
getStore(name, throwIfMissing = true )
/**
* Renders or hydrates the react element passed. In case react version is >=18 will use the new api.
* @param domNode
* @param reactElement
* @param hydrate if true will perform hydration, if false will render
* @returns {Root|ReactComponent|ReactElement|null}
*/
reactHydrateOrRender(domNode, reactElement, hydrate)
/**
* Set options for ReactOnRails, typically before you call ReactOnRails.register
* Available Options:
* `traceTurbolinks: true|false Gives you debugging messages on Turbolinks events
*/
setOptions(options)
/**
* Allow directly calling the page loaded script in case the default events that trigger react
* rendering are not sufficient, such as when loading JavaScript asynchronously with TurboLinks:
* More details can be found here:
* https://www.shakacode.com/react-on-rails/docs/rails/turbolinks
*/
reactOnRailsPageLoaded()
/**
* Returns CSRF authenticity token inserted by Rails csrf_meta_tags
* @returns String or null
*/
authenticityToken()
/**
* Returns header with csrf authenticity token and XMLHttpRequest
* @param {*} other headers
* @returns {*} header
*/
authenticityHeaders(otherHeaders = {})
```