SelectUpdatable

use Kompo\`SelectUpdatable`;

SelectUpdatable::form('Select tag or create a new one.')
   ->addsRelatedOption(TagForm::class)
   ->addLabel('Add a new tag')

The linked Form to add another option needs to return an associative array with the option's value and label. We may do so in the `completed()` method, for example:

class TagForm extends Form
{
   public $model = Tag::class;

   //This allows the Select to update its options 
   //and set the new value automatically.
   public function completed()
   {
      $this->option = [
         $this->model->id => $this->model->name
      ];
   }

   public function komponents()
   {
      return [
         Input::form("Name"),
         SubmitButton::form("Add tag")
      ];
   }
}

Chainable methods

Preview

SelectUpdatable specific

Method
Parameters
Comment
addsRelatedOption
string $formClassOrRoute
The fully qualified form class or kompo route url.
array|null $ajaxPayload
Additional custom data to add to the request (optional).
Specifies which form to open in the modal. In the first parameter:
- You may either call a Form class directly. Ex: App\Http\Komposers\MyForm::class
- Or call a Route::kompo() that points to the Form Class. Ex: route('my-form').
After submit, the object will be added to the select options (and selected).
addLabel
string $label
The label
Specifies the label of the link that will load the form. Default is 'Add a new option'.
options
array|Collection $options
An associative array the values and labels of the options.
Sets the Select's options.
You may use an associative array directly:
->options([
'key1' => 'value1',
'key2' => 'value2',
...
])

Or Laravel's pluck method :
->options(Tags::pluck('tag_name', 'tag_id'))
optionsFrom
string $keyColumn
The key representing the value of the element saved in the DB.
string|array|Kompo\Card $labelColumns
Can be a simple string, an associative array of strings or Closures or a Card component.
string|null $morphToModel
If MorphTo relation, we need to specify the model because it is unknown in the model's relationship.
A cleaner way, when you are using Eloquent relationships, is to use this method that does the query for you. You need to specify the value/label columns in the parameters. For example:
Select::form('Pick the tags')
->name('tags') //<-- Kompo will know this is the Tag Model
->optionsFrom('tag_id', 'tag_name') //<-- value / label convention

When displaying a CustomLabel, `$labelColumns` accepts an array of strings or Closures:
Select::form('Pick the tags')->name('tags')
->optionsFrom('id', IconText::form([ //<-- using a custom Label component
'text' => 'name', //$tag->name
'icon' => `function`($tag){ return $tag->published ? 'icon-check' : 'icon-edit'; }
]))
morphToModel
string $morphToModel
The morph to model class as stored in the DB.
If dealing with a MorphTo relation, we need to specify the model because it is unknown in the model's relationship.
No need to use this method if already specified with optionsFrom().
searchOptions
integer $minSearchLength
The minimum search length
string $searchMethod
The method to search the options from the AJAX request.
string|null $retrieveMethod
(optional) The method to convert a DB value into an option on display.
You may load the select options from the backend using the user's input.
For that, a new public method in your class is needed to return the matched options.
Note that the requests are debounced.
For example:
public function komponents()
{
return [
//User can search and matched options will be loaded from the backend
Select::form('Users')
->optionsFrom('id','name')
->searchOptions(2, 'searchUsers')
]
}
//A new method is added to the Form class to send the matched options back.
public function searchUsers($search = '') //<-- The search value (can be empty)
{
return Users::where('name', 'LIKE', '%'.$search.'%')
->pluck('name', 'id'); //return an associative array.
}

If the `$searchMethod` parameter is left blank, the default method will be 'search{ucfirst(field_name)}'.
For example, for a field name of users, you may directly declare a searchUsers method in your Form Class to return the options.
optionsFromField
string $otherFieldName
The other field's name.
string|null $searchMethod
The public method name
string $retrieveMethod
The method to convert a DB value into an option on display.
You may load the select options from the backend using another field's value.
For that, a new public method in your class is needed to return the new options.
For example:
public function komponents()
{
return [
Select::form('Category')
->optionsFrom('category_id', 'category_name'),
//Tags options will load by Ajax when a category changes
Select::form('Tags')
->optionsFromField('category', 'getTags')
]
}
//A new method is added to the Form class to send the new options back.
public function getTags($value) //<-- the selected category's value.
{
return Tags::where('category_id', $value)
->pluck('tag_name', 'tag_id'); //return an associative array.
}

