Docs on how to use with React

[flesler]

Hi,

The project looks interesting. I think it'd add up if you add an example of how would one use this within React, whether it can be enough to implement the Flux architecture or what else would be needed.

I imagine this in the README and/or an examples folder.

[arqex]

Hi @flesler

Thanks for your interest, there is a JSON editor example where you can see it working:

http://jsbin.com/hugusi/1/edit?js,output

And here the article that talks about how it:

http://arqex.com/991/json-editor-react-immutable-data

Probably I should add it to the readme file.

[flesler]

I think both are too technical and complex. I'm thinking more a code snippet that shows Freezer in action in the simplest case.

[arqex]

Immutable data shines in complex examples, but you are right I need to add some example that people can understand at first sight. I will think about it. If you have some example in mind just tell me.

Thanks for your feedback.

[hampsterx]

just wanted to say thanks! this library is insanely great for React, I am surprised it hasn't caught on like wildfire yet, I first tried Baobab but like you didn't like the idea of tying cursors to components, this library really helps with thinking in the "reactive" way with React. cheers~

[arqex]

Hey @hampsterx

Thanks for your kind words, I am glad you liked freezer. Certainly I believe it is a great project that makes working with react really easy, I would love that it was used by many more developers.

But it is difficult to promote freezer, immutable.js is backed by facebook and it is everywhere, and freezer is only used by developers that likes to investigate.

I have thought that if I could make a product that everybody can use ( not only geeks who like immutable structures like us :smile: ) that works with freezer, maybe it can be known by more developers this way. So I have started to work in a customizable form creator that uses freezer:

https://github.com/arqex/react-json

The idea is getting rid of all the code boilerplate needed to create and handle inputs in react, and create them in a declarative way using json.

It would be possible to create customized field types, so other outstanding form components like http://jedwatson.github.io/react-select/ can be used inside react-json.

I hope you like it too :)

[hampsterx]

re: customizable form creator

Not sure whether you intend this to be used for form builders (ie end users) or for developers as a scaffold for server generated json api/form specification. We are pondering the later case.

In both cases it gets challenging thinking about nested formsets, layout, etc, one earlier attempt at json form builder is https://github.com/jdorn/json-editor, you only need to look at the issue count (~150) to see how the complexity can spiral, however I think delegating the data to widgets avoids at least having to handle low level widget issues but the more it gets used the more people are going to want a consistent interface otherwise it will become spaghetti mess of options to create a form.

Few notes below from a recent poke at the subject, probably not helpful but might give you some ideas, no idea..

• api doc generators
  • apiary, raml, swagger, api blueprint, etc *1
  • some are yaml based, some markdown, most cater firstly for manually created docs via builder tools * 2
• form builders
  • mostly based around JSON Schema * 3

There appears to be some cross over with JSON Schema support in these api doc generators *4

---

*1

Ask HN: What's the best way to write an API spec? https://news.ycombinator.com/item?id=8912897

There have been an explosion of API specification formats in the last few years. No clear winner has emerged.

JSON Schema and JSON Hyperschema are JSON-based formats for describing JSON and REST (hypermedia-driven) APIs. The formats make decent sense and can be used to generate docs, validators, client libraries, UIs, and more.http://json-schema.org/

API Blueprint is another emerging format for API description. It's written in Markdown, so it is very human-readable and -writable. It is not yet suitable for hypermedia APIs. Like JSON Schema, its tooling includes validators, client library generators, mock server generators, docs generators, etc. http://apiblueprint.org/

Swagger is a YAML-based format for specifying JSON APIs. It is meant to be created using the Swagger UI, rather than handwritten. It generates pretty docs, client software, etc. but is not suited to describing hypermedia APIs. http://swagger.io

Slate is an API documentation framework/template, designed to generate very handsome documentation pages. Its concern is more documentation than specification, and therefore doesn't concern itself with things like library or mock generation.https://github.com/tripit/slate

WADL is an API description language which describes API interactions in an XML format. It resembles WSDL. Not many people use it. http://en.wikipedia.org/wiki/Web_Application_Description_Lan...

