Document use of third party react components (#84) #85
Conversation
|
Related to issue #84 |
|
|
||
| Using a third party (Javascript) React component is straightforward for most components. There are two ways of declaring a third party React component in F# - either by declaring a Pojo record for the props or by declaring a Discriminated Union where each case has one field. | ||
|
|
||
| Some components have a [Typescript](https://www.typescriptlang.org/) definition available, either because the component was authored in Typescript or someone created a type definition for the [Definitely Typed project](https://definitelytyped.org/). If this is the case then you can try the [ts2fable tool](https://github.com/fable-compiler/ts2fable) to convert this React component type definition from Typescript to a Fable type declaration - it might need some tweaking but for components with a big API surface this can be a real time safer. |
There was a problem hiding this comment.
Typo: time safer -> saver.
|
|
||
| ## Edgecases | ||
|
|
||
| This documentation needs to be extended to cover [Higher Order Components](https://reactjs.org/docs/higher-order-components.html) and maybe [Context]()https://reactjs.org/docs/context.html, [Fragments](https://reactjs.org/docs/fragments.html) etc. Contributions are welcome! |
There was a problem hiding this comment.
Fix parens for the "Context" link.
| | StrokeColor of string | ||
| ``` | ||
|
|
||
| If one of the props is treated as a string enum in Javascript (e.g. if there is a size prop with the supported values "small", "normal" and "big"), then the `[<StringEnum>]` attribute can be very useful for defining helper types: |
There was a problem hiding this comment.
Maybe adding a link to StringEnum in Fable docs? http://fable.io/docs/interacting.html#stringenum-attribute
|
|
||
| ## Dynamic import using a Pojo | ||
|
|
||
| The dynamic import is similar to the approach above, but instead of declaring a DU you create a Pojo record. This looks more like normal F# code but can be unwieldy if you have a lot of optional props (which is often the case in complex React components) |
There was a problem hiding this comment.
Using the Pojo still makes the props typed, so I'd just say "Importing using a Pojo (plain old JS object) record" and then after this say you can declare props dynamically too:
open Fable.Core.JsInterop
ofImport "Line" "rc-progress" (createObj ["strokeWidth" ==> 5]) []We could also add a note saying the Pojo attribute (link to Fable docs: http://fable.io/docs/interacting.html#plain-old-javascript-objects) is necessary because React only accepts plain JS objects (btw, the attribute won't be necessary in Fable 2, because records will compile directly to pojos).
|
|
||
| ### 3. Define the React component creation function | ||
|
|
||
| Using the `ofImport` function you instruct Fable which component should be instantiated when the creation function is called. |
There was a problem hiding this comment.
Maybe quickly warning about importing default members, which is a common source of confusion. You can also link to Fable docs: http://fable.io/docs/interacting.html#importing-javascript-code
|
This is great @danyx23, thanks a lot for this! 👏 👏 👏 I think your writing is very good, I just added a few minor comments. Please feel free to edit the text if you think they're helpful and then we merge the PR :) |
… it easier to understand the structure of the document
|
@alfonsogarciacaro thanks, that was all good feedback. I tried to incorporate it all. Thanks to your hints I now understood the props/dynamic import much better and decided to break this out into it's own section; so now I write that there are three distinct ways of using a third parts react component. I also added a table of contents because the document is already quite long now. Let me know if you think this is overkill and we should take it out again. Please let me know if there is anything else you would like to see changed, otherwise I'm looking forward to the merge :) |
| For example to use the [rc-progress React components](https://github.com/react-component/progress), run the following in your Fable project root: | ||
|
|
||
| ```bash | ||
| yarn install rc-progress |
|
Awesome, thanks again for this! |
This is a first stab at documenting how to use a third party react component. Please let me know what you think!