Form elements

Edit page

Fields are used to generate the output of the fill and edit form template.

Feel free to add your fields, for example, to use the convenient editor for you or any components.

Input

It is one of the versatile form elements and allows you to create different parts of the interface and provide interaction with the user. Mainly designed to create text fields.

Input

Example:

use Orchid\Screen\Fields\Input;

Input::make('name');

Design

Empty and expressionless input fields can confuse the user, but you can help by specifying a title.

Input::make('name')
    ->title('First name');

When you need to describe the purpose of the field in more detail, then you can use the hint:

Input::make('name')
    ->help('What is your name?');

If the field description is very specific and a large description is required, You can use the tooltip that will be shown as a popup:

Input::make('name')
    ->popover('Tooltip - hint that user opens himself.');

Horizontal or vertical view:

Input::make('name')->vertical();

Input::make('name')->horizontal();

Required

Sometimes you may need to specify a required field, to do this, call the required method:

Input::make('name')
    ->type('text')
    ->required();

Hiding

Input::make('name')->canSee(true);
Input::make('name')->canSee(false);

Note that many methods, such as canSee, required, title, help, vertical, horizontal and many others, are available in almost every field of the system.

Types

One of the most universal fields, by specifying a type, all html values are supported:

Please note. Support for the new HTML5 attributes is completely dependent on the browser used.

Text field. Designed to enter characters using the keyboard.

Input::make('name')->type('text');

A field for entering the name of the file that is sent to the server.

Input::make('name')->type('file');

Hidden field.

Input::make('name')->type('hidden');

Widget for choosing a color.

Input::make('name')->type('color');

For email addresses.

Input::make('name')->type('email');

Entering numbers.

Input::make('name')->type('number');

Slider to select numbers in the specified range.

Input::make('name')->type('range');

To specify web addresses.

Input::make('name')->type('url');

You can learn more about attribute types at Mozilla’s website.

Mask for entering values

Great if the values should be written in a standard form, such as TIN or phone number

Example:

Input::make('phone')
    ->mask('(999) 999-9999')
    ->title('Phone number');

An array with parameters can be passed to the mask, for example:

Input::make('price')
    ->title('Price')
    ->mask([
     'mask' => '999 999 999.99',
     'numericInput' => true
    ]);

Input::make('price')
    ->title('Price')
    ->mask([
        'alias' => 'currency',
        'prefix' => ' ',
        'groupSeparator' => ' ',
        'digitsOptional' => true,
    ]);

All available Inputmask options can be viewed here.

TextArea

The textarea field is a form element for creating an area into which multiple lines of text can be entered. In contrast to the input tag, it is permissible to do line breaks in the text field, they are saved when sending data to the server.

Example:

TextArea::make('description');

You can set the required number of rows using the rows method:

TextArea::make('description')
    ->rows(5);

CheckBox

A graphical user interface element that allows the user to control a parameter with two states – ☑ on and ☐ off.

Example:

CheckBox::make('free')
    ->value(1)
    ->title('Free')
    ->placeholder('Event for free')
    ->help('Event for free');

By default, browsers do not send the value of an unselected field. This complicates the installation of simple Boolean types. To solve this, there is a separate method in which the value false will be sent:

CheckBox::make('enabled')
    ->sendTrueOrFalse();

Select

Simple selection from an array list:

Select::make('select')
    ->options([
        'index'   => 'Index',
        'noindex' => 'No index',
    ])
    ->title('Select tags')
    ->help('Allow search bots to index');

Work with a source model:

Select::make('user')
    ->fromModel(User::class, 'email');

Source with the condition:

Select::make('user')
    ->fromQuery(User::where('balance', '!=', '0'), 'email');

Key change:

Select::make('user')
    ->fromModel(User::class, 'email', 'uuid');

There may be situations when you need to add some value, which means that the field is not selected. To do this, you can use the empty method:

// For array
Select::make('user')
    ->options([
        1  => 'Option 1',
        2  => 'Option 2',
    ])
    ->empty('No select');