If the `$searchMethod` parameter is left blank, the default method will be 'search{ucfirst(field_name)}'.
For example, for a field name of first_name, you may directly declare a searchFirstName method in your Form Class to return the options.

Field specific

Method
Parameters
Comment
name
string|array $name
The name attribute of the field.
Sets the name for the field corresponding the attribute it will fill.
placeholder
string $placeholder
The placeholder for the field.
Sets the placeholder of this field.
By default, the fields have no placeholder.
value
string|array $value
The value to be set.
Sets the value of the field for the output (display) phase.
Note: if the Form is connected to an Eloquent Model, the DB value takes precedence.
default
string $defaultValue
The default value
Sets a default value to the field. Applies if the value is empty.
sluggable
string|null $slugColumn
The name of the column that contains the slug
Adds a slug in the table from this field. For example, this will populate the `title` column with the field's value and the `slug` column with it's corresponding slug.
Input::form('Title')->sluggable('slug')
readOnly
none
Makes the field readonly (not editable).
noAutocomplete
none
Removes the browser's default autocomplete behavior from the field.

Input Validation

Method
Parameters
Comment
rules
string|array $rules
A | separated string of validation rules or Array of rules.
Appends Laravel input validation rules for the field.
required
string|null The
required indicator Html. The default is (*).
Sets a required (*) indicator and adds a required validation rule to the field.

Html attributes

Method
Parameters
Comment
id
string $id
The id attribute.
Sets the id attribute of the element.
class
string $classes
The class attribute.
Sets the class attribute of the element.
For multiple classes, use a space-separated string.
replaceClass
string $classes
Adds classes to the element. TODO: replace with overwriteClass or smth...
removeClass
string $classes
Removes a class or space separated classes from the element.
style
string $styles
The CSS style attribute.
Sets the style attribute of the element.
For multiple styles, use a ";" separated string.
attr
array $attributes
Associative array of attribute names and values.
Sets HTML attributes to the element. For example:
->attr([
'title' => 'Some title',
'data-target' => '#target-id'
])
title
string $title
The HTML title attribute
Sets the HTML title attribute of the element.
inputClass
string $classes
The class attribute.
Sets the class attribute for the input element of the field.
For multiple classes, use a space-separated string.
inputStyle
string $style
The CSS style attribute.
Sets the style attribute for the input element of the field.
For multiple styles, use a ";" separated string.
noMargins
none
Removes the default margin applied to fields.
To disable ALL the fields in a form, use the $noMargins property on the Form.

Label, icons & comments

Method
Parameters
Comment
label
string $label
Overwrite the initially set label.
icon
string $iconString
This is the icon HTML or icon class in <i class="..."></i>
Adds an icon before component's label.
rIcon
string $iconString
This is the icon HTML or icon class in <i class="..."></i>
Adds an icon after component's label.
noLabel
none
This will remove the label.
labelClass
string $labelClass
The label's space separated class attribute.
Sets the class attribute of the elements' label.
For multiple classes, use a space-separated string.
comment
string $comment
The comment. Can be an HTML string too.
Adds a comment below the field. This is additional information to complement the label of the input.
hint
string $hint
The information text that displays on hover.
Adds a help text next to the label that appears on hover. By default, a question mark icon is used.
hintIcon
string $iconClassOrHtml
This is the icon HTML or class in <i class="..."></i>
Sets the hint text's icon or class icon. By default, it is the built-in question mark icon.
hintPlacement
string $infoPlacement
Accepted values are top, bottom, left, right
Sets where the hint text's will show on hover. By default, it displays on top.

AJAX HTTP

