Skip to content

Latest commit

 

History

History
347 lines (261 loc) · 7.87 KB

documentation.md

File metadata and controls

347 lines (261 loc) · 7.87 KB

Structure

<pwc-dynamic-form>
  <pwc-dynamic-form-content> </pwc-dynamic-form-content>
  <pwc-dynamic-form-buttons> </pwc-dynamic-form-buttons>
</pwc-dynamic-form>

pwc-dynamic-form

Render structure

<form>
  <slot />
</form>

formChanged Event

formChanged: EventEmitter<PwcDynamicForm.FormChangedEventPayload>

Emitted when there is a change in the form.

A change can be a field change or a form reset.

Payload

type: "change" | "reset";
fieldChangedEventPayload: FieldChangedEventPayload;
formResetEvent: Event;
formValues: { [key: string]: boolean | string | string[] };
formElement: HTMLPwcDynamicFormElement;
  • type: type of the change. change if the event is raised due to a field change. reset if the event is raised due to a form reset.
  • fieldChangedEventPayload: (valid if type is change) payload of the fieldChangedEvent that caused this event to be raised.
  • formResetEvent: (valid if type is reset) the reset event that caused this event to be raised.
  • formValues: current form values (not the values before the event, but the new ones).
  • formElement: the <pwc-dynamic-form> element.

getFieldValues Method

async getFieldValues(returnOnlyValuesForPwcSelects: boolean = false): Promise<{ [key: string]: boolean | string | string[] }>

Parameters

  • returnOnlyValuesForPwcSelects: Optional, defaults to false. If true, the values of pwc-choices fields will be object arrays containing choice objects, as passed to the items configuration. If false, they will be string arrays containing only values of each choice object.

pwc-dynamic-form-content

Render structure

<div>
  Generated fields
</div>

items Prop

items: string | PwcDynamicForm.ContentItemConfig[]

This prop is our configuration for the form fields.

Example

dynamicFormContent.items = [
  {
    type: "select-single",
    name: "single-select-1",
    id: "single-select-1",
    label: "This is a label!",
    distinct: "value",
    choices: [
      {
        value: "superstar",
        label: "Superstar"
      },
      {
        value: "foo",
        label: "bar"
      }
    ]
  },
  {
    type: "checkbox",
    name: "checkbox_1",
    id: "checkbox_1",
    label: "This is another label!"
  }
];

PwcDynamicForm.ContentItemConfig type union

type ContentItemConfig = NativeInputConfig | PwcSelectConfig | PwcColorPickerConfig

This type is a union of the supported interfaces for the fields.

NativeInputConfig interface

export interface NativeInputConfig
  extends JSXBase.InputHTMLAttributes<HTMLInputElement> {
  label: string;
}

This interface is used for native HTML input fields.

  • label: Translated into a <label> element for our generated element.

You can also pass in all valid HTML attributes of an <input> tag, alongside the custom fields listed above.

PwcSelectConfig interface

export interface PwcSelectConfig
  extends JSXBase.InputHTMLAttributes<HTMLPwcChoicesElement> {
  type: "select-single" | "select-multiple" | "select-text";
  label: string;
  choices: Array<any>;
  distinct?: "value" | "label" | "all" | "none";
}

This interface is used for pwc-choices web components.

  • type: The type of the generated pwc-choices web component. Mapping:

    • select-single -> single
    • select-multiple -> multiple
    • select-text -> text

  • label: Translated into a <label> element for our generated element.

  • choices: The array of choice objects for this element. A usual choice object looks like this:

{
    label: "Superstar",
    value: "superstar",
    selected: false, // optional
    disabled: false, // optional
    /* any other custom field you wish can also be passed */
}

You can also pass in all valid HTML attributes of an <pwc-choices> tag, alongside the custom fields listed above.

PwcColorPickerConfig interface

export interface PwcColorPickerConfig
  extends JSXBase.InputHTMLAttributes<HTMLPwcColorPickerElement> {
  label: string;
}

This interface is used for pwc-color-picker web components.

You can pass in all valid HTML attributes of a <pwc-color-picker> tag. The label field is translated into a <label> element for our generated element.

fieldChanged Event

fieldChanged: EventEmitter<PwcDynamicForm.FieldChangedEventPayload>

This event is emitted whenever a field changes.

Payload

element: HTMLInputElement | HTMLPwcChoicesElement | HTMLPwcColorPickerElement;
newValue: string | string[];
originalEvent: Event | CustomEvent;
  • element: The form element that changed.
  • newValue: The new value of the element that changed.
  • originalEvent: The original event that caused this event to be raised.

Element Generation

The type of the generated element is determined with the type field in the element's configuration object, in items prop:

  • color -> <pwc-color-picker>
  • select-single -> <pwc-choices> with single select config.
  • select-multiple -> <pwc-choices> with multiple select config.
  • select-text -> <pwc-choices> with text select config.
  • Any other type -> <input type="__TYPE__">

The final generated structure will look like this:

<div class="form-group">
  <label>
    Label
    <__GENERATED ELEMENT__></__GENERATED ELEMENT__>
  </label>
</div>

Note: Placement of the label text depends on the generated element type.

Example element generation for pwc-choices

Item config:

{
  type: "select-single",
  name: "ss1-name",
  id: "ss1-id",
  label: "ss1-label",
  distinct: "value",
  choices: [
    {
      value: "superstar",
      label: "Superstar",
      selected: false,
      disabled: false
    },
    {
      value: "foo",
      label: "bar",
      selected: false,
      disabled: false
    }
  ]
}

Generated element:

<div class="form-group">
  <label>
    ss1-label
    <pwc-choices
      type="single"
      name="ss1"
      id="ss1"
      distinct="value"
      choices='[
        {
          "value": "superstar",
          "label": "Superstar",
          "selected": false,
          "disabled": false
        },
        {
          "value": "foo",
          "label": "bar",
          "selected": false,
          "disabled": false
        }
      ]'
    ></pwc-choices>
  </label>
</div>

Example element generation for a native HTML input

Item config:

{
  type: "number",
  name: "number-input-name",
  id: "number-input-id",
  label: "This is a number input!",
  required: true
}

Generated element:

<div class="form-group">
  <label>
    This is a number input!
    <input
      type="number"
      name="number-input-name"
      id="number-input-id"
      required
    ></input>
  </label>
</div>

Notes

  • For color and checkbox types, the label text is placed after the input element.
  • More items will be supported soon, and we plan on implementing an interface, which you can use to add support for your own custom elements.

pwc-dynamic-form-buttons

Render structure

<div>
  Generated buttons
</div>

items Prop

items: string | PwcDynamicForm.ButtonItemConfig[]

This prop is our configuration for the form fields.

ButtonItemConfig type

ButtonItemConfig = JSXBase.InputHTMLAttributes<HTMLInputElement>

You can pass in any valid attribute of an html <input> tag to an object of this type.

Button Generation

The given config object for the button is simply translated into <input {...config}></input>.

Example

Item config:

{
  type: "submit",
  id: "foo",
  name: "bar"
}

Generated button:

<input type="submit" id="foo" name="bar"></input>