# form

[[toc]]

Blessing Skin uses AdminLTE as the UI framework, so the forms on the page can be well beautified. Blessing Skin provides the OptionFormclass and OptionFormItemclass, which can help us quickly generate AdminLTE-style forms. In fact, Blessing Skin also uses these two classes extensively internally.

OptionFormclass is used to generate the form, and the OptionFormItemclass is used to generate each form item in the form.

# create a form

You can either create a form in the controller and render the form and pass it to the view, or you can embed a piece of PHP code directly in the view to create the form.

Creating a form is as simple as calling the OptionFacade's formmethod. The formmethod receives three parameters. The first parameter is the name of the form (but not the title displayed on the page), which must be unique. The second parameter is the title, which will be displayed on the page and can be repeated. The third parameter is a callback function, and the callback function receives a parameter of type App\Services\OptionForm.

The code to create the form is as follows:

$form = Option::form( ' my_form ' , 'Form example' , function ( $form ) {
    // 
}) ;

OptionForm::AUTO_DETECTin the second parameter , so that Blessing Skin will look for the corresponding multilingual text in the language file according to the unique name of your form, and use it as the title.

# generate form

After creating the form in the above way, you need to generate the form:

$form- >handle() ;

Only by calling the handlemethod on the form can the form accept POST requests in response to data changes.

# render form

Calling the handlemethod just generates the form, but nothing is displayed on the page at this time, because we haven't rendered the form yet.

The OptionForminstance provides a variety of methods that allow us to render forms with different characteristics, but in any case, the rendermethod must be called to generate the HTML of the form.

Here is a simple example:

{!! $form->render() !!}

rendermethod will return the HTML of the form. Because of this, we need to avoid letting Laravel's template engine escape the generated HTML. (Using double curly braces {{ }}will escape the content, using {!! !!}will not) :::

The rendered form will appear as follows on the page:

Form rendering result

By default, Blessing Skin will use the <table>element for each form item in the form. If you don't want this, you can call the form instance's renderWithoutTablemethod. However, this is generally not recommended.

$ form->renderWithoutTable() ;

Usually, each form item has its title and corresponding input box. If you want to display only the input box without the title on the left, you can call the renderInputTagsOnlymethod of the form instance.

$ form->renderInputTagsOnly() ;

In addition, you can also cancel the rendering of the "submit" button by calling the renderWithoutSubmitButton method:

$ form->renderWithoutSubmitButton() ;

# life cycle hook

Each form instance provides lifecycle hooks that you can use to intervene with the form.

# Before the form is rendered

You can call the alwaysmethod on the form instance and pass it a callback function. The form will execute this callback function before rendering. Such as:

$form- >always( function ( $form ) {
    // $form parameter is this form instance 
}) ;

# Before the form handles the POST request

You can call the beforemethod on the form instance and pass it a callback function. The form will execute this callback function before processing the POST request. Such as:

$form- >before( function ( $form ) {
    // $form parameter is this form instance 
}) ;

# After the form handles the POST request

You can call the aftermethod on the form instance, passing it a callback function. The form will execute this callback function after processing the POST request. Such as:

$form- >after( function ( $form ) {
    // $form parameter is this form instance 
}) ;

# add message

You can add a message to the form, which will appear at the top of the form.

