Ui Laravel Package

Getting Started

First Steps

1. Installation Update to the latest version via Composer:

   composer require atk4/ui:^6.0
   

   Require the autoloader in your Laravel app (unchanged):

   require __DIR__.'/../vendor/autoload.php';
   

2. Basic Setup Initialize the UI framework in a Laravel service provider (updated for setEntity):

   public function boot()
   {
       $this->app->singleton('atk4/ui', function ($app) {
           return new \atk4\ui\UI();
       });
   }
   

3. First Use Case: Simple Form Updated to use setEntity() instead of setModel():

   use atk4\ui\UI;
   
   public function showForm(UI $ui)
   {
       $user = new \App\Models\User(); // Eloquent model
       $ui->add('Form')->setEntity($user)->addField('name', 'text');
       $ui->add('Button', 'Submit')->js('this.form.submit()');
   }
   

Implementation Patterns

Core Workflows

1. Component-Based UI Leverage UI::add() with updated methods (e.g., setEntity):

   $ui->add('Grid', $data)->addColumn('name');
   $ui->add('Form')->setEntity($user)->addField('email', 'email')->addButton('Save');
   

2. Data Binding Use setEntity() (replaces setModel()) for Eloquent models:

   $form = $ui->add('Form')->setEntity($user);
   $form->addField('email')->setModelAttribute('email');
   

3. Event Handling Updated onChange() now requires explicit type casting:

   $field = $ui->add('Field', 'name', 'text');
   $field->onChange(function($value) {
       return (string) $value; // Explicit cast
   });
   

4. Templates & Layouts Override templates via setTemplate() (unchanged):

   $ui->setTemplate('my_template');
   

New Features

1. Clearable Dropdowns Enable clearable dropdowns with:

   $ui->add('Dropdown')->setClearable(true);
   

2. Master Checkbox in Grids Add bulk actions with a master checkbox:

   $grid = $ui->add('Grid', $data);
   $grid->addColumn('checkbox', 'select')->setMasterCheckbox();
   

3. Password Field with Reveal Eye Use the built-in toggle for password visibility:

   $ui->add('Field', 'password', 'password')->setRevealEye();
   

4. Teleported Modals Modals now teleport early for smoother UX (no manual intervention required).

Integration with Laravel

• Blade Integration (unchanged):

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

• Asset Management (updated for Fomantic UI 2.10):

  // resources/js/app.js
  import '@atk4/ui/dist/atk4-ui.css';
  import 'fomantic-ui/dist/semantic.min.css';
  

Gotchas and Tips

Breaking Changes

1. setModel() → setEntity() Replace all instances of setModel() with setEntity() for forms/grids:

   // Old:
   $form->setModel($user);
   // New:
   $form->setEntity($user);
   

2. isDisabled → isEnabled Update disabled state logic:

   // Old:
   $button->setDisabled(true);
   // New:
   $button->setEnabled(false);
   

3. Form Control Class Changes Custom form controls must now extend the abstract Form\Control class:

   class MyControl extends \atk4\ui\Form\Control { ... }
   

4. Dropdown Multiple JSON Fix Ensure multi-select dropdowns use valid JSON:

   $dropdown = $ui->add('Dropdown')->setMultiple(true);
   $dropdown->setSource([1, 2, 3]); // Array must be JSON-serializable
   

Common Pitfalls

1. HTML Escaping Dropdowns and toasts now escape HTML by default. Use setHTML() explicitly:

   $dropdown->setHTML('<strong>Custom</strong> HTML');
   

2. Async Handler Cleanup Terminate async JS handlers when components are destroyed to avoid memory leaks:

   $ui->add('Button')->js('fetch("/data").then(...)', [], true); // Auto-cleanup
   

3. Tab Loading Tabs now load content via JSON from the server. Use setSource():

   $tabs = $ui->add('Tabs');
   $tabs->addTab('Data')->setSource('/api/data');
   

4. CSRF Protection Manually add CSRF tokens to forms (unchanged):

   $form->addCSRF();
   

Debugging Tips

• Enable Debug Mode (unchanged):

  $ui->debug(true);
  

• Log Component Hierarchy (unchanged):

  dd($ui->getTree());
  

Extension Points

1. Custom Components Extend Form\Control for new form controls:

   class MyField extends \atk4\ui\Form\Control {
       public function init() { ... }
   }
   

2. Override Templates Place custom templates in resources/views/atk4/ (unchanged):

   $ui->setTemplate('my_form');
   

3. Hooks & Events Use on() with explicit type casting:

   $form->on('afterSave', function($entity) {
       toast((string) $entity->name);
   });
   

4. Laravel Service Container Bind custom configurations (unchanged):

   $this->app->bind('atk4/ui', function ($app) {
       $ui = new \atk4\ui\UI();
       $ui->setConfig(['theme' => 'dark']);
       return $ui;
   });
   

New Features in Depth

1. FilterModel Support for smallint/bigint Add support for numeric filters:

   $filter = $ui->add('FilterModel', $model);
   $filter->add('age', 'integer')->setRange(1, 100);
   

2. Fomantic UI 2.10 Integration Updated styling and components. Test your themes for compatibility.

3. JsCallback Typecasting Use JsCallback for dynamic JS with type safety:

   $ui->js(new \atk4\ui\JsCallback('alert', ['Hello']));