1. Pods
  2. Form Bean 1.1.6
  3. API
  4. FormBean

classafFormBean::FormBean

sys::Obj
  afFormBean::FormBean

Represents a Fantom type that can be rendered as a HTML form, and reconstituted back to a Fantom instance.

beanType

Source

const Type beanType

The bean type this FormBean represents.

createBean

Source

virtual Obj createBean([Str:Obj?]? extraProps := null)

Creates an instance of beanType with all the field values set to the form field values. Uses afBeanUtils::BeanProperties.create().

This should only be called after validateForm().

Any extra properties passed in will also be set.

errorMsgs

Source

Str[] errorMsgs := Str[,]

You may set any extra (cross field validation) error messages here. They will be rendered along with the form field error messages.

errorSkin

Source

@Inject { optional=true }
ErrorSkin? errorSkin

The ErrorSkin used to render error messages.

fieldMsg

Source

Str? fieldMsg(FormField formField, Str key, Obj? arg1 := null, Obj? arg2 := null, Obj? arg3 := null)

Returns a message for the given field and key. Messages are looked up in the following order:

  • <bean>.<field>.<key>
  • <field>.<key>
  • <key>

And the following substitutions are made:

  • ${label} -> formField.label
  • ${value} -> formField.formValue
  • ${arg1} -> arg1.toStr
  • ${arg2} -> arg2.toStr
  • ${arg3} -> arg3.toStr

The form value is substituted for ${value} because it is intended for use by validation msgs.

Returns null if a message could not be found.

fileUploadHook

Source

|Str,InStream->File? fileUploadHook

Hook for handling file uploads. By default, an in-memory file is returned. In memory files do not require deleting.

formFields

Source

Field:FormField formFields := ... { private set }

The form fields that make up this form bean.

getByName

Source

@Operator
FormField getByName(Str name)

Returns the form field that corresponds to the given field name.

formField := formBean["name"]
hasErrors

Source

Bool hasErrors()

Returns true if any form fields are in error, or if any extra error messages have been added to this

make

Source

new make(Type beanType, |This in)

Deconstructs the given form bean type to a map of FormFields.

messages

Source

Str:Str messages := ...

The message map used to find strings for labels, placeholders, hints, and validation errors. Messages are read from (and overridden by) the following pod resource files:

  • <beanType.name>.properties
  • FormBean.properties Note that property files must be in the same pod as the defining bean.
msg

Source

Str? msg(Str key, Obj? arg1 := null, Obj? arg2 := null, Obj? arg3 := null)

Returns a message for the given key. Messages are looked up in the following order:

  • <bean>.<key>
  • <key>

And the following substitutions are made:

  • ${arg1} -> arg1.toStr
  • ${arg2} -> arg2.toStr
  • ${arg3} -> arg3.toStr

Returns null if a message could not be found.

reinspectBean

Source

Void reinspectBean()

Re-generates the formFields map. Useful if you've set new message properties and want them to be picked up.

renderBean

Source

virtual Str renderBean(Obj? bean)

Renders the form bean to a HTML form.

If the given bean is null then values are taken from the form fields. Do so if you're re-rendering a form with validation errors.

renderErrors

Source

virtual Str renderErrors()

Renders form field errors (if any) to an unordered list. Delegates to a default instance of ErrorSkin which renders the following HTML:

<div class='formBean-errors'>
    <div class='formBean-banner'>#BANNER</div>
    <ul>
        <li> Error 1 </li>
        <li> Error 2 </li>
    </ul>
</div>

To change the banner message, set a message with the key errors.banner.

renderSubmit

Source

virtual Str renderSubmit()

Renders a simple submit button.

<div class='formBean-row submitRow'>
  <input type='submit' name='formBeanSubmit' class='submit' value='label'>
</div>

The label is taken from the msg key submit.label and defaults to Submit.

updateBean

Source

virtual Obj updateBean(Obj bean, [Str:Obj?]? extraProps := null)

Updates the given bean instance with form field values. Uses afBeanUtils::BeanProperties.

This should only be called after validateForm().

The given extra properties will also be set on the bean.

Returns the given bean instance.

validateForm

Source

virtual Bool validateForm(Str:Str form)

Populates the form fields with values from the given form map and performs server side validation. Error messages are saved to the form fields.

This method does not handle file uploads - use validateRequest() instead.

Returns true if all the values are valid, false if not.

It is safe to pass in HttpRequest.form() directly.

Note that all form values are trimmed before being stowed and validated.

validateRequest

Source

virtual Bool validateRequest(HttpRequest httpReq)

Populates the form fields with values from the HTTP Request and performs server side validation. Error messages are saved to the form fields.

This method also handles File uploads and sets any Buf and File fields to an appropriate value. HTML Forms with file uploads must have set the attribute <form enctype="multipart/form-data" ... >

If the form content type is not multipart/form-data then processing is delegated to validateForm(). That makes this method safe to use in all situations.

In memory file are returned for file uploads, so the caller does not need to concern themselves with deleting them.

Returns true if all the values are valid, false if not.