// For model
Select::make('user')
    ->fromModel(User::class, 'name')
    ->empty('No select');

The empty method also accepts the second argument, which is responsible for the value:

Select::make('user')
    ->empty('No select', 0)
    ->options([
        1  => 'Option 1',
        2  => 'Option 2',
    ]);

Relation

Relations fields can load dynamic data, this is a good solution if you need connections.

Relation::make('idea')
    ->fromModel(Idea::class, 'name')
    ->title('Choose your idea');

For multiple selections, use the multiple() method.

Relation::make('ideas.')
    ->fromModel(Idea::class, 'name')
    ->multiple()
    ->title('Choose your ideas');

Note. Note the dot at the end of the name. It is necessary in order to show the expectedness of the array. As if it were HTML code <input name='ideas[]'>

To modify the load, you can use the reference to the scope model, for example, take only active:

namespace App;

use Illuminate\Database\Eloquent\Model;

class Idea extends Model
{

    /**
     * @param Builder $query
     *
     * @return Builder
     */
    public function scopeActive(Builder $query)
    {
        return $query->where('active', true);
    }
}

Relation::make('idea')
    ->fromModel(Idea::class, 'name')
    ->applyScope('active')
    ->title('Choose your idea');

You can also pass additional parameters to the method:

Relation::make('idea')
    ->fromModel(Idea::class, 'name')
    ->applyScope('status', 'active')
    ->title('Choose your idea');

You can add one or several fields, which will be additionally searched for:

Relation::make('idea')
     ->fromModel(Idea::class, 'name')
     ->searchColumns('author', 'description')
     ->title('Choose your idea');

To set the number of items that will be listed as a result of a search, you can chain the method chunk, passing the number of search results as a param:

Relation::make('users.')
    ->fromModel(User::class, 'name')
    ->chunk(20);

Selection options can work with calculated fields, but only to display the result, the search will occur only on one column in the database. To do this, use the displayAppend method.

namespace App;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * @return string
     */
    public function getFullAttribute(): string
    {
        return $this->attributes['name'] . ' (' . $this->attributes['email'] . ')';
    }
}

To indicate the displayed field you must:

Relation::make('users.')
    ->fromModel(User::class, 'name')
    ->displayAppend('full')
    ->multiple()
    ->title('Select users');

DateTime

Allows you to select the date and time.

Datatime

Example:

DateTimer::make('open')
    ->title('Opening date');

Allow direct input:

DateTimer::make('open')
    ->title('Opening date')
    ->allowInput();

Please note that setting a field can be mandatory only with direct input:

DateTimer::make('open')
    ->title('Opening date')
    ->allowInput()
    ->required();

Data format:

DateTimer::make('open')
    ->title('Opening date')
    ->format('Y-m-d');

Example for display in 24th format:

DateTimer::make('open')
    ->title('Opening date')
    ->format24hr();

Calendar over time:

DateTimer::make('open')
    ->title('Opening time')
    ->enableTime();

Choice of time only:

DateTimer::make('open')
    ->title('Opening time')
    ->noCalendar()
    ->format('h:i K');

DateRange

Allows you to select a range of date (and time).

Example:

DateRange::make('open')
    ->title('Opening between');

Default value / result is an array with keys of start, end.

TimeZone

Field for convenient time zone selection:

TimeZone::make('time');

Specification of specific time zones is possible using:

use DateTimeZone;

TimeZone::make('time')
    ->listIdentifiers(DateTimeZone::ALL);

The default value is DateTimeZone::ALL, but others are possible:

DateTimeZone::AFRICA;
DateTimeZone::AMERICA;
DateTimeZone::ANTARCTICA;
DateTimeZone::ARCTIC;
DateTimeZone::ASIA;
DateTimeZone::ATLANTIC;
DateTimeZone::AUSTRALIA;
DateTimeZone::EUROPE;
DateTimeZone::INDIAN;
DateTimeZone::PACIFIC;
DateTimeZone::UTC;
DateTimeZone::ALL_WITH_BC;
DateTimeZone::PER_COUNTRY;

