Merge pull request #54 from ethul/topic/dynamic-children

Topic/dynamic children

Author: ethul

.gitignore

@@ -1,3 +1,4 @@
 output
 bower_components
 node_modules
+.pulp-cache/

README.md

@@ -9,6 +9,14 @@ For a more high-level set of bindings, you might like to look at `purescript-the
 
 - [Module Documentation](docs/)
 
+## Dynamic children
+
+There are two ways that child elements can be passed to components:
+- The first way is to spread the child element array when passing them to React's `createElement` function. The [React.DOM](docs/React/DOM.md) and [React.DOM.SVG](docs/React/DOM/SVG.md) spread the child element array.
+- The second way is to pass the child element array to `createElement` without spreading. This is useful when dealing with [dynamic children](https://facebook.github.io/react/docs/multiple-components.html#dynamic-children). In this case a `key` property should be assigned direclty to each child. The [React.DOM.Dynamic](docs/React/DOM/Dynamic.md) and [React.DOM.SVG.Dynamic](docs/React/DOM/SVG/Dynamic.md) pass the child element array without spreading.
+
+Note that this module provides functions `createElement` and `createElementDynamic` to handle the two cases above for component classes.
+
 ## Building
 
 The library and example can be built with Pulp as follows:

bower.json

@@ -15,10 +15,10 @@
     "test",
     "tests"
   ],
-  "repository": {                                              
-    "type": "git",                                             
+  "repository": {
+    "type": "git",
     "url": "git://github.com/purescript-contrib/purescript-react.git"
-  },                                                        
+  },
   "dependencies": {
     "purescript-dom": "~0.2.6"
   },

docs/React.md

@@ -2,6 +2,14 @@
 
 This module defines foreign types and functions which wrap React's functionality.
 
+#### `TagName`
+
+``` purescript
+type TagName = String
+```
+
+Name of a tag.
+
 #### `ReactElement`
 
 ``` purescript
@@ -308,7 +316,31 @@ Create an event handler.
 createElement :: forall props. ReactClass props -> props -> Array ReactElement -> ReactElement
 ```
 
-Create an element from a React class.
+Create an element from a React class spreading the children array. Used when the children are known up front.
+
+#### `createElementDynamic`
+
+``` purescript
+createElementDynamic :: forall props. ReactClass props -> props -> Array ReactElement -> ReactElement
+```
+
+Create an element from a React class passing the children array. Used for a dynamic array of children.
+
+#### `createElementTagName`
+
+``` purescript
+createElementTagName :: forall props. TagName -> props -> Array ReactElement -> ReactElement
+```
+
+Create an element from a tag name spreading the children array. Used when the children are known up front.
+
+#### `createElementTagNameDynamic`
+
+``` purescript
+createElementTagNameDynamic :: forall props. TagName -> props -> Array ReactElement -> ReactElement
+```
+
+Create an element from a tag name passing the children array. Used for a dynamic array of children.
 
 #### `createFactory`
 

docs/React/DOM.md

@@ -1,9 +1,16 @@
 ## Module React.DOM
 
+#### `IsDynamic`
+
+``` purescript
+newtype IsDynamic
+  = IsDynamic Boolean
+```
+
 #### `mkDOM`
 
 ``` purescript
-mkDOM :: String -> Array Props -> Array ReactElement -> ReactElement
+mkDOM :: IsDynamic -> TagName -> Array Props -> Array ReactElement -> ReactElement
 ```
 
 #### `text`