# 🔌 React HTML Connector · [![](https://travis-ci.org/schalkventer/react-html-connector.svg?branch=master)](https://travis-ci.org/schalkventer/react-html-connect) [![](https://img.shields.io/npm/dm/react-html-connector.svg)](https://www.npmjs.com/package/react-html-connector) [![](https://img.shields.io/badge/stability-experimental-orange.svg)](#package-state) A JavaScript function that eases integration of [React](https://reactjs.org/) (or [Preact](https://preactjs.com/)) components into existing server-side templating. Works with: - [Wordpress](https://wordpress.org) - [Magento](https://www.magento.com/) - [Jekyll](https://jekyllrb.com/) - [Django](https://www.djangoproject.com/) ## Development This package is still considered experimental. This means that it works as intended, however features may still change or get removed in future versions. It is currently used in-house by the team at [OpenUp](https://github.com/orgs/OpenUpSA), however feel free to try it out and provide feedback via Github issues. If it addresses a use-case that is important to you please let me know at [schalk@openup.org.za](mailto:schalk@openup.org.za). ## Usage This package is intended to be imported into a NodeJS module resolver like [Webpack](https://webpack.js.org/). However it is built in accordance with the [UMD JavaScript specification](https://github.com/umdjs/umd). This means that it can also be pulled directly into the browser via a ` ``` ## Getting Started ##### 1. Make sure that you have the latest version of [NodeJS](https://nodejs.org/en/) installed: ##### 2. Install the package alongside _React_ and _React DOM_: ``` npm install --save react react-dom react-html-connector ``` ##### 3. Create your server-side template: ``` // Users.php

Users List

``` ##### 4. Create your React component ``` // Users.jsx class Users extends React.Component { constructor(props) { super(props); this.state = { showAll: true, } this.toggleShowAll = this.toggleShowAll.bind(this); } toggleShowAll() { this.setState({ showAll: !this.state.showAll }) } render() { return (

{this.props.title}

) } } ``` ##### 4. Connect React component to your 'data-component' attribute: ``` // scripts.jsx import React from 'react'; import ReactDOM from 'react-dom'; import ReactHtmlConnector from 'react-html-connector'; // Create an instance of React HTML Connector. const userConnector = new ReactHtmlConnector(React.createElement, ReactDOM.render); // Define how values from template should be passed as props. const query = { title: 'innerHTML', users: [ { id: 'number', active: 'boolean', name: 'innerHTML', } ] } // Call `connect` to bind the 'User' component and associated properties to your template. userConnector.connect(Users, 'Users', query) ``` ##### 5. Congrats! Your component should be bound to the `data-component="Users"` attribute. View a live Codepen example of the above at [https://codepen.io/schalkventer/pen/oyJeqg](https://codepen.io/schalkventer/pen/oyJeqg). ## API ### ReactHtmlConnector The `react-html-connector` package exposes a JavaScript class. The constructor associated with this class returns an object with various methods that can be called to ease integration of React with server-side templating. ``` const connectorInstance = new ReactHtmlConnector(createElement, render, options) ``` ##### `createElement ` _required_ Needs to be a React (or a React-like) `createElement` method (for example: `React.createElement`). By passing this manually you are able to pass a specific version of React or React-like library. In order to use this package with Preact you need to pass [Hyperscript](https://github.com/hyperhype/hyperscript) instead of the React `createElement` method (for example: `Preact.h`). ##### `render ` _required_ Needs to be a React (or React-like) `render` method (for example: `ReactDOM.render`). By passing this manually you are able to pass a specific version of React DOM or React-like library. In order to use this package with Preact you need to pass the Preact render method instead of the React DOM `render` method (for example: `Preact.render`). ##### `options ` _optional | default: null_ Accepts an object of key-value pairs that set specific change the way the returned methods work. See the upcoming parameters for a list of valid `options` values. ##### `options.scope `_optional | default: window.document.body_ Restricts the returned connect and nodeQuery methods' searchable range to a specifc HTML node and its children. Useful for avoid conflicting attribute names used elsewhere in your templates. ##### `options.attribute `_optional | default: 'data-component'_ Changes the name of the attribute used to bind components to your templates. Useful when `data-component` is already in use or you want to use a more specific attribute like `data-react-compoment`. ##### `options.library <'react' | 'preact'>` _optional | default: 'react'_ Changes how the returned connect method parses params. For example, in Preact you need to pass a fourth parameter into `preact.render` to ensure that a component replaces the targeted HTML node, and not simply appends it to the existing content. ##### `options.store ` _optional | default: null_ Description pending... ##### `options.provider ` _optional | default: null_ Description pending... ### Methods returned from ReactHtmlConnector constructor: ``` const connectorInstance = new ReactHtmlConnector(createElement, render, options); connectorInstance.connect(_component_, _query_); const customQuery = connectorInstance.nodeQuery(_query_); ``` ##### `connectorInstance.connect.component ` _required_ The React (or React-like) component that will be bound to a specific `data-component` attribute in your template. ##### `connectorInstance.connect.name ` _required_ The string value used in the `data-component` attribute of the HTML node you want to target. You can have multiple of the same `data-component` string in a template to initialise multiple instances of a component. Note that the node itself (and everything inside) will be swapped out for the React component. ##### `connectorInstance.connect.query ` _optional | default: {}_ Object literal that instructs what (and how) values should be parsed from your template into props and passed to the component. The object passed to this parameter uses a custom schema, loosely inspired by [GraphQl](https://graphql.org/). This schema will be documented in more detail at some point (See [Issue #2](https://github.com/schalkventer/react-html-connector/issues/2). Alternatively, a callback function can be passed to this parameter to override the default querying behaviour above. This callback automatically passes the HTML node itself as its first argument. It also passes the `nodeQuery` method (covered below) as it's second argument. The callback should return an object that will then be passed as [props](https://reactjs.org/docs/components-and-props.html) to the React component. #### `connectorInstance.nodeQuery.query ` _optional | default: {}_ Similar to `instance.connect.query`, however this method allows you to use the custom querying method independantly of the `instance.connect` method. Useful if you want parse values in your template independantly or before the component is rendered.