a more simple syntax definition

[cocodrino]

Hi andrew, It's not a criticism but I've found a bit complex understand how define my schemas, basically I feel than there are some incidental complexity in the way how build this (again it's not a criticism and I wish know your point of vie)

1) after read the doc I understand than you choose use a kind of pointers avoiding nesting compositions, so instead of a form panel with multiples question panels and more nested questionSets you chose separe this in 3 main schema properties and that every components refers with a pointer id to this components, this is pretty nice but I think than this

"formPanels" : [{
        "index" : 1,
        "panelId" : "intro-panel"
    }, {
        "index" : 2,
        "panelId" : "register-panel"
    }, {
        "index" : 3,
        "panelId" : "final-panel"
    }]

can be reduced to

"formPanels" : [ "intro-panel", "register-panel","final-panel"]

I feel than it's not only more readable but than also give the feels about I'm indicating which panels has my component instead of defining panels, in the original way I feel like if I've define my panels in two different places

2)

"action" : {
            "conditions" : [{
                "questionId" : "existing-user",
                "value" : "no",
                "action" : "GOTO",
                "target" : "register-panel"
            }],
            "default" : {
                "action" : "GOTO",
                "target" : "final-panel"
            }
        },
        "button" : {
            "text" : "Next"
        },

for me it's not clear the relationship between default and button, my understand after read the doc is than button call the default action, but in the def seems like if they're not related

maybe something like this could be better

"action" : {
            "conditions" : [{
                "questionId" : "existing-user",
                "value" : "no",
                "action" : "GOTO",
                "target" : "register-panel"
            }],
            "default" : {
                "button" : "Next",
                "action" : "GOTO",
                "target" : "final-panel"
            }
        },

Hope you feel than this can be an improve, I really like many ideas behind this lib and I found I nice way of build forms, thanks

[iamthemovie]

Hello there!

Thanks for your feedback on this, I understand where you're coming from with some of these questions so allow me to add a little context to the schema in order to provide some clarity.

Form Panels

The form panel array itself providers those pointers as you mentioned yes, by having an object rather than a single reference of text will allow us to expand in future. A single string with reference to ID's while seemingly it feels more straight forward presents a few issues in my mind:

• The indexes which provide the panel ordering, in the version currently, allows for explicit declaration. I understand implicitly using the array indices could have been an option (and this was considered) but my personal feeling with this being a schema, the more implicit the easier it easier to understand the form design especially.
• Using objects allows more room for expanding and evolving panel properties without convoluting the actual question sets with arbitrary properties in the future. We can separate the specific properties from the actual question data. Take the following loose example:

"formPanels": [ {
        "index" : 1,
        "panelId" : "intro-panel",
        "animation": "some-animation-directive",
        "conditions": {
           // Only display if the user has registered
        }
    }]

As you can see, objects allow us to extend beyond what we have so far by giving us, at the very least, the ability to add properties.

Its also worth noting that the entire design of this schema is made to feel like you could write strongly typed classes mirroring the schema very easily.

Default, Conditions and the all important Button

Again, a fair point but a few things that stand out with the following that might make it difficult to work with in the future:

• A Panel is like a window, it can contain multiple question sets but ultimately it needs to do something (like submit or goto the next panel) and by having a button object we provider separation between what the button does and what the button looks like. We want to keep sections of the schema clear and concise in these nested sections. The button itself is an object with Text, a CSS class maybe and other properties while the action is defined and determined in it's own block. We could put button overrides within the conditions which leads me on to my next point...
• The Default action is only one action of many possible actions and if we hit a conditional statement then we would no longer be using the default block to form the basis of the button's properties. I think in this case though it might be nice to be able to change the button text in the future based on conditions, potentially an issue for another day? :smile:

I hope this gives you a better idea of where the thoughts and structure came from when designing this schema.

By no means is it definitive though and I no body's perfect so if you've got a better way of doing that could work just as well we'd love to see it!

Thanks for you feedback. :smiley:

[jwbrady]

If "index" is suppose to mean the order of the objects, then it might be better to use "order" instead. That would clear up the confusion about "index".

[iamthemovie]

Fair point! I think we had other idea's for the index property when we were discussing what we wanted to do with this in the future. (I think it like a little timeline of where you were in the form was something we wanted for our specific solution).

[zanedev]

I wonder what @iamthemovie thoughts are on the schema approach used with this project (jsonschema + seperate uischema). So far I have found it a bit too restrictive on data types in form fields making it a bit of a painful Developer Experience.

https://github.com/mozilla-services/react-jsonschema-form

[iamthemovie]

@zanedev Do you mean the schema here is too restrictive or the react-jsonschema-form is?

The schema in Winterfell was designed to suite the need of designing forms in a fairly concise manner for the problem we were solving originally. My take on the react-jsonschema-form is that, while it looks like it's abstracting out key concepts (Schema, UI, Data) and providing a dedicated type annotation system it's inherently less lightweight and more cumbersome split out.

I like the overall idea but it reminds of when I was 14 with Zend_Form's and CakePHP's form helper when I was a PHP engineer.

I think the use of a standard schema in here would be good though, potentially something pluggable?