polymer-rails-forms 0.3.0 → 0.3.01

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e84e48d69438d5b8a537430e33e8b76c577737fc
-  data.tar.gz: 61425af1e14df5ea2127d01a7fd6ef932a2142a3
+  metadata.gz: b75d3c9c3f3557fccb6938dc90e4f72d16c002fc
+  data.tar.gz: fba524123deb455a9ac60055f40d6748aa765386
 SHA512:
-  metadata.gz: 5a9ed0c220c28ca4b7d747ed938b6a809c0caf384cd553dda015cd70a7207bdb82e35ed0959e35ba0cb180448ac23f32e2239be324e0028ab2481401836cc9b5
-  data.tar.gz: 14f3780952bfa622d3e7ddb68fa30303464551c04ffb8f13063898f6eb623bf59450741569fafbf8b508acc6c331c565a16919abd78ae2f32e983a631a0fc767
+  metadata.gz: 73251ebfb263ad43a526105e1e04fe5e1d9b25e487028e83c97823bdef785e879feb65d0860b0c6e6149f10f23b002b1565fac0d5e74375099c9a956018421bc
+  data.tar.gz: 44289cfe4ca79e7193d0fcb7e8d4980bb5f910f5197f7814fb5174480e13dcf16d19839c67c2a238de60b8cfe66b79eb1f4347c5bb70d84d54488adf724ea53d

data/README.md

@@ -24,6 +24,27 @@ then in your /app/assets/components/application.html file add
 	*= require rails-forms/rails-form
 ```
 
+##BREAKING CHANGE IN 0.3.0
+Because objects are unordered and order is generally important in forms I've updated 
+the form structures to be arrays. So rather than 
+
+```javascript
+  this.structure = {
+    myKey: {type: "string"}
+  }
+``` 
+
+your structure should look like
+
+```javascript
+  this.structure = [
+    { key: myKey, type: "string" }
+  ]
+```
+Additionally since you can no longer just do something like ```this.stucture.myKey``` to get a 
+structure's fields I've added a get field function ```this.getField("myKey")``` for nested fields
+you would just do ```this.getField("myNest.myKey")```
+
 ##Basic example
 
 This is what a simple login form could look like using this gem
@@ -31,10 +52,10 @@ This is what a simple login form could look like using this gem
 ```html
 <rails-form id='sign_in_form' action="/users/sign_in" method="POST" scope="user" submitText="Sign In"></rails-form>
 <script>