$form ->addMessage( 'It's not easy to write a document' ) ;

info type message

You can also output different types of messages:

$form ->addMessage( 'It's not easy to write a document' , 'success' ) ;

success type message

$form ->addMessage( 'It's not easy to write a document' , 'warning' ) ;

warning type message

$form ->addMessage( 'It's not easy to write a document' , 'danger' ) ;

danger message

# add notice

You can add a notice to the form. It will appear at the top of the form.

$form ->addAlert( 'This is text' ) ;

You can also output different types of notifications, just like addMessagedoes. The default type is info.

# add button

You can add buttons other than "Submit" to the form, and the added button will appear next to the "Submit" button. You can call the addButtonmethod on the form instance and pass in an array of key-value pairs as a parameter.

The following options can exist in the array, all of which can be omitted:

style- the style of the button, the currently supported values of style are ``default, primary, success, info, danger, warning, default is default.
class- HTML classes to add to the button, as an array, not a string.
href- If you use this option, the final button will be rendered as an <a>element instead of a <button>element, and the <a>element's link points to the hrefvalue you pass.
text- the text to display on the button.
type- the type of the button, this option cannot be used with href at the same time, it is onlymeaningful when rendered as <button> .
name- the name attribute of the button, onlymeaningful when rendered as a <button> .

$ form->addButton([
    'style' => 'primary' ,
    'text' => 'click me' 
]) ;

button

# pass data

Since a form is also a view in Blessing Skin, you can also pass data to it, just call the withmethod, the usage is the same as the with of the view.

# Set form border type

Call the typemethod to set the style of the form border.

$form- >type( 'info' ) ;

info border

$form- >type( 'success' ) ;

success border

$form- >type( 'warning' ) ;

warning border

$form ->type( 'danger' ) ;

danger border

$form- >type( 'default' ) ;

default border

# add controls

Controls are indispensable in forms, and there are a series of methods on form instances that allow you to add controls. The first parameter of each control method is its key in the optionstable, so you don't have to pay attention to where the data in the form will be saved-they will correspond to the name of the control one by one. The second parameter is the title of each form item displayed in the form. Of course, you can also use OptionForm::AUTO_DETECTto let Blessing Skin automatically find the corresponding translation text from the language file.

The code for adding controls should be written in the third parameter in Option::form , which is the callback function, such as:

$form = Option::form( ' my_form ' , 'form' , function ( $form ) {
    $form- >text( /* ... */ ) ; 
}) ;

# text input box

$ form- >text( 'my_text' , 'Text input box' ) ;

text box

You can add placeholders to textboxes:

$ form- >text( 'my_text' , 'Text input box' )->placeholder( 'placeholder' ) ;

text box with placeholder

# check box

$ form- >checkbox( 'my_checkbox' , 'checkbox' ) ;

check box

You can also add a label after the checkbox.

$ form- >checkbox( 'my_checkbox' , 'check box' )->label( 'label' ) ;

Labeled checkbox

# text field

$ form- >textarea( 'my_textarea' , 'TextField' ) ;

text field

You can specify how many lines are in the text field:

$ form- >textarea( 'my_textarea' , 'TextField' )->rows( 50 ) ;

# drop down box

$ form- >select( 'my_select' , 'Drop-down box' ) 
->option( 'option1' , ' option1' ) 
->option( 'option2' , 'Option 2' ) ;

drop down box

Expanded drop down box

The first parameter of the optionmethod is the value of the option, which will be passed to the backend and saved to the database; the second parameter is the text displayed on the page.

# text box group

$form ->group( 'my_group' , 'textbox group' ) 
->text( 'input1' ) 
->addon( 'to' ) 
->text( 'input2' ) ;

text box group

textmethod and the addonmethod can be used in any number without limitation.

# Methods shared by controls

In addition to their own methods, each control also has some common methods. These methods can be used on any control.

The following introductions all take the text box as an example.

# `value`method

With the valuemethod, you can pre-set the value of the control, other than the default empty or the saved value from the database optionstable:

$form- >text( 't' , 'Text box' )->value( 'Preset value' ) ;

value method

# `hint`method

Use the hintmethod to add a question mark icon to the right of the title of the form item. When the mouse hovers over the icon, there will be a bubble prompt.

$form- >text( 't' , 'Text box' )->hint( 'You may not know...' ) ;

hint method

# `format`method

Using the formatmethod, you can process the data entered by the user. Blessing Skin will first execute the callback function passed in the formatmethod, and then save the data to the database.

$form- >text( 't' , 'textbox' ) 
->format( function ( $data ) {
      // The $data parameter here is the value of this form item, not the data of the entire form. 
}) ;

# `disabled`method

Disable controls. When disabled, the user cannot interact with the control.

$form- >text( 't' , 'Text Box' )->disabled() ;

disabled method

# `description`method

This method will add a description below the control. You can pass HTML to this method and it will not be escaped.

$form- >text( 't' , 'Text box' )->description( 'This is a description' ) ;

description method

← persistent configuration helper function →