FormidableLabs / ecology

Documentation generator for collections of react components.
MIT License
107 stars 13 forks source link

flag for ignoring some component playground text when rendering a code block #33

Open boygirl opened 8 years ago

boygirl commented 8 years ago

Define and render arbitrary components inside a ```playground_no_render... code block without them showing up in the rendered block of source code. This would give us the ability to do things like display a dropdown to determine props, add an export to gist button, etc without having to show the code responsible in the docs, and without having to add a bunch of specialized functionality to ecology.

credit for this idea belongs to @paulathevalley

coopy commented 8 years ago

The upside with an implementation that puts the responsibility on the documentation author to define any additional component behaviors is that we don't have to add any features to Ecology or Component Playground (other than perhaps un-deprecating noRender, ahem).

I can see a couple of downsides, though:

  1. It adds boilerplate to otherwise clean code examples in the ecology.md file, making it less readable as an un-augmented Markdown file (e.g. https://github.com/FormidableLabs/victory-chart/blob/master/docs/victory-chart/ecology.md).
  2. Said boilerplate has to be repeated for each playground snippet you want to add special behavior to.
  3. It potentially hides the code the user is modifying through a dropdown or similar, making it non-obvious what is being changed

An alternative solution is to add features to Ecology that allows modifying the source before passing it to component-playground, and that renders additional UI:

  1. Define a place to inject data:

    ```playground_no_render
    <MyComponent data={data}/>
    data=[];
  2. Add new Ecology props to define options and where to put a selected option:
    • replaceOptionExpression={/data=(.*);/}
    • userOptions={{set1: [1, 2, 3], set2: [4, 5, 6]}}
  3. Either pass a userOptionComponent prop to Ecology with a component that has a defined interface for rendering options and calling back on option change, or just have Ecology magically rendering a dropdown with the passed userOptions.

@kenwheeler do you have some bright flash of insight into this?

kenwheeler commented 8 years ago

@coopy What if we provided a wrapper component via scope, and provided a way to reference it using a regexable pattern in the first line of the code text?

Like:

@@MyScopeProvidedWrapper
kenwheeler commented 8 years ago

Then again, because we'd be concatting, we'd then also have to probably add a template marker in the wrapper for where the wrapped code is inserted. Slippery slope.

coopy commented 8 years ago

What if we simply wrote an example with a wrapper component including data sources that passes data to the Victory component, letting it all hang out in the rendered example code block? It would be an easy win and would give us an idea of whether we need to hide the non-VIctory stuff in the docs.

coopy commented 8 years ago

The actual definition of the wrapper component would just be passed in scope, to reduce the clutter.

kenwheeler commented 8 years ago

That would totally work

coopy commented 8 years ago

@paulathevalley Let's do it this minimal-style ^ for a selected victory component first to see what it looks like.

We'll write a DataSource component or something that renders a dropdown of options, and passes the selected data to its wrapped child the Victory component.