Which of these is the best? Good question. I like JSON Hyperschema, but I am writing hypermedia APIs and the other formats here are lacking in their hypermedia support. API Blueprint is a nice format to write in a text editor and is easily read as-is or rendered from Markdown; no separate docs generator is necessary.

• 2

http://apievangelist.com/2014/11/21/there-are-four-api-design-editors-to-choose-from-now/

Apiary.io - Collaborative design, instant API mock, generated documentation, integrated code samples, debugging and automated testing using the API Blueprint API definition format. API Designer - Enables the ability to design APIs in the RAML API definition format, and mock, preview and save API designs into a notebook Swagger Editor - Allows the designing APIs in the Swagger format in both YAML and JSON, allowing you to import, edit, preview, and export API design docs. Restlet Studio - Allows you to create, and load API designs in Swagger and RAML formats, save, and generate server side scaffolding, and client side SDKs in multiple languages.

• 3

http://programmers.stackexchange.com/questions/267309/does-a-form-describing-json-standard-exist

I think the standard you are looking for is JSON Schema. It's not specific to forms, it's a more general specification for defining what a particular JSON format looks like (like an XML schema). There are a few solutions for creating forms with JSON Schema, like joshfire/jsonform.

https://github.com/Textalk/angular-schema-form

Generate forms from JSON schemas using AngularJS. Schema Form is inspired by the nice JSON Form library and aims to be roughly compatible with it, especially its form definition.

http://appliedmathematicsanu.github.io/plexus-form/

A dynamic form component for React using a specification format based on JSON-Schema.

• 4

http://support.apiary.io/knowledgebase/articles/147279-json-schema-validation

In API Blueprint you can associate a JSON Schema (http://json-schema.org) with any JSON-represented resource. If a JSON Schema is specified, every Content-Type: application/json request to an endpoint is validated against it. Validation results can be found under the "Inspector" tab or in endpoint documentation's debugger.

https://github.com/apiaryio/Amanda

Amanda is aiming to be a universal schema validation library. Currently it supports only the JSON Schema Internet Draft

[arqex]

Hi @hampsterx

I suppose you want to help me with react-json, and that's why you sent me all that info :)

Thanks. From my point of view, all the libraries that are using JSON schema for form definitions are not in the right way. JSON schema is too verbose, you need to write a lot to define your forms, and lacks of some properties to make form creation easy. Lib authors add those missing properties to the schema but, is it a proper JSON schema anymore?

JSON schema was never thought to build forms, so I prefered to define them using a handcrafted form definition, inspired in some way by JSON schema. I think it won't scare developers because it is concise, and it is easy to understand because it talks form language ( fields instead of properties, labels instead of titles... ).

Apart from the ease of use, I think the key part of creating a nice form builder is that it needs to be completely customizable. If somebody has created a awesome file upload library, or a beautiful color picker, why I wouldn't use them inside my form builder? The idea behind react-json is having completely independent form fields that can communicate changes to react-json, so people can create new form fields or use whatever component they would like inside the form.

It is still work in progress, I was looking for a datetime picker to handle Date objects but I couldn't find a nice one, I need to improve CSS customization, lock up the API, add tests, improve validation, add docs... But I think it won't take long to release a beta :)

Anyways, it alredy works nicely https://github.com/arqex/react-json

[hampsterx]

yeah, fair point. I guess my perspective is more from being able to generate a form definition from the server side which would require a defined set of widgets and consistent structure for form errors, etc, the client can then render the default form or use the definition as a starting point for a partially or completely custom form (ie using the structure merely for reference).

As you say, a work in progress but functional at present, a couple of moderately complex form examples (rather than 2 fields at present) would probably go a long way :)

Regarding the origin of this issue:

.. add an example of how would one use this within React, whether it can be enough to implement the Flux architecture or what else would be needed... I think both are too technical and complex. I'm thinking more a code snippet that shows Freezer in action in the simplest case.

I think your blog post is fantastic at explaining how to use freezer with React. However, the big question that remains is how it plays with Flux which is a larger issue than just freezer.js as IMHO many React developers (myself included) are confused on how immutable libraries fit with Flux, eg

