Atk4 Hintable Laravel Package

Getting Started

Minimal Steps

1. Install the Package Require the package via Composer in your Laravel project (if using ATK4):

   composer require mvorisek/atk4-hintable
   

   Note: This package is designed for ATK4, not vanilla Laravel. Ensure your project integrates ATK4 (e.g., via atk4/core).

2. First Use Case: Adding a Hint to a Field Extend an ATK4 field (e.g., TextField) with the Hintable trait:

   use Atk4\Hintable\Hintable;
   use Atk4\Ui\Form;
   
   $form = new Form();
   $field = $form->addField('email', ['TextField']);
   $field->addExtension(Hintable::class)->setHint('Enter a valid email address');
   

   Render the form to see the hint appear as a tooltip or inline text.

3. Where to Look First

   • src/Hintable.php: Core logic for hint attachment and rendering.
   • README.md: Basic setup and configuration (e.g., dependency requirements).
   • Tests: Check tests/HintableTest.php for usage examples and edge cases.

Implementation Patterns

Usage Patterns

1. Basic Hint Attachment Attach hints to any ATK4 field (e.g., TextField, DateField):

   $field->addExtension(Hintable::class)
         ->setHint('This field is required');
   

2. Dynamic Hints via Validation Update hints based on field state (e.g., validation errors):

   $field->onValidate(function($field) {
       if (!$field->isFilled()) {
           $field->getExtension(Hintable::class)
                 ->setHint('Please fill this field')
                 ->setHintType('error');
       }
   });
   

3. Bulk Hint Application Apply hints to multiple fields in a loop:

   foreach ($form->getFields() as $field) {
       $field->addExtension(Hintable::class)
             ->setHint('Required format: ' . $field->getName());
   }
   

4. Custom Hint Templates Override the default hint rendering (if the package supports templates):

   $field->getExtension(Hintable::class)
         ->setHintTemplate('<div class="custom-hint">{{hint}}</div>');
   

Workflows

• Form Initialization: Attach hints during form setup (e.g., in a Form constructor).
• Dynamic Updates: Modify hints in real-time (e.g., via AJAX or user interactions).
• Localization: Store hints in language files and switch them dynamically:

  $hint = __("Hint for {field}", ['field' => $field->getName()]);
  $field->getExtension(Hintable::class)->setHint($hint);
  

Integration Tips

• ATK4 Grid Integration: Add hints to grid columns for data clarity:

  $grid->addColumn('status')
       ->addExtension(Hintable::class)
       ->setHint('Pending/Active/Completed');
  

• Accessibility: Ensure hints are screen-reader friendly by adding aria-describedby:

  $field->addExtension(Hintable::class)
        ->setHint('Description for screen readers')
        ->enableAriaSupport();
  

• Performance: Lazy-load hints for complex forms to avoid initial render delays.

Gotchas and Tips

Pitfalls

1. ATK4 Dependency

   • Issue: The package only works with ATK4. If your project uses vanilla Laravel or other frameworks, integration will fail.
   • Fix: Ensure ATK4 is properly installed and configured before using this package.

2. Hint Rendering Conflicts

   • Issue: Hints may not appear if CSS/JS conflicts exist (e.g., duplicate tooltip libraries).
   • Fix: Inspect the browser’s console for errors and override default styles:

     .hintable-tooltip { /* Customize to avoid conflicts */ }
     

3. Dynamic Content in Hints

   • Issue: Hints with dynamic content (e.g., user-specific data) may not update automatically.
   • Fix: Manually refresh hints after data changes:

     $field->getExtension(Hintable::class)->refreshHint();
     

4. Missing Documentation

   • Issue: Limited examples or API docs may require reverse-engineering.
   • Fix: Check the tests/ directory for usage patterns and extend the package as needed.

Debugging Tips

• Verify Extension Attachment Ensure the Hintable extension is properly added:

  if (!$field->hasExtension(Hintable::class)) {
      throw new \RuntimeException('Hintable extension not attached!');
  }
  

• Check Hint Visibility Use browser dev tools to inspect if hints are rendered but hidden (e.g., display: none).
• Log Hint Events Add debug logs to track hint lifecycle:

  $field->getExtension(Hintable::class)->on('hintRendered', function() {
      \Log::debug('Hint rendered for field: ' . $field->getName());
  });
  

Configuration Quirks

• Hint Types The package may support types like info, warning, or error. Test all types to ensure consistent styling:

  $field->getExtension(Hintable::class)->setHintType('warning');
  

• Global Defaults Set default hints for all fields via a base class:

  class BaseField extends \Atk4\Ui\Field {
      public function init() {
          $this->addExtension(Hintable::class)
               ->setHint('Default hint text');
      }
  }
  

Extension Points

1. Custom Hint Triggers Extend the package to support non-hover triggers (e.g., focus or click):

   $field->getExtension(Hintable::class)
         ->setTrigger('click'); // Default is 'hover'
   

2. Hint Storage Store hints in a database or config file for dynamic updates:

   $hint = config("hints.{$field->getName()}");
   $field->getExtension(Hintable::class)->setHint($hint);
   

3. Localization Use Laravel’s localization system to manage multi-language hints:

   $field->getExtension(Hintable::class)
         ->setHint(__('hints.field_name'));