The representation of variable zones can be found in the documentation PHP.

HTML Quill Editor

Such an editor allows you to insert pictures, tables, specify styles for text, video.

Example:

Quill::make('html');

There are 6 groups of controls available:

Quill::make('html')
    ->toolbar(["text", "color", "header", "list", "format", "media"]);

It’s possible to install additional plugins with a simple Javascript file

document.addEventListener('orchid:quill', (event) => {
    // Object for registering plugins
    event.detail.quill;

    // Parameter object for initialization
    event.detail.options;
});

Note: You can add custom scripts and stylesheets through the platform.php config file

Example for quill-image-compress:

Add the following in config/platform.php into the resource.scripts array

"https://unpkg.com/quill-image-compress@1.2.11/dist/quill.imageCompressor.min.js",
"/js/admin/quill.imagecropper.js",

create a quill.imagecropper.js in public/js/admin with the following content

document.addEventListener('orchid:quill', (event) => {
    // Object for registering plugins
    event.detail.quill.register("modules/imageCompressor", imageCompressor);

    // Parameter object for initialization
    event.detail.options.modules = {
         imageCompressor: {
            quality: 0.9,
            maxWidth: 1000, // default
            maxHeight: 1000, // default
            imageType: 'image/jpeg'
        }
    };
});

Markdown Editor

Editor for the lightweight markup language. Created with the goal of writing the most readable and easy to edit text. But suitable for converting into languages for advanced publications.

Markdown Markdown2

Example:

SimpleMDE::make('markdown');

Matrix

The field provides a convenient interface for editing a flat table. For example, you can store information inside a JSON column type:

Matrix::make('options')
    ->columns([
        'Attribute',
        'Value',
        'Units',
    ])

Not always the values of the columns can coincide with what needs to be displayed in the headers, for this you can write using the keys:

Matrix::make('options')
    ->columns([
        'Attribute' => 'attr',
        'Value' => 'product_value',
    ])

It is possible to indicate the maximum number of lines, upon reaching which the add button will not be available:

Matrix::make('options')
    ->columns(['id', 'name'])
    ->maxRows(10)

By default, each cell element has a textarea field, but you can change it to your own fields as follows:

Matrix::make('users')
    ->title('Users list')
    ->columns(['id', 'name'])
    ->fields([
        'id'   => Input::make()->type('number'),
        'name' => TextArea::make(),
    ]),

Code editor

A field for writing program code with the ability to highlight.

Code

Example:

Code::make('code');

To specify code highlighting for a specific programming language, you can use the language() method.

 Code::make('code')
     ->language(Code::CSS);

The following languages are available:

  • Markup – markup, html, xml, svg, mathml
  • CSS – css
  • C-like – clike
  • JavaScript – javascript, js

The number of lines is supported:

Code::make('code')
    ->lineNumbers();

Picture

Allows you to upload an image.

Example:

Picture::make('picture');

Laravel filesystems are supported:

Picture::make('picture')
    ->storage('s3');

Use the acceptedFiles method to define the types of files the field should accept, for example:

Picture::make('picture')
    ->acceptedFiles('.jpg');

The string passed is a comma-separated list of unique file type specifiers.

Cropper

Extends Picture and allows you to upload an image and crop to the desired format.

Cropper

Example:

Cropper::make('picture');

Width and height

In order to control the format, you can specify the width and height of the desired image:

Cropper::make('picture')
    ->width(500)
    ->height(300);

Or you can impose specific limits using minWidth / maxWidth or minHeight / maxHeight or use convenience methods minCanvas / maxCanvas

Cropper::make('picture')
    ->minCanvas(500)
    ->maxWidth(1000)
    ->maxHeight(800);

File size limit

To limit the size of the downloaded file, you must set the maximum value in MB.

Cropper::make('picture')
    ->maxFileSize(2);

Value

The control of the return value is carried out using the methods:

Cropper::make('picture')
    ->targetId();