• state. Even without immutable library the idea of using state is confusing, should you keep it in the view component, or move to store, should it be in a sub store or a completely different store
• store. How to handle multiple instances of same component, singleton passing in id of instance or one store per instance
• immutable data. Should private component state live in the data structure. If an immutable structure can be updated by a view which triggers a top down cascade then does it make sense to have the view update itself if it's only handling internal state. In this case should a child component first call the parent (via say flux-reactions) so it's updating the node a bit higher up.

Some articles of interest:

http://blog.risingstack.com/the-react-js-way-flux-architecture-with-immutable-js/

http://www.thomasboyt.com/2014/09/15/no-fit-state.html

https://groups.google.com/forum/m/#!topic/reactjs/olCk8zdmb5c

http://blog.elsdoerfer.name/2014/12/25/react-js-flux-om-i-am-trying-to-think-it-through/

https://medium.com/@dan_abramov/the-evolution-of-flux-frameworks-6c16ad26bb31

http://omniscientjs.github.io//guides/01-simpler-ui-reasoning-with-unidirectional/

http://blog.siftscience.com/blog/2015/best-practices-for-building-large-react-applications

[hampsterx]

Me again, more pondering..

I am basically at the point where I have build 2x pieces of isolated functionality on an existing project with React (using freezer.js, no flux, nor dispatcher, view updates data directly). Shortly I will need to make a choice on how the M/C parts (er "flux" aka unidirectional data flow pattern) works before we begin a Single Page App redesign.

In Om/Clojure land the benefits of a global atom containing all the local state is promoted as an effective way to snapshot and debug an app. Eg

• Simpler UI Reasoning with Unidirectional Dataflow and Immutable Data
• local state global concerns
• better flux dom events

So..

• single data structure
• stateless components (UI state in global data structure)
• top down rendering (props all the way down)

vs the spectrum of flux implementations that range from

• UI state in components, app state in stores, to UI state also in stores
• views updated from stores
• tight coupling (as you say) with the flux framework you choose

I think the confusing bit is the flux frameworks that are using an immutable library for store data (mostly for the benefit of using PureRenderer). Eg Fluxy, NuclearJS for example. I think this is where I ended up going around in a circle with my prior comment :(

Another example is this ticket on flux, flux with immutable data #134

Depending on your needs, you may or may not need flux if you are using global immutable state and passing things via cursors. You might still want to use flux or events so that the global app state is mutated in the proper way before the cursor triggers a render, but you might not need as many listeners on the render side (just passing cursors to props and use efficient shouldComponentUpdate).

So yeah I guess that is my question. A reactive approach handles the rendering strategy but it still leaves some questions about dispatching and managing the global state.

• dispatch. Should everything run through a dispatch or only those things that may have dependencies (eg the equivalent of store waitFor)?
• should you still use singleton store like objects for the M part? Eg fetching data from remote sources

I really haven't seen any flux, pure dispatcher or otherwise library that is really designed for the global state immutable data pattern you and others are advocating. I am weary of paving my own way here as I am still heavily learning this stuff.

Cheers~

[arqex]

Hey @hampsterx

It is true that is difficult to choose the right tools when there are so many! Well, I have been busy these days and that's why I couldn't reply to your previous message.

What I think it is important from flux is the concept of unidirectional data flow, everything else is really subjective. Using dispatchers, action creators, reducers... it is a matter of a personal taste, so you can choose the implementation that you like the most.

The stores in flux for example, they are meant to update and access to the state of a specific domain, but that does not make them own the data. I mean, the data doesn't need to be in the store, you can use any other library to keep it. That way you can have stores (helpers to get and update the current state) and use immutable structures ( to have the data ).

It is what @gaearon try to explain in https://medium.com/@dan_abramov/the-evolution-of-flux-frameworks-6c16ad26bb31, and the stores not owning the data is one of the strong points of his flux library https://github.com/gaearon/redux IMHO.

That way you can have your data in a single data structure, and the stores can work with its part of the structure. Communication among stores is far more easy this way than using waitFor.

[arqex]

Finally I had time to create a sample of the TodoMVC app that work just with React and Freezer. No frameworks leads to a very clean code:

Todo MVC using Freezer. Code & Demo.

And an article explaining it: How to use React and Freezer together.

Cheers, Javi