Instantsearch.js: Provide simple examples wrapping well known React UI libraries

[vvo]

We need to show that our components are easily pluggable on existing libraries like:

• react-toolbox
• OnsenUI

see http://stackoverflow.com/a/23495996/147079

[bobylito]

The list is way longer :) Can we choose some of them? What are the criteria to choose one over the other (number of stars on github maybe?)?

What are the compatibility issues that we can encounter?

---

For info, stars of the projects quoted in the SO thread (as of now):

• Material UI, 19241
• React-bootstrap 7126
• React-toolbox 4098
• Onsen-ui 3283
• Elemental 2910
• Belle, 1584
• Rebass 1569
• Khan academy components, 793
• Grommet 788
• Stardust 366
• Pivotal 299
• React-foundation 277
• React-islands 105
• React-topui 87

[vvo]

Thanks for creating the list!

Can we choose some of them?

Yes for a first start we should only do the obvious ones. The goal is only to show that's possible and profit from the possible popularity of thoses communities.

I would say:

• react-toolbox
• material UI
• react-select

And then emphasis that we are basically compatible with any of those UI libraries, once your understand the HOC strategy we provide, you can apply it to anything.

[mthuret]

I started to look after integrated instantsearch-react with material-ui.

In term of output, I was thinking as a simple page displaying some of the most important items (live examples + source code).

For example for material-ui, maybe we can demonstrate our integration with: TextField, Checkbox, List and Select Field.

[vvo]

Yes if you already started a simple material UI example create a new branch and let's move on.

A simple searchbox + facet list + select (sort by) + hits should be sufficient to demonstrate what's achievable.

For now we can focus on having the live example.

Displaying the associated source code in a good way I am not sure how to do that and do it well (technically, design/page ui wise). It might be tricky and maybe not that critical.

Because for a full example (not a widget example) there's potentially a lot of code, so just linking to github could be nice enough, and better in the end. React developers should be used to it.

Maybe what we can do is a landing Material UI + react-instantsearch page that explains the high level concepts and show a single code example on how to connect those two libraries. Then link to the live example and link to the full code (github)

[bobylito]

Why not a Codepen for that?

[mthuret]

Yes 👍 .

So is it ok for everyone if we start with a 3rd-party React UI libraries page with :

• High level concepts
• Full examples displayed with Codepen ? (starting maybe only with material-ui first).

[bobylito]

Sounds good to me.

[vvo]

I am not in favor of codepen for now for all our documentation purpose in react-instantsearch.

Mostly because:

• you cannot use import module from '..' in codepen
• you cannot split your JS code in multiple files, so you have to sometime complexify your code style to make it fit in a single file (and it can be harder to read the interesting parts)
• every library you want to use needs to be available in an UMD build (not always the case, plus you have to try and see if it's actually available, big loss of time here)
• I don't feel like codepen demos are something very relevant to React communities (= I did not see a lot of React libraries using this). We do see a lot of creative, beautiful demos on codepen, less documentation oriented examples
• live editing is interesting but only when on codepen.io which requires a context switch (from our website to their UI). Otherwise it's too small to be usable
• If you are used to github, browsing and reading code on codepen can in the end be a frustative experience given the size of the example you are browsing (Ok how do I see the code, argh it's very small..). That's what you get when trying to combine two things that are hard to combine (live demo of a full webpage and code)
• "bad" live coding experience, it's a lot harder to code in codepen than your editor (syntax errors, no react-hot-loader..). Sure you can copy paste code from your editor but then it's again frustrating.

I propose what I proposed here: https://github.com/algolia/instantsearch.js/issues/1257#issuecomment-245851944:

• react/material-ui.html:
  
  
  
  • Hello we are compatible with material-ui
  
  
  • what is material-ui
  
  
  • basic concepts of wiring material-ui and react-instantsearch
  
  
  • link to github source (context switch, but reading code on github is a lot easier)
  
  
  • link to demo
  
  
• react/material-ui-demo.html: live demo showing regular demos like we have our examples/ecommerce..
• From experience with react-algoliasearch-helper, doing

And we can reuse the same pattern for one or two others very popular libraries.
And we can have a root "Linking to library X" webpage that explains basically the high level concepts of linking any library to react-algoliasearch (which means, explaining HOCS).

What do you think?

[bobylito]

The title of the issue was about example. Examples should be in a live context. and codepen lets you show the code side by side (and you can tweak it, it's not about live coding). My 2 cts on the subject of codepen :P

Cool idea to have an article but wouldn't it make more sense as a blog post article? We could promote it, etc etc.

[vvo]

We shown how to use material ui, that's enough for a first release.

[HemalR]

We shown how to use material ui, that's enough for a first release.

@vvo Are you able to link to where this has been shown/documented? Tried the forum, google, the docs.. I must be missing something.

Thanks in advance!

Edit - Is it this: https://community.algolia.com/instantsearch.js/react/guide/Connectors.html ?

[vvo]

@HemalR here's an example with material ui: https://github.com/algolia/instantsearch.js/tree/v2/docgen/src/examples/material-ui

What is the library you are trying to plug with react-instantsearch?

[HemalR]

Thanks for that. I was initially using Algolia's React component. I managed to follow the example and get a rudimentary version working (based on the example shown at https://github.com/algolia/instantsearch.js/blob/v2/packages/react-instantsearch/examples/autocomplete/src/App-Hits-And-Facets.js )

I had slight problems with:

• How to style them and whether the Algolia provided css files will be sufficient
• How to add selection handlers on the list (currently it is unelectable)
• How to add keyboard events to enable selection using arrow keys/the enter key

---

In the end, using this code below has done the trick - I'm not sure whether that is an inefficient way to do it or if it can be improved? Will happily post it in the community forums if it looks good and might help others trying to build an autocomplete dropdown style search box:

import React, { Component } from 'react';
import AutoComplete from 'material-ui/AutoComplete';
import algoliaSearch from 'algoliasearch/reactnative';

class SearchAlgolia extends Component {
    constructor(props) {
        super (props);
        this.state = {
            searchResults: [],
            searchText: ''
        };

        this.handleUpdate = this.handleUpdate.bind(this);
        this.onSelect = this.onSelect.bind(this);

        //Algolia
        this.client = algoliaSearch(`AlgoliaId`, `API Key`);
        this.index = this.client.initIndex(`getstarted_actors`);
    }
    handleUpdate(value) {
        this.setState({searchText: value});
        this.index.search(value, (err, content)=>{
            if (err) {
                console.log(err);
                this.setState({searchResults: [`Error! - ${err.message}`]})
            } else {
                console.log(content);
                this.setState({searchResults: content.hits})
            }
        });
    }
    onSelect(chosenRequest, index) {
        console.log(chosenRequest);
    }
    render() {
        const dataSourceConfig = {
            text: `name`,
            value: 'objectID'
        };
        return (
            <div>
                <AutoComplete
                    floatingLabelText="Search"
                    floatingLabelFixed={true}
                    hintText="Type here..."
                    filter={AutoComplete.noFilter}
                    dataSource={this.state.searchResults}
                    dataSourceConfig={dataSourceConfig}
                    maxSearchResults={12}
                    onNewRequest={this.onSelect}
                    onUpdateInput={this.handleUpdate}
                    fullWidth={true}
                    style={{width: "80%"}}
                  searchText={this.state.searchText}
                />
            </div>
        )
    }
};

export default SearchAlgolia;

[vvo]

Given your code example I think you should be able to remove some good boilerplate code by reusing InstantSearch + connectHits, can you try that and open a new issue or https://discourse.algolia.com/ post if so? Thanks.