The sequence number (id) of the Attachment record will be returned.

Cropper::make('picture')
    ->targetRelativeUrl();

Will return the relative path to the image.

Cropper::make('picture')
    ->targetUrl();

Will return the absolute path to the image.

Upload

Renders upload for images or regular files.

Example:

Upload::make('upload');

Upload::make('docs')
    ->groups('documents');

Upload::make('images')
    ->groups('photo');

To get specific files via Model relation

use Orchid\Attachment\Models\Attachment;

// One-to-Many (with foreign id)
public function hero()
{
    return $this->hasOne(Attachment::class, 'id', 'hero')->withDefault();
}

// Many-to-Many (no foreign id on table, should be uploaded with groups() function)
public function documents()
{
    return $this->hasMany(Attachment::class)->where('group','documents');
}

It can be used to limit the maximum number of files that will be processed:

Upload::make('upload')
    ->maxFiles(10);

Determines the number of concurrent downloads for processing files:

Upload::make('upload')
    ->parallelUploads(2);

Maximum upload file size: Default upload_max_filesize & post_max_size values are 2M, You can change them in php.ini to enable setting max file size to be more than 2M

Upload::make('upload')
    ->maxFileSize(1024); // Size in MB

The default implementation of accept checks the type or extension of the MIME file against this list. This is a comma-separated list of MIME types or file extensions.

Upload::make('upload')
    ->acceptedFiles('image/*,application/pdf,.psd');

The upload field can work with various repositories. To specify it, you must pass the key specified in config/filesystems.php:

Upload::make('upload')
    ->storage('s3');

The default storage is public.

Sometimes you already know that the file was loaded earlier, then you can use the library search:

Upload::make('upload')
    ->media();

It will add a new button with a modal window to preview uploaded files.

Group

A group is used to combine several fields on one line.

Group::make([
    Input::make('first_name'),
    Input::make('last_name'),
]),

In order to determine the width of the fields, you must use one of the proposed methods.

Fields will occupy the entire available screen width.

Group::make([
    // ...
])->fullWidth();

Fields will take up as much space as necessary.

Group::make([
    // ...
])->autoWidth();

Button/Link

In certain cases, you need to add a button to call a modal window, a simple link, or add a button submit the form at the end of the screen. For such cases, there is a Button field. The Button field cannot have any values and is not transmitted when saving. It can be used to call a modal window defined on the screen. And to add a simple link in the form.

An example of using the modal window addNewPayment added earlier to the screen:

ModalToggle::make('Add Payment')
    ->modal('addNewPayment')
    ->icon('wallet');

Linking example:

Link::make('Google It!')
    ->href('http://google.com');


Link::make('Idea')
    ->route('platform.idea');

Example use with method:

Button::make('Google It!')
    ->method('goToGoogle');

Available modifiers:

  • right() – Positioning the element on the right edge of the screen
  • block() – Positioning the element across the entire width of the screen
  • class('class-names') – rewrites the standard button classes
  • method('methodName') – when clicked, the form will be sent to the specified method within the current screen
  • icon('icon-wallet') – sets an icon for the button

Dropdown

You can easily create a DropDown action button combining all other actions. For example, you can create the typical three dots dropdown:

DropDown::make()
    ->icon('options-vertical')
    ->list([
        Link::make(__('Edit'))
            ->route('platform.users.edit', $user->id)
            ->icon('pencil'),
        Button::make(__('Delete'))
            ->method('remove')
            ->icon('trash')
            ->confirm(__('Are you sure you want to delete the user?'))
            ->parameters([
                'id' => $user->id,
            ]),
    ]);

NumberRange

You can create ranges of numbers. Especially usefull for filters.

NumberRange::make();

Usage with filters:

TD::make()->filter(NumberRange::make());
//or
TD::make()->filter(TD::FILTER_NUMBER_RANGE);

Result is an array with keys of min, max.

And one more thing.

Discussion Blog Donation

GitHub Telegram Twitter Discord

English / Russian