Better docs for integrating with jQuery et al

[petehunt]

Apparently the docs aren't too clear on this: https://plus.google.com/+IanBicking/posts/D1W2yqRh3BB

We need to have a section in the docs that talks about how to integrate with third party plugins in more detail, and stress the difference between mounting and updating.

[vjeux]

Mention the Reconciliation page to understand when an element is removed/added vs updated: http://facebook.github.io/react/docs/reconciliation.html

[ianb]

FWIW, here's roughly the code that was causing me a problem:

Widget = React.createClass({
  render: function () {
    var open = null;
    if (this.props.showOpen) {
      open = <a data-toggle="tooltip" title="do it">!</a>;
    }
    return (
      <div class="widget"> ...
        {open}
      </div>
    );
  },
  componentDidMount: function () {
    $(this.getDOMNode()).find("*[data-toggle=tooltip]").tooltip();
  }
});

I think my mistaken theory was that componentDidMount would be called whenever that node was rendered. But instead when I rendered a list like [<Widget showOpen={false} />] and then with setState [<Widget showOpen={true} />, <Widget showOpen={false} />] even though the first element changed in a significant way, componentDidMount wasn't called. Maybe! I never really figured out what was going on. Now I've just decided to never conditionally construct elements that I want to tweak after rendering.

Also I eventually found the Bootstrap example in the repository, but it wasn't linked up from anywhere. In addition to the modal example, an example like a tooltip would be nice, because tooltips don't "own" the element, they are a kind of annotation on an existing element.

[petehunt]

Hey @ianb -

I think that this is because the tooltip component doesn't change its behavior when the underlying DOM is manipulated. What happens if you do this instead?

Widget = React.createClass({
  render: function () {
    var open = null;
    if (this.props.showOpen) {
      open = <a data-toggle="tooltip" title="do it">!</a>;
    }
    return (
      <div class="widget"> ...
        {open}
      </div>
    );
  },
  componentDidMount: function () {
    this.runTooltipPlugin();
  },
  componentDidUpdate: function(prevProps) {
    // You can remove this condition if you don't care how often the
    // plugin is called
    if (prevProps.showOpen !== this.props.showOpen) {
      this.runTooltipPlugin();
    }
  },
  runTooltipPlugin: function() {
    $(this.getDOMNode()).find("*[data-toggle=tooltip]").tooltip();
  }
});

[zpao]

Still plans on doing this anytime soon? I think we probably want to do a more complete revamp and reconsider some of our docs, maybe in the 1.0 timeframe.

[gaearon]

We should do it, but keeping a bunch of old issues around doesn't help visibility.
Putting this as umbrella item in #8060.