OctoberCms Forms

OctoberCms Forms

     

Defining form fields（you can define youself form filed）

Form fields are defined with the YAML file. The form fields configuration is used by the form behavior for creating the form controls and binding them to the model fields. The file is placed to a subdirectory of the models directory of a plugin. The subdirectory name matches the model class name written in lowercase. The file name doesn't matter, but fields.yaml and form_fields.yaml are common names. Example form fields file location:

plugins/  acme/    blog/      models/            <=== Plugin models directory        post/            <=== Model configuration directory          fields.yaml    <=== Model form fields config file        Post.php         <=== model class

Fields can be placed in three areas, the outside area, primary tabs or secondary tabs. The next example shows the typical contents of a form fields definition file.

# ===================================#  Form Field Definitions# ===================================

fields:
    blog_title:
        label: Blog Title
        description: The title for this blog

    published_at:
        label: Published date
        description: When this blog post was published
        type: datepicker

    [...]

tabs:
    fields:
        [...]

secondaryTabs:
    fields:

[...]

Tab options

For each tab definition, namely tabs and secondaryTabs, you can specify these options:对于每一个tab 定义，命名tabs和secondaryTabs

OptionDescriptionstretchspecifies if this tab stretches to fit the parent height.defaultTabthe default tab to assign fields to. Default: Misc.cssClassassigns a CSS class to the tab container.

Field options

For each field you can specify these options (where applicable):

OptionDescriptionlabela name when displaying the form field to the user.typedefines how this field should be rendered (see Available fields types below). Default: text.spanaligns the form field to one side. Options: auto, left, right, full. Default: auto.sizespecifies a field size for fields that use it, for example, the textarea field. Options: tiny, small, large, huge, giant.placeholderif the field supports a placeholder value.commentplaces a descriptive comment below the field.commentAboveplaces a comment above the field.commentHtmlallow HTML markup inside the comment. Options: true, false.defaultspecifies the default value for the field.defaultFromtakes the default value from the value of another field.tabassigns the field to a tab.cssClassassigns a CSS class to the field container.disabledgrays out the field if set to true. Options: true, false.hiddenhides the field from the view. Options: true, false.stretchspecifies if this field stretches to fit the parent height.contextspecifies what context should be used when displaying the field. Context can also be passed by using an @ symbol in the field name, for example, [e-mail] array of other field names this field depends on, when the other fields are modified, this field will update.triggerspecify conditions for this field using trigger events.presetallows the field value to be initially set by the value of another field, converted using theinput preset converter.requiredplaces a red asterisk next to the field label to indicate it is required.attributesspecify custom HTML attributes to add to the form field element.containerAttributesspecify custom HTML attributes to add to the form field container.

Available field types(可用的域类型)

There are various native field types that can be used for the type setting. For more advanced form fields, a form widget can be used instead.