Method
Parameters
Comment
get
string $route
The route name or uri.
array|null $parameters
The route parameters (optional).
array|null $ajaxPayload
Additional custom data to add to the request (optional).
Performs a GET request to a route in your application.
post
string $route
The route name or uri.
array|null $parameters
The route parameters (optional).
array|null $ajaxPayload
Additional custom data to add to the request (optional).
Performs a POST request to a route in your application.
put
string $route
The route name or uri.
array|null $parameters
The route parameters (optional).
array|null $ajaxPayload
Additional custom data to add to the request (optional).
Performs a PUT request to a route in your application.
delete
string $route
The route name or uri.
array|null $parameters
The route parameters (optional).
array|null $ajaxPayload
Additional custom data to add to the request (optional).
Performs a DELETE request to a route in your application.
selfGet
string $methodName
The class's method name that will return the new komponents.
array|null $ajaxPayload
Additional custom data to add to the request (optional).
Loads a view with a GET ajax request.
To display the view in a container, you may chain it with the methods `inModal` or `inPanel`. For example:
->getView('get-route-of-view')->inModal()
selfPost
string $methodName
The class's method name that will return the new komponents.
array|null $ajaxPayload
Additional custom data to add to the request (optional).
Loads a view with a POST ajax request.
To display the view in a container, you may chain it with the methods `inModal` or `inPanel`. For example:
->postView('get-route-of-view')->inModal()
selfPut
string $methodName
The class's method name that will return the new komponents.
array|null $ajaxPayload
Additional custom data to add to the request (optional).
Loads a view with a POST ajax request.
To display the view in a container, you may chain it with the methods `inModal` or `inPanel`. For example:
->postView('get-route-of-view')->inModal()
selfDelete
string $methodName
The class's method name that will return the new komponents.
array|null $ajaxPayload
Additional custom data to add to the request (optional).
Loads a view with a POST ajax request.
To display the view in a container, you may chain it with the methods `inModal` or `inPanel`. For example:
->postView('get-route-of-view')->inModal()

Special AJAX

Method
Parameters
Comment
getKomposer
string $methodName
The method name that will return a view or HTML response.
array|null $ajaxPayload
Additional custom data to add to the request (optional).
Loads a fresh Komposer class from the server.
To display the new Komposer, you need to chain a method `inModal` or `inPanel`.
You may also pass it additional data in the $payload argument. This data will be injected in the Komposer's store.
Note that the new Komposer will be separate from the parent Komposer where this call is made. If you wanted to include the Komponents as part of the parent, use `getKomponents()` instead.
For example:
->getKomposer(PostForm::class, ['payload' => 'some-data'])->inModal()
getKomponents
string $methodName
The class's method name that will return the new komponents.
array|null $ajaxPayload
Additional custom data to add to the request (optional).
Includes additional komponents from the server. If they contain Fields, they will be included in the Form data and handled in an Eloquent Form.
To display the new Komponents, you need to chain a method `inModal` or `inPanel`. For example:
->getKomponents('newKomponentsMethod')->inPanel('panel-id')
getView
string $viewPath
The view path as in the view() helper.
array|null $ajaxPayload
Additional custom data to include in the view (optional).
Loads a backend Blade view from the server.
To display the view in a container, you may chain it with the methods `inModal` or `inPanel`.
You may also pass it additional data in the $payload argument. This data will be available with the request() helper.
For example:
->loadView('route-of-view')->inModal()
refresh
null|string|array $komposerIds
The id of the Komposer(s). Keep blank if targeting self.
Refreshes the Komposer(s) by reloading a fresh new version from the backend.
If the argument is left blank, the Komposer will refresh itself. To target another Komposer, add a string or array of target Komposer ids.
getFreshForm
none
Reloads a new empty Form. Useful when chained after a submit() to add another item.
redirect
string $route
The route name or uri.
array|null $parameters
The route parameters (optional).
Redirects to the route/uri if the AJAX request was a success.

Modal, Panels & Alerts

