New-UDForm

Forms can contain any set of input controls. Each of the controls will report its value back up to the form when the submit button is clicked.

Synopsis

Forms can contain any set of input controls. Each of the controls will report its value back up to the form when the submit button is clicked.

Syntax

New-UDForm [-Id <String>] [-OnValidate <Endpoint>] [-SubmitText <String>] [-CancelText <String>] [-ButtonVariant <String>] [-ClassName <String>] [-DisableSubmitOnEnter] [-Script <String>] [-OutputType <String>] [-ShowBackButton] [<CommonParameters>]

    New-UDForm [-Id <String>] -Children <ScriptBlock> -OnSubmit <Endpoint> [-OnValidate <Endpoint>] [-OnProcessing <ScriptBlock>] [-OnCancel <Endpoint>] [-SubmitText <String>] [-CancelText <String>] [-ButtonVariant <String>] [-ClassName <String>] [-DisableSubmitOnEnter] [<CommonParameters>]

    New-UDForm [-Id <String>] -OnSubmit <Endpoint> [-ButtonVariant <String>] [-ClassName <String>] -Schema <Hashtable> [-UiSchema <Hashtable>] [-FormData <Hashtable>] [-DisableSubmitOnEnter] [<CommonParameters>]

Description

Creates a new form. Forms can contain any set of input controls. Each of the controls will report its value back up to the form when the submit button is clicked.

Parameters

-Id

The ID of the component. It defaults to a random GUID.

Required?                    false
Position?                    named
Default value                [Guid]::NewGuid().ToString()
Accept pipeline input?       false
Aliases
Accept wildcard characters?  false

-Children

Controls that make up this form. This can be any combination of controls. Input controls will report their state to the form.

Required?                    true
Position?                    named
Default value
Accept pipeline input?       false
Aliases
Accept wildcard characters?  false

-OnSubmit

A script block that is execute when the form is submitted. You can return controls from this script block and the form will be replaced by the script block. The $EventData variable will contain a hashtable of all the input fields and their values.

Required?                    true
Position?                    named
Default value
Accept pipeline input?       false
Aliases
Accept wildcard characters?  false

-OnValidate

A script block that validates the form. Return the result of a call to New-UDFormValidationResult.

Required?                    false
Position?                    named
Default value
Accept pipeline input?       false
Aliases
Accept wildcard characters?  false

-OnProcessing

A script block that is called when the form begins processing. The return value of this script block should be a component that displays a loading dialog. The script block will receive the current form data.

Required?                    false
Position?                    named
Default value
Accept pipeline input?       false
Aliases
Accept wildcard characters?  false

-OnCancel

A script block that is called when a form is cancelled. Useful for closing forms in modals.

Required?                    false
Position?                    named
Default value
Accept pipeline input?       false
Aliases
Accept wildcard characters?  false

-SubmitText

Text to show within the submit button. Defaults to 'Submit'.

Required?                    false
Position?                    named
Default value                Submit
Accept pipeline input?       false
Aliases
Accept wildcard characters?  false

-CancelText

Text to show within the cancel button. Defaults to 'Cancel'.

Required?                    false
Position?                    named
Default value                Cancel
Accept pipeline input?       false
Aliases
Accept wildcard characters?  false

-ButtonVariant

Type of button to display. Defaults to text. Valid values are contained, outlined, text.

Required?                    false
Position?                    named
Default value                text
Accept pipeline input?       false
Aliases
Accept wildcard characters?  false

-ClassName

A CSS class to apply to the form.

Required?                    false
Position?                    named
Default value
Accept pipeline input?       false
Aliases
Accept wildcard characters?  false

-Schema

Defines a form based on a hashtable of schema. This version of forms is based on react-jsonschema-form.

Required?                    true
Position?                    named
Default value
Accept pipeline input?       false
Aliases
Accept wildcard characters?  false

-UiSchema

Used to modify the ordering of the fields (see documentation)

Required?                    false
Position?                    named
Default value                @{}
Accept pipeline input?       false
Aliases
Accept wildcard characters?  false

-FormData

Required?                    false
Position?                    named
Default value                @{}
Accept pipeline input?       false
Aliases
Accept wildcard characters?  false

    -DisableSubmitOnEnter [<SwitchParameter>]
        Disables the functionality where pressing enter in a textbox submits the form it is a part of.

Required?                    false
Position?                    named
Default value                False
Accept pipeline input?       false
Aliases
Accept wildcard characters?  false

-Script

Used to automatically generate forms based on scripts in your PowerShell Universal environment. Script forms will generate input components based on the param block. Script forms automatically support progress and feedback.

Required?                    false
Position?                    named
Default value                None
Accept pipeline input?       false
Aliases
Accept wildcard characters?  false

-OutputType

The type of output to return from the script. Valid values are: "Text", "Table"

Required?                    false
Position?                    named
Default value                Text
Accept pipeline input?       false
Aliases
Accept wildcard characters?  false

    -ShowBackButton [<SwitchParameter>]
        Shows a back button after the form is submitted. This is only used for script forms.