• Text
• Number
• Password
• Textarea
• Dropdown
• Radio List
• Checkbox
• Checkbox List
• Switch
• Section

  Text

  text - renders a single line text box. This is the default type used if none is specified.

  blog_title:    label: Blog Title    type: text

  Number

  number - renders a single line text box that takes numbers only.

  your_age:    label: Your Age    type: number

  Password

  password - renders a single line password field.

  user_password:    label: Password    type: password

  Textarea

  textarea - renders a multiline text box. A size can also be specified with possible values: tiny, small, large, huge, giant.

  blog_contents:    label: Contents    type: textarea    size: large

  Dropdown

  dropdown - renders a dropdown with specified options. There are 4 ways to provide the drop-down options. The first method defines options directly in the YAML file:

  status:    label: Blog Post Status    type: dropdown    options:        draft: Draft        published: Published        archived: Archived

  The second method defines options with a method declared in the model's class. If the options element is omitted, the framework expects a method with the name get*Field*Options() to be defined in the model. Using the example above, the model should have the getStatusOptions() method. This method takes a single parameter, the current key value, and should return an array of options in the format key => label.

  status:    label: Blog Post Status    type: dropdown

  Supplying the dropdown options tn the model class:

  public function getStatusOptions($keyValue = null){    return ['all' => 'All', ...];}

  The third global method getDropdownOptions() can also be defined in the model, this will be used for all dropdown field types for the model. This method takes two parameters, the field name and current key value, and should return an array of options in the format key => label.

  public function getDropdownOptions($fieldName = null, $keyValue = null){    if ($fieldName == 'status')        return ['all' => 'All', ...];    else        return ['' => '-- none --'];}

  The fourth method uses a specific method declared in the model's class. In the next example the listStatuses()method should be defined in the model class. This method takes two parameters, the current key value and field name, and should return an array of options in the format key => label.

  status:    label: Blog Post Status    type: dropdown    options: listStatuses

  Supplying the dropdown options to the model class:

  public function listStatuses($keyValue = null, $fieldName = null){    return ['published' => 'Published', ...];}

  By default the dropdown has a searching feature, allowing quick selection of a value. This can be disabled by setting the showSearch option to false.

  status:    label: Blog Post Status    type: dropdown    showSearch: false

  Radio List

  radio - renders a list of radio options, where only one item can be selected at a time.

  security_level:    label: Access Level    type: radio    options:        all: All        registered: Registered only        guests: Guests only

  Radio lists can also support a secondary description.

  security_level:    label: Access Level    type: radio    options:        all: [All, Guests and customers will be able to access this page.]        registered: [Registered only, Only logged in member will be able to access this page.]        guests: [Guests only, Only guest users will be able to access this page.]

  Radio lists support three ways of defining the options, exactly like the dropdown field type. For radio lists the method could return either the simple array: key => value or an array of arrays for providing the descriptions: key => [label, description]

  Checkbox

  checkbox - renders a single checkbox.

  show_content:    label: Display content    type: checkbox    default: true

  Checkbox List

  checkboxlist - renders a list of checkboxes.

  permissions:    label: Permissions    type: checkboxlist    options:        open_account: Open account        close_account: Close account        modify_account: Modify account

  Checkbox lists support three ways of defining the options, exactly like the dropdown field type and also support secondary descriptions, found in the radio field type.

  Switch

  switch - renders a switchbox.

  show_content:    label: Display content    type: switch    comment: Flick this switch to display content

  Section

  section - renders a section heading and subheading. The label and comment values are optional and contain the content for the heading and subheading.

  user_details_section:    label: User details    type: section    comment: This section contains details about the user.

  Partial

  partial - renders a partial, the path value can refer to a partial view file otherwise the field name is used as the partial name. Inside the partial these variables are available: $value is the default field value, $model is the model used for the field and $field is the configured class object Backend\Classes\FormField.

  content:    type: partial    path: $/acme/blog/models/comments/_content_field.htm

  Hint

  hint - identical to a partial field but renders inside a hint container that can be hidden by the user.

  content:    type: hint    path: content_field

  Widget

  widget - renders a custom form widget, the type field can refer directly to the class name of the widget or the registered alias name.

  blog_content:    type: Backend\FormWidgets\RichEditor    size: huge

  Form widgets

  There are various form widgets included as standard, although it is common for plugins to provide their own custom form widgets. You can read more on the Form Widgets article.

  • Code editor
  • Color picker
  • Date picker
  • File upload
  • Record finder
  • Media finder
  • Relation
  • Repeater
  • Rich editor / WYSIWYG
  • Markdown editor
  • Tag list

  Code editor

  codeeditor - renders a plaintext editor for formatted code or markup. Note the options may be inherited by the code editor preferences defined for the Administrator in the back-end.

  css_content:    type: codeeditor    size: huge    language: html

  OptionDescriptionlanguagecode language, for example, php, css, js, html. Default: php.showGuttershows a gutter with line numbers. Default: true.wrapWordsbreaks long lines on to a new line. Default true.fontSizethe text font size. Default: 12.

  Color picker

  colorpicker - renders controls to select a hexadecimal color value.

  color:    label: Background    type: colorpicker

  OptionDescriptionavailableColorslist of available colors.

  Date picker

  datepicker - renders a text field used for selecting date and times.

  published_at:    label: Published    type: datepicker    mode: date

  OptionDescriptionmodethe expected result, either date, datetime or time. Default: datetime.minDatethe minimum/earliest date that can be selected. Default: 2000-01-01.maxDatethe maximum/latest date that can be selected. Default: 2020-12-31.

  File upload

  fileupload - renders a file uploader for images or regular files. The field name must use an attachOne or attachMany relation.

  avatar:    label: Avatar    type: fileupload    mode: image    imageHeight: 260    imageWidth: 260

  OptionDescriptionmodethe expected file type, either file or image. Default: file.imageWidthif using image type, the image will be resized to this width, optional.imageHeightif using image type, the image will be resized to this height, optional.fileTypesfile extensions that are accepted by the uploader, optional. Eg: zip,txtmimeTypesMIME types that are accepted by the uploader, either as file extension or fully qualified name, optional. Eg: bin,txtuseCaptionallows a title and description to be set for the file. Default: trueprompttext to display for the upload button, applies to files only, optional.

  Record finder

  recordfinder - renders a field with details of a related record. Expanding the field displays a popup list to search large amounts of records. Supported by singular relationships only.

  user:    label: User    type: recordfinder    list: $/rainlab/user/models/user/columns.yaml    prompt: Click the %s button to find a user    nameFrom: name    descriptionFrom: email

  OptionDescriptionnameFromthe column name to use in the relation used for displaying the name. Default: name.descriptionFromthe column name to use in the relation used for displaying a description. Default: description.titletext to display in the title section of the popup.prompttext to display when there is no record selected. The %s character represents the search icon.lista configuration array or reference to a list column definition file, see list columns.recordsPerPagerecords to display per page, use 0 for no pages. Default: 10conditionsspecifies a raw where query statement to apply to the list model query.scopespecifies a query scope method defined in the related form model to apply to the list query always.searchModedefines the search strategy to either contain all words, any word or exact phrase. Supported options: all, any, exact. Default: all.searchScopespecifies a query scope method defined in the related form model to apply to the search query, the first argument will contain the search term.

  Media finder

  mediafinder - renders a field for selecting an item from the media manager library. Expanding the field displays the media manager to locate a file. The resulting selection is a string as the relative path to the file.

  background_image:    label: Background image    type: mediafinder    mode: image

  OptionDescriptionmodethe expected file type, either file or image. Default: file.prompttext to display when there is no item selected. The %s character represents the media manager icon.

  Relation

  relation - renders either a dropdown or checkbox list according to the field relation type. Singular relationships display a dropdown, multiple relationships display a checkbox list. The label used for displaying each relation is sourced by the nameFrom or select definition.

  categories:    label: Categories    type: relation    nameFrom: title

  Alternatively, you may populate the label using a custom select statement. Any valid SQL statement works here.

  user:    label: User    type: relation    select: concat(first_name, ' ', last_name)

  OptionDescriptionnameFroma model attribute name used for displaying the relation label. Default: name.selecta custom SQL select statement to use for the name.descriptionFromthe column name to use in the relation used for displaying a description (optional). Default: description.emptyOptiontext to display when there is no available selections.

  Repeater

  repeater - renders a repeating set of form fields defined within.

  extra_information:    type: repeater    form:        fields:            added_at:                label: Date added                type: datepicker            details:                label: Details                type: textarea

  OptionDescriptionforma reference to form field definition file, see backend form fields. Inline fields can also be used.prompttext to display for the create button. Default: Add new item.

  Rich editor / WYSIWYG

  richeditor - renders a visual editor for rich formatted text, also known as a WYSIWYG editor.

  html_content:    type: richeditor    toolbarButtons: bold|italic    size: huge

  OptionDescriptiontoolbarButtonswhich buttons to show on the editor toolbar. Default:paragraphFormat|paragraphStyle|quote|bold|italic|align|formatOL|formatUL|insertTable|insertLink|insertImage|insertVideo|insertAudio|insertFile|insertHR|fullscreen|html

  The available toolbar buttons are:

  fullscreen, bold, italic, underline, strikeThrough, subscript, superscript, fontFamily, fontSize, |, color, emoticons, inlineStyle, paragraphStyle, |, paragraphFormat, align, formatOL, formatUL, outdent, indent, quote, insertHR, -, insertLink, insertImage, insertVideo, insertAudio, insertFile, insertTable, undo, redo, clearFormatting, selectAll, html

  Note: | will insert a vertical separator line in the toolbar and - a horizontal one.

  Markdown editor

  markdown - renders a basic editor for markdown formatted text.

  md_content:    type: markdown    size: huge    mode: split

  OptionDescriptionmodethe expected view mode, either tab or split. Default: tab.

  Tag list

  taglist - renders a field for inputting a list of tags.

  tags:    type: taglist    separator: space

  A tag list can support three ways of defining the options, exactly like the dropdown field type.

  tags:    type: taglist    options:        - Red        - Blue        - Orange

  You may use the mode called relation where the field name is a many-to-many relationship. This will automatically source and assign tags via the relationship. If custom tags are supported, they will be created before assignment.

  tags:    type: taglist    mode: relation

  OptionDescriptionmodecontrols how the value is returned, either string, array or relation. Default: string.separatorseparate tags with the specified character, either comma or space. Default: comma.customTagsallows custom tags to be entered manually by the user. Default: trueoptionsspecifies a method or array for predefined options. Set to true to use model get*Field*Options()method. Optional.nameFromif relation mode is used, a model attribute name for displaying the tag name. Default: name.