-	document.getElementById("sign_in_form").setAttribute("structure", JSON.stringify({
-		email: { type: 'string', label: "Email Address" },
-    	password: { type: 'password' }
-    }))
+	document.getElementById("sign_in_form").setAttribute("structure", JSON.stringify([
+		  { key: "email", type: 'string', label: "Email Address" },
+    	{ key: "password", type: 'password' }
+    ]))
 </script>
 ```
 
@@ -55,11 +76,11 @@ polymer element that extends rails-form. Here's the same login form
       submitText: "Sign In",
 
       ready: function(){
-        this.structure = {
-          email: { type: 'string', label: "Email Address" },
-          password: { type: 'password' },
+        this.structure = [
+          { key: "email", type: 'string', label: "Email Address" },
+          { key: "password", type: 'password' },
         }               
-      }
+      ]
     });
   </script>
 </polymer-element>
@@ -84,17 +105,16 @@ again, but this time with nested location attributes
       submitText: "Sign In",
 
       ready: function(){
-        this.structure = {
-	      email: { type: 'string', label: "Email Address", required: true },
-	      password: { type: 'password', required: true },
-	      location: { type: 'nest', allowAdd: false, multiple: false, structure: {
-	          address: { type: "string" },
-    		  city: { type: "string" },
-    		  state: { type: "string" },
-    		  zip: { type: "string" }
-	      	}
-	      }
-        }               
+        this.structure = [
+          { key: "email", type: 'string', label: "Email Address", required: true },
+          { key: "password", type: 'password', required: true },
+          { key: "location", type: 'nest', allowAdd: false, multiple: false, structure: [
+            { key: "address", type: "string" },
+            { key: "city", type: "string" },
+            { key: "state", type: "string" },
+            { key: "zip", type: "string" }
+          ]}
+        ]            
       }
     });
   </script>
@@ -106,28 +126,95 @@ to set ```multiple: true``` the name would become ```user[location_attributes][0
 you were to set ```allowAdd: true``` the inputs would be in a list with the option to create more. 
 
 
-###Validations
+##GROUPS AND STEPS
+
+Sometimes you want to style a group of elements in a form and polymer selectors can get somewhat 
+unwieldy without having a list of them so polymer-rails-forms now includes groups. Groups are similar to 
+nests but don't change the scope for inputs, they're purely for styling. If, for instance, ```location```
+in the previous example were not a nested attribute, but just a group of fields you wanted to add some special
+styling to you could write it like
+
+```javascript
+  this.structure = [
+    { key: "email", type: 'string', label: "Email Address", required: true },
+    { key: "password", type: 'password', required: true },
+    { key: "location", type: 'group', structure: [
+      { key: "address", type: "string" },
+      { key: "city", type: "string" },
+      { key: "state", type: "string" },
+      { key: "zip", type: "string" }
+    ]}
+  ]
+```
+
+which would keep all the address fields in the default scope but wrap them in a div with the class 'location'.
+
+Additionally, if you wanted to make the form a multi-step form, with the user entering in the email, password 
+on the first step and the location information in the second simply group fields by step like so:
+
+```javascript
+  this.structure = [
+    { key: "header": type: "html", content: "<h4>This will stay visible because it's outside of the steps</h4>" },
+    { key: "step_1", type: "step", structure: [
+      { key: "email", type: 'string', label: "Email Address", required: true },
+      { key: "password", type: 'password', required: true },
+      { key: "location", type: 'group', structure: [
+    ]},
+    { key: "step_2", type: "step", structure: [
+      { key: "address", type: "string" },
+      { key: "city", type: "string" },
+      { key: "state", type: "string" },
+      { key: "zip", type: "string" }
+    ]}
+  ]
+```
+
+##Validations
 
 Also not that I've included ```required: true``` on the email and password fields. This means this triggers
 them to be validated onSubmit and onChange. For a custome validation just use ```validates: 'method_name'```
 
 ####Note:
 
-If you're going to use the domReady function in your custom form element, be sure to call
+If you're going to use the domReady or created function in your custom form element, be sure to call
 ```this.super()``` at the top of the function to run the form's default domReady functionality 
 (which includes appending all the inputs so... kind of important). If you don't want the default 
 functionality though, just make sure you run the ```this.appendInputs()``` so the inputs get added. 
 
-###XHR
+##XHR
 
 To make the form ajaxy just include the form element's ```xhr='true'``` param 
 and override the ```handleXhrCallback``` function. 
 
+##Notes about certain field types
+
+###Arbitrary HTML
+
+Sometimes you want to just put a bit of explanation or whatever else in the middle of a form. To
+do this just create a field with the type 'html' and give is a 'content' attribute. The content attribute is 
+just a string of HTML that will be injected inbetween whatever inputs you put it between. 
 
 ###Selects
 
-selects are the same as any other input except that they also require the values property which is and array of 
-arrays, so ```[[value1, text2], [value2, text2]]```
+Selects are the same as any other input except that they also require the values property which is and array of 
+arrays, so ```[[value1, text2], [value2, text2]]```. If ```multi``` is set to true then it'll be a multi select 
+with those slick paper-checkboxes
+
+###JSON fields
+Since Postgres now has those awesome HStore and JSON fields you can take for advantage of them by using a json field 
+
+```javascript
+{ key: "awesome_json", type: "json", multiple: false, structure: [
+  { key: "first_field", type: "string"},
+  { key: "nests_work_to", type: "nest", multiple: true, allowAdd: false, structure: [
+    { key: "cool_right", type: "string" }
+  ]}
+]} 
+```
+This will create multiple inputs that all automatically serialize to a single field in the form's data called 
+'awesome_json' whenever any of them are changed. If anyone out there wants to try this out with some other noSQL 
+DB's that'd be awesome.
+
 
 ##What's supported what's not
 
@@ -140,11 +227,14 @@ arrays, so ```[[value1, text2], [value2, text2]]```
 * email
 * url
 * integer
+* select (single / multi)
 * date (uses pickaday.js)
 * location (uses google places API, which you'll have to include separately)
-* image (works, but CSS is messed up)
+* file 
+* image 
 * checkbox
-* json (limted, only basic objects are supported so far, not nested arrays and objects)
+* json 
+* arbitrary HTML
 
 ###What's not supported 
 
@@ -152,6 +242,6 @@ arrays, so ```[[value1, text2], [value2, text2]]```
 * ranges
 * everything else
 
-Support for radio buttons, ranges (sliders), and selects will hopefully be coming shortly. 
-Everything else, who knows. This is still a very early release. 
+Support for radio buttons, ranges (sliders) will be coming when someone requests them or I
+need them for something.  
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: polymer-rails-forms
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.01
 platform: ruby
 authors:
 - Joel Weber