Method
Parameters
Comment
inModal
string|null $modalName
The modal name (optional)
Whatever is loaded by AJAX will be displayed in a modal.
If the modalName is left blank, the default modal will be used.
Otherwise, you have to declare a `<vl-modal>` with the desired name.
warnBeforeClose
string|null $message
Shows a warning message that the user needs to confirm before closing the editing modal.
If message is left empty, it defaults to "Any unsaved changes will be lost. Are you sure you want to close this window?".
keepModalOpen
none
Keeps the modal open after a form submit.
inPanel
string $panelId
The panel id attribute
Whatever is loaded by AJAX will be displayed in the panel with the specified id.
You need to add a `Panel` component to your Form or Query. For example:
Button::form('Click')->loadsView('view-route')->inPanel('panel-id'),
Panel::form('panel-id')
alert
string $message
The message to be displayed
string|boolean|null $icon
An optional icon class. Default is "icon-check".
string|null $alertClass
The class for the alert box. Default is "vlAlertSuccess" (green background).
Displays a Bootstrap-style alert message.
By default, a "check" icon is shown but you may override it by setting your own icon class, or disable it by setting it to false.
You may also add an class to the whole box with the alertClass parameter.
inAlert
string|boolean|null $icon
An optional icon class. Default is "icon-check".
string|null $alertClass
The class for the alert box. Default is "vlAlertSuccess" (green background).
Displays a Bootstrap-style alert message after an AJAX request, using the response from the request as the message.

Form submission

Method
Parameters
Comment
submit
string $methodName
The class's method name that will handle the submit.
Submits the form. By default, it will submit to the handle method. The default trigger is:
On click for Buttons/Links.
On change for fields (after blur).
dontSubmitOnEnter
none
Cancel default behavior of certain komponents submitting on Enter key release.
hideIndicators
none
Hides the submission indicators (spinner, success, error).
displayNone
none
Hides the field or element on the Front-end with Vue's v-if.

Catalog actions

Method
Parameters
Comment
filter
string|null $operator
Pick one of these supported operators `=`, `>`, `<`, `>=`, `<=`, `LIKE`, `STARTSWITH`, `ENDSWITH`, `BETWEEN`, `IN`.
Or keep blank to fallback to the field's default operator.
Filters a Query `onChange` for a Field or `onInput` for a text Input field by default.
If these default triggers do not suit you, use another one, for example: ->onBlur->filter('>=')
browse
string|null $queryId
The target Query Id or
integer|null $page
The page
Reload the cards of one or many Query(ies). If $queryId is left blank, it will browse cards of it's parent query.
Otherwise, you may set a string or an array of query ids to refresh.
sort
string|null $sortOrders
If field, the value will determine the sort. If trigger (link or th), we need to add a pipe serapated string of column:direction for ordering.
Triggers a sort event of the query. The parameter is a pipe separated string of column:direction. Example: updated_at:DESC|last_name|first_name:ASC.

Front-end actions

Method
Parameters
Comment
toggleId
string $id
The id of the element to be toggled.
boolean|null $toggleOnLoad
Whether the item should be toggled on inital load. Default is true.
Toggles another item identified by the $id. By default, the target item is hidden on load.
hideSelf
none
The Komponent will hide itself after an interaction.

Vue events

Method
Parameters
Comment
emit
string $event
The event name
array|null $data
The optional additional data
Emits a Vue event to the parent Komposer.
You may add an optional payload as the event's first parameter.
emitDirect
string $event
The event name
array|null $data
The optional additional data
Emits a regular Vue event to it's parent Komponent. This is useful for custom Komponents.
You may add an optional payload as the event's first parameter.

Layout grids

Method
Parameters
Comment
col
string $col
The col attribute. Ex: `col-8`.
Sets a specific col value when the element is used inside `Columns`. By default, the columns get equal widths. A 12 column grid system is used here (same as Bootstrap CSS). For example:
Columns::form(
Html::form('Column 1')->col('col-8'),
Html::form('Column 2')->col('col-4')
)

Testing TDD

Method
Parameters
Comment
dusk
array $selector
Dusk selector attribute.
Sets a dusk selector attribute to the element.

Customization

Method
Parameters
Comment
data
array $data
Key/value associative array.
Pass additional data to the element that can be accessed from the Front-end in the `data` property of the object - especially useful if you wish to customize or add new features to the component.

Eloquent specific

Method
Parameters
Comment
ignoresModel
none
Removes a specific field from the database interaction process.
doesNotFill
none
Has a value but it is not persisted in DB.
extraAttributes
array $attributes
Constant columns/values pairs (associative array).
This specifies extra attributes (constant columns/values) to add to the model.