Required?                    false
Position?                    named
Default value                False
Accept pipeline input?       false
Aliases
Accept wildcard characters?  false

    <CommonParameters>
        This cmdlet supports the common parameters: Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer, PipelineVariable, and OutVariable. For more information, see
        about_CommonParameters (https://go.microsoft.com/fwlink/?LinkID=113216).

Outputs

-------------------------- EXAMPLE 1 --------------------------

PS >New-UDForm -Id 'form1' -Content {
PS >     New-UDTextbox -Id 'form1Textbox' -Label 'Name'
PS > } -OnSubmit {
PS >     Show-UDToast -Message ($EventData.form1Textbox)
PS > }

Basic|Creates a basic form.




-------------------------- EXAMPLE 2 --------------------------

PS >New-UDForm -Id 'form2' -Content {
PS >     New-UDTextbox -Id 'form2Textbox' -Label 'Name'
PS > } -OnSubmit {
PS >     Show-UDToast -Message ($EventData.form2Textbox)
PS > } -OnValidate {
PS >     if ($EventData.form2Textbox -eq 'Bob') {
PS >         New-UDValidationResult -ValidationError 'Bob is not allowed'
PS >     }
PS >     else {
PS >         New-UDValidationResult -Valid
PS >     }
PS > }

Validation|Creates a form with validation.




-------------------------- EXAMPLE 3 --------------------------

PS >New-UDForm -Id 'form3' -Content {
PS >     New-UDTextbox -Id 'form3Textbox' -Label 'Name'
PS > } -OnSubmit {
PS >     Start-Sleep -Seconds 5
PS >     Show-UDToast -Message ($EventData.form3Textbox)
PS > } -OnProcessing {
PS >     New-UDCard -Title 'Processing' -Content {
PS >         New-UDProgress
PS >     }
PS > }

Processing|Creates a form with a processing dialog.




-------------------------- EXAMPLE 4 --------------------------

PS >New-UDForm -Id 'form4' -Content {
PS >     New-UDTextbox -Id 'form4Textbox' -Label 'Name'
PS > } -OnSubmit {
PS >     Show-UDToast -Message ($EventData.form4Textbox)
PS > } -OnCancel {
PS >     Show-UDToast -Message 'Form was cancelled'
PS > }

Cancel|Creates a form with a cancel button.




-------------------------- EXAMPLE 5 --------------------------

PS >New-UDForm -Id 'form5' -Content {
PS >     New-UDTextbox -Id 'form5Textbox' -Label 'Name'
PS > } -OnSubmit {
PS >     Show-UDToast -Message ($EventData.form5Textbox)
PS > } -SubmitText 'Save' -CancelText 'Close' -OnCancel {
PS >     Show-UDToast -Message 'Form was cancelled'
PS > }

Submit and Cancel Text|Creates a form with custom submit and cancel text.




-------------------------- EXAMPLE 6 --------------------------

PS >New-UDForm -Id 'form6' -Content {
PS >     New-UDTextbox -Id 'form6Textbox' -Label 'Name'
PS > } -OnSubmit {
PS >     Show-UDToast -Message ($EventData.form6Textbox)
PS > } -ButtonVariant 'contained'

Button Variant|Creates a form with a contained button variant.




-------------------------- EXAMPLE 7 --------------------------

PS >New-UDForm -Id 'form7' -Content {
PS >     New-UDTextbox -Id 'form7Textbox' -Label 'Name'
PS > } -OnSubmit {
PS >     Show-UDToast -Message ($EventData.form7Textbox)
PS > } -ClassName 'my-form'

Class Name|Creates a form with a custom CSS class name.




-------------------------- EXAMPLE 8 --------------------------

PS >New-UDForm -Id 'form8' -Schema @{
PS >     title = "Test Form"
PS >     type = "object"
PS >     properties = @{
PS >        name = @{
PS >            type = "string"
PS >        }
PS >        age = @{
PS >            type = "number"
PS >        }
PS >     }
PS > } -OnSubmit {
PS >     Show-UDToast -Message ($EventData.name)
PS >     Show-UDToast -Message ($EventData.age)
PS > }

Schema|Creates a form with a schema. You can find out more about JSON Schema here: https://rjsf-team.github.io/react-jsonschema-form/docs/




-------------------------- EXAMPLE 9 --------------------------

PS >New-UDForm -Id 'form9' -Schema @{
PS >     title = "Test Form"
PS >     type = "object"
PS >     properties = @{
PS >        name = @{
PS >            type = "string"
PS >        }
PS >        age = @{
PS >            type = "number"
PS >        }
PS >     }
PS > } -uiSchema @{
PS >	"ui:order" = @('age','name')
PS > } -FormData @{ Name = "adam"; Age = 38 } -OnSubmit {
PS >     Show-UDToast -Message ($EventData.name)
PS > }

UI Schema|Creates a form with a schema and a UI schema. You can find out more about JSON Schema here: https://rjsf-team.github.io/react-jsonschema-form/docs/




-------------------------- EXAMPLE 10 --------------------------

PS >New-UDForm -Id 'form10' -Script "Script1.ps1" -OutputType "Table"

Script|Creates a form from a script. Parameters of the script will define the form. Output from the script will be displayed in a table.




-------------------------- EXAMPLE 11 --------------------------

PS >New-UDForm -Id 'form11' -Content {
PS >    New-UDTextbox -Id 'form11Textbox' -Label 'Name'
PS > } -OnSubmit {
PS >     Show-UDToast -Message ($EventData.form11Textbox)
PS > }
PS > New-UDButton -Text "A submit button outside the form" -OnClick {
PS >     Invoke-UDForm -Id "form11"
PS > }

Invoke-UDForm|Creates a form with a submit button outside the form.




-------------------------- EXAMPLE 12 --------------------------

PS >New-UDForm -Id 'form12' -Content {
PS >    New-UDTextbox -Id 'form12Textbox' -Label 'Name'
PS > } -OnSubmit {
PS >     Show-UDToast -Message ($EventData.form12Textbox)
PS > } -OnValidate {
PS >     if ($EventData.form12Textbox -eq 'Hello') {
PS >         New-UDValidationResult -Valid
PS >     }
PS >     else {
PS >         New-UDValidationResult -ValidationError "Name must be 'Hello'"
PS >     }
PS > }
PS > New-UDButton -Text "Validate form" -OnClick {
PS >     Test-UDForm -Id "form12"
PS > }

Test-UDForm|Creates a form with a validate button outside the form.