Fix #284: Introduce a field template API.

[n1k0]

Refs #284, WiP. Early feedback appreciated :)

Field template

To take control over the inner organization of each field (each form row), you can define a field template for your form.

A field template is basically a React stateless component being passed field-related props so you can structure your form row as you like:

function CustomFieldTemplate(props) {
  const {id, classNames, label, help, required, description, errors, children} = props;
  return (
    <div className={classNames}>
      <label htmlFor={id}>{label}{required ? "*" : null}</label>
      {description}
      {children}
      {errors}
      {help}
    </div>
  );
}

render((
  <Form schema={schema}
        FieldTemplate={CustomFieldTemplate} />,
), document.getElementById("app"));

The following props are passed to a custom field template component:

• id: The id of the field in the hierarchy. You can use it to render a label targetting the wrapped widget;
• classNames: A string containing the base bootstrap CSS classes merged with any custom ones defined in your uiSchema;
• label: The computed label for this field, as a string;
• description: A component instance rendering the field description, if any defined (this will use any custom DescriptionField defined);
• children: The field or widget component instance for this field row;
• errors: A component instance listing any encountered errors for this field;
• help: A component instance rendering any ui:help uiSchema directive defined;
• hidden: A boolean value stating if the field should be hidden;
• required: A boolean value stating if the field is required;
• readonly: A boolean value stating if the field is read-only;
• displayLabel: A boolean value stating if the label should be rendered or not. This is useful for nested fields in arrays where you don't want to clutter the UI.

Note: you can only define a single field template for a form. If you need many, it's probably time to look for custom fields instead.

[n1k0]

I'd really appreciate feedback from @mplis-jetsetter @nuclearspike @Natim @magopian @amarnus @MoOx or basically anybody interested in this feature.

[MoOx]

lgtm. This is really a nice addition.

It would be nice to have "style" in addition to "classNames", but this comment probably apply for the entire project :D (Nice when you write CSS in JS - which is the future, you already know that /trollOrNotThatSTheQuestion ^^)

[n1k0]

tbh I precisely asked to gather this sort of feedback :) we can definitely add more props, I was wondering about passing the schema, uiSchema and friends, but I fear that would be opening the door to a lot of possible abuse ^^

[MoOx]

I was wondering about passing the schema, uiSchema and friends, but I fear that would be opening the door to a lot of possible abuse

With great powers blah blah blah. If that can offer flexibility, maybe that's a good idea?

[n1k0]

I don't know, I like the idea of having a template not dealing with any kind of business logic; I feel like people will see this as a way to implement logic in there while they should be doing this in custom field/widget comps.

Sure I could document this heavily with big warnings and so on but in my experience:

• people don't read them
• even if they read them, they'll keep doing the wrong thing
• and after that they'll file issues
• and that usually tends to burn me out

That may just be me being paranoid here though :p

[MoOx]

That may just be me being paranoid here though :p

No, you are concerned by the project you are shipping. Totally legit.

Just bikeshedding: if people want to add logic here, it's because the "U/DX" won't be good enough so they will use that because it's seems more simple for them. This might mean the "normal" way to do is less accessible or more complicated :)

[n1k0]

I can always land this limited at first and we can add more props in the future if anyone comes with good legit use cases for them.

[MoOx]

Definitely!

[n1k0]

Okay people, I'm landing this.

[n1k0]

Released in v0.39.0.

[n1k0]

I can always land this limited at first and we can add more props in the future if anyone comes with good legit use cases for them.

It didn't take long to identify a first good use case :p #196 (comment)

[nuclearspike]

Finally got a chance to take this for a spin, and definitely appreciate this. I use it to do automatic title prettification so I can leave out a lot of titles now. "first_name" => "First Name" or in some strange situations where I want no titles/labels (uses placeholders only), no indication that it's required but I still want the required behavior (popup, no posting until it's filled in).

Additionally (maybe best as a new ticket) it would be nice to be able to override the error field to handle that however I want. One thing I want to do is to just do a find and replace on the word "property" in the error messages. No user should ever see that (I realize that's the json validator library and not this component's code).

[matias-sandell]

Excellent work! Now I can remove the labeling from the field template and have Material-UI render the title/label.

Unfortunately, the field template only gets me half way since objects like this;

"watchType": {
    "type": "object",
    "properties": {
        "id": {
            "title": "Watch Type",
            "type": "number",
            "enum": [1, 2, 3],
            "enumNames": ["Apple", "Big Ben", "Cuckoo"]
        }
    }
},

...will be wrapped in a <fieldset> with the <legend> set to watchType, like this;

...so what I would need is either

1. A way to turn of the automatic labelling with something like autolabels: false which only uses the title from the json-schema if it's available without falling back to the property name
2. Access to a fieldset template, like @nuclearspike suggested in #284
3. Some very hard coded display: none CSS rules.

Or have I missed the perfect solution behind door number four?

[prevuelta]

Quick question, I'm guessing the ArrayFieldTemplate (or FieldTemplate) would need to be a full component to allow collapsing? eg. collapsed state & toggle method.. At the moment I can't pass in a component class or object, it has to be a stateless functional component.. or am I missing something?

[n1k0]

At the moment I can't pass in a component class or object, it has to be a stateless functional component

Why can't you pass a stateful component? What's the error?

[prevuelta]

If I pass a class I get TypeError: Cannot set property 'props' of undefined on this line

// Check if a custom render function was passed in
var renderFunction = ArrayFieldTemplate || DefaultNormalArrayFieldTemplate;
return renderFunction(arrayProps);

It's expecting a render function but gets the class constructor which has no this in that context

    function ArrayFieldTemplate(props) {
        ____Class0.call(this,props);
    }

[n1k0]

That's indeed an unfortunate limitation #519 is gonna fix.

Edit: released in v0.44.0.

[prevuelta]

Cheers :)

[EvertLagerberg]

I am trying to figuring out how to make a part of my schema collapsed from the start as to improve UX on a large form. According to #598, this merge was merged for my use case. However, I cannot figure out how I am supposed to use the field template API to make a part of the form collapsible. Can anyone point me in the right direction?

[janpauldahlke]

Will use this to bump. Or can someone be so kind to point me to an example, where only specific parts of the formschema are collapsible?

[MatinF]

Hi again,

I've tried to achieve the removal of the "*" for required fields using the Field Template, but I'm finding it to be rather difficult to achieve without breaking something else.

As an example, I'm currently also using an ArrayFieldTemplate similar to the expanded example in the docs. But when I use a FieldTemplate in conjunction, it seems like my ArrayFieldTemplate gets overruled.

What I would like is really simple: Not having the "*" next to any required fields. It seems like a very clean addition to the source code and something many would like. I realize that it's possible to achieve via custom fields, but for more complex forms, this quickly gets very difficult to manage.

Any thoughts on potentially making this possible?