Extend Collection+JSON template with options. #6

kivi · 2012-08-21T12:34:38Z

As talked about in here https://groups.google.com/d/msg/collectionjson/PQK5PoB7eSI/Tq2LZ_wr-_cJ

pull request by
User:mrdevinmob
User:kivi

typo

…ns: (array of prompt/value pair) and multiple: (boolan)

kivi · 2012-08-21T16:11:10Z

if multiple values are selected, I would say value should be an array, so processing would be strict JSON otherwise you would have to split elements by ', '

{"name" : "country", "value" : ["Germany", "Poland"], ...}

kivi · 2012-08-21T16:17:41Z

I think "text" instead of prompt is ok, but "text" would need further description, whereas "prompt" within "options" is described by it's analogy to the "prompt" in data item.

mamund · 2012-08-21T19:37:57Z

Currently, value is defined as a string, not an array. changing this can break existing implementations. if you want to return something other than a string, you need to use a different property. @hamnis solves this problem by creating the value-types extension.

Also, why should the client return the entire hash ({prompt,value}? Isn't the value good enough? other data elements do not return the prompt.

mamund · 2012-08-21T19:39:14Z

[snip]
"text" would need further description,
[/snip]

Not sure what this means "further description" you mean that it adds a new property to CJ? or something else?

mrdevinmob · 2012-08-22T08:55:29Z

value-extension.json

The value extension seems to be a great way to handle multiple value in either an objet or an array. If that is indeed the solution from @hamnis

I alos find "text" to be a better option as "prompt" or just returning "value". I could imagine a case where the value is
nondescript and you still need a descriptor or some type.

"template" : {
    "data" : [
        { 
            "name" : "customer", 
            "value" : "", 
            "prompt" : "Customer", 
            "multiple" : "false",  
            "options" : [ 
                {
                    "text" : "Jane", 
                    "value" : "0z1a6" //value could be a customer id
                }, 
                { 
                    "text" : "Joe", 
                    "value" : "0b2c2" 
                } 
            ]
        }
    ]
}

would the "text" field need to be described in the documentation somewhere? Or would it be self explanatory?

updating to reflect conclusions drawn in this [pull request](mamund#6)

mamund · 2012-08-22T14:17:18Z

@mrdevinmob

yes, the text property would need to be documented for this extension. similar to the way options and multiple are in this extension already.

Update extensions/template-options.md

added a reference to value types and documentation for "text" and "value"

had single quotes where I should have double quotes

adding post and put examples

Update extensions/template-options.md add reference to value-types, showing POST/PUT request the actual state that is transferred from client to server (via POST or PUT) the resulting "item" that is returned from server to client

kivi · 2012-09-19T19:07:31Z

Hi @mamund

just changed the structure or sequence of text blocs and published on gist.
First we have the description of the optional properties and then template, the body which is sent and the resulting item.

No objections to text and value as @mrdevinmob mentioned in the group discussion.
Is the example detailed enough?

sorry for inconvenience, hope I understood everything fits now. I just followed the structure of the other extensions.

mamund · 2012-09-19T19:14:55Z

thanks for the follow up and posting the gist.

it looks pretty clear. style-wise, the content is just fine.

anyone else want to weigh in here?

is it OK w/ all that the {item} that is returned only shows the "text" and
not the "value" (i.e. shows "Germany" and not "de" [or both])?

just making sure to cover all bases here. adding anything beyond simple
types is tricky; lots of angles.

On Wed, Sep 19, 2012 at 3:07 PM, kivi [email protected] wrote:

Hi @mamund https://github.com/mamund

just changed the structure or sequence of text blocs and published on gisthttps://gist.github.com/3415015
.
First we have the description of the optional properties and then
template, the body which is sent and the resulting item.

No objections to text and value as @mrdevinmobhttps://github.com/mrdevinmobmentioned in the group discussion.
Is the example detailed enough?

sorry for inconvenience, hope I understood everything fits now. I just
followed the structure of the other extensions.

—
Reply to this email directly or view it on GitHubhttps://github.com//pull/6#issuecomment-8702680.

kivi · 2012-09-22T20:43:16Z

is it OK w/ all that the {item} that is returned only shows the "text" and not the "value" (i.e. shows "Germany" and not "de" [or both])?

I would leave that optional. If respond contains the value "de" which was for the text "German", then it should also included in any response for that item/href.

Example how a response could look like with value (countryCode). However a client also could refer to valueof text in it's template data object and there for I would l rather leave it out.

    "items" : [
      {
        "href" : "http://example.org/users/1",
        "data" : [
          {"name" : "username", "value" : "JDoe", "prompt" : "User name"},
          {"name" : "country", "value" : "Germany", "prompt" : "Country"},
          {"name" : "countryCode", "value" : "de", "prompt" : "Country"},
          {"name" : "talents", "array" : ["socializing", "climbing"], "prompt" : "Talents"}
        ]
      }
    ]

just making sure to cover all bases here. adding anything beyond simple types is tricky; lots of angles.

I thought to suggest a definition for òbject as value-types. The only thing, what makes sense to me could look like the following example. But I won't include that in the current suggestion, since I don't have a real world example/use case.

Template:

"template" : {
  "data" : [ 
    { "name" : "contact", "value" : "", "prompt" : "Contact", "required" : "true", "object" : {} }
  ]
}

POST/PUT
{ "contact" : { "github": "kivi", "twitter" : "chatmasala" }  }

RESPONSE
...
{"name" : "contact", "object" : { "github": "kivi", "twitter" : "chatmasala" }, "prompt" : "Contact"}      
...

@mrdevinmob

1. the template:{} (which you have above) 1. the actual body that will be sent via POST/PUT 1. the resulting item:{} 1. text and value as @mrdevinmob and @mamund mentioned in the group discussion

jstephenson · 2013-07-26T09:28:00Z

This appears to have gone cold, but none the less a related point: a similar construct for 'queries' would be a good idea, no? Ofc HTML as a media type can use <select> in query forms, and it seems sensible to have such a capability here?

mamund · 2013-07-26T21:00:28Z

yes, if we can come up w/ a stable extension for the data element that
mimics the "select" control for HTML, it could be applied to the data
element in all locations (item, query, template).

On Fri, Jul 26, 2013 at 5:28 AM, James Stephenson
[email protected]:

This appears to have gone cold, but none the less a related point: a
similar construct for 'queries' would be a good idea, no? Ofc HTML as a
media type can use in query forms, and it seems sensible to have such a
capability here?

—
Reply to this email directly or view it on GitHubhttps://github.com//pull/6#issuecomment-21610457
.

This is not canon but we need it to move forward. Yes, this means you could do collection.items[n].data[y].options. Don't do that. hat tip: http://schinckel.net/2012/03/10/collection%2Bjson-primer-%28and-comments%29/ reference: mamund/collection-json#6

kivi added 3 commits August 21, 2012 14:01

Update extensions/template-validation.md

e2af624

typo

New extension: template options. Proposing optional properties: optio…

d87c8ed

…ns: (array of prompt/value pair) and multiple: (boolan)

Merge branch 'master' of github.com:kivi/collection-json

7c53be0

ghost assigned mamund Aug 21, 2012

Update extensions/template-options.md

be350d3

updating to reflect conclusions drawn in this [pull request](mamund#6)

kivi and others added 6 commits August 22, 2012 07:23

Merge pull request #3 from mrdevinmob/patch-3

adad47f

Update extensions/template-options.md

Update extensions/template-options.md

98314ca

added a reference to value types and documentation for "text" and "value"

Update extensions/template-options.md

f147556

had single quotes where I should have double quotes

Update extensions/template-options.md

f2de8cf

adding post and put examples

Merge pull request #4 from mrdevinmob/patch-3

15b3911

Update extensions/template-options.md add reference to value-types, showing POST/PUT request the actual state that is transferred from client to server (via POST or PUT) the resulting "item" that is returned from server to client

comma remove for valid json Update template-options.md

c99e74f

restructure and include: template, request and response

99cf86b

1. the template:{} (which you have above) 1. the actual body that will be sent via POST/PUT 1. the resulting item:{} 1. text and value as @mrdevinmob and @mamund mentioned in the group discussion

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Extend Collection+JSON template with options. #6

Extend Collection+JSON template with options. #6

kivi commented Aug 21, 2012

kivi commented Aug 21, 2012

kivi commented Aug 21, 2012

mamund commented Aug 21, 2012

mamund commented Aug 21, 2012

mrdevinmob commented Aug 22, 2012

mamund commented Aug 22, 2012

kivi commented Sep 19, 2012

mamund commented Sep 19, 2012

kivi commented Sep 22, 2012

jstephenson commented Jul 26, 2013

mamund commented Jul 26, 2013

Extend Collection+JSON template with options. #6

Are you sure you want to change the base?

Extend Collection+JSON template with options. #6

Conversation

kivi commented Aug 21, 2012

kivi commented Aug 21, 2012

kivi commented Aug 21, 2012

mamund commented Aug 21, 2012

mamund commented Aug 21, 2012

mrdevinmob commented Aug 22, 2012

mamund commented Aug 22, 2012

kivi commented Sep 19, 2012

mamund commented Sep 19, 2012

kivi commented Sep 22, 2012

jstephenson commented Jul 26, 2013

mamund commented Jul 26, 2013