Forms

Information about forms in ManageIQ.

Design Guidelines

Here are the guidelines for the consistent user experience of form fields derived from PatternFly.

• these are PatternFly patterns: top aligned labels, error field

Form checklist

• is it a required form? use *
• do you have correct helper text? provide a correct format Ex. Incorrect syntax used. Example: smtp.mailserver.com
• need a detailed description? add a popover icon next to the label
• when to show an error message? when the field loses focus
• vertical or horizontal? go with vertical as it's easier to scan and complete
• what is the width of the form? wrap it in bootstrap container (not fluid container)

Migration

First step - template

• use Data driven forms if possible
  • forms prepared to match all properties listed above
• use form container with class container to avoid endless fields expanding
  • will require small override of pf class. Use max-width instead of width. MIQ layout does have some additional spacing that causes overflow on small devices.
  • form container width will stop expanding so there won't be extremely large inputs

<div class="container">
  <form>
    ....
  </form>
</div>

• form field layout
  • All text field should be 100% width of its parent container.
  • Form groups should follow vertical layout.
  • Data driven forms enforce this.
  • Only exception is check box group with only one option. It should be replaced with switches or stay horizontal.
  • old haml forms should be migrated to following:
    • replacing div with .form-horizontal class with normal form tag
    • remove col-md classes from labels, inputs and help blocks
    • remove .form-horizontal div container

# before
.form-horizontal
  %div
    .form-group{...}
        %label.col-md-2.control-label{...}
          = _('Name')
        .col-md-8
          %input.form-control{...}
          %span.help-block{...}

# after
%form
  .form-group{...}
    %label.control-label
      = _('Name')
    %input.form-control{...}
    %span.help-block{...}

Second step - validation

Cloud Network

Networks > Networks > Configuration > Add a new Cloud Network

Required parameters for each type of Provider Network

type	physical_network	segmentation_id
flat	required
gre		required (GRE ID)
vlan	required	required (VLAN ID)
vxlan

Custom data driven forms component

Code Editor

This component uses codemirror editor. You can use it with or without data driven forms.

import CodeEditor, { DataDrivenFormCodeEditor } from '/app/javascript/components/code-editor' // path depends where you use it

Props

name	type	default	required	description
value	string	undefined	true	value of editor
onBeforeChange	func: (editor, data, value) => void	undefined	true	function that handles value changes
mode	on of ["yaml", "json"]	yaml	false	Language mode for code editor. Changes code highlight and validation later
modes	Array of strings	undefined	false	If specified adds radio buttons which will allow you to change between modes. If a prop mode is specified it will be picked as initial language mode
hasError	bool	false	false	If true changes styling of the editor to represent error state.
options	Object	Object	false	Use at your own risk. Configuration object for code mirror component. Options can be found here.

Basic usage

import React, { useState } from 'react'
import CodeEditor from '/app/javascript/components/code-editor'

const MyComponent = () => {
  const [value, setValue] = useState('') // set initial code editor value

  const handleChange(editor, data, value) => {
    //do something with editor or data if you need
    setValue(value)
  }

  return (
    <CodeEditor
      value={value} // value displayed in editir
      onBeforeChange={handleChange} // onChange handler the.
      hasError={bool} // sets error
      mode="json" // initial language
      modes={['json', 'yaml']} // shows radio buttons which allow switching between languages
    />
  )
}

Usage with data-driven-forms

const schema = {
  fields: [
   ...
   {
    component: 'code-editor',
    name: 'content',
    label: __('Content'),
    modes: ['yaml', 'json'],
    ...any other data driven specific attributes
   }
  ]
}