Agile UI

A Seed is a shorthand syntax (using strings or arrays) used to represent an object before it is actually instantiated. Instead of manually creating an object instance, you provide a seed that Agile UI uses to dynamically locate and load the correct class only when it is needed.

Advantages of using Seeds:

• Readability: Shorter and cleaner syntax.
• Performance: Objects are only initialized when required.
• Recursive Injection: Allows for nested property and constructor argument injection.
• Flexibility: Can be namespace-specific and allows application logic to enhance mechanics.

// Manual object creation
$icon = new Icon('book');
$button = new Button('Hello');
$button->icon = $icon;

// Using a Seed (string/array) instead of an object
$button = new Button('Hello');
$button->icon = 'book';

In Agile UI, a "Theme" is a conceptual package that provides three main components to change the application's appearance and structure:

1. Custom CSS: A build based on Fomantic-UI.
2. Custom Layout(s): Unique layout implementations accompanied by documentation.
3. Views: Additional or tweaked View components.

Custom layouts can serve as stand-in replacements for standard layouts or as entirely new structural patterns.

Agile UI provides a bridge between PHP and JavaScript, allowing you to generate and execute client-side events and actions directly from your PHP Views. Instead of writing raw JavaScript logic in PHP, you should use Agile UI to bind generic JavaScript routines (like jQuery) to your UI components via actions and events.

Basic integration example:

$b = new Button();
$b->js('click')->hide();

When using an array as a seed, the structure determines how the object is constructed and how properties are assigned:

1. Index 0: The class name (mapped to the \Atk4\Ui namespace by default).
2. Numeric Indexes: Values passed as arguments to the object's constructor.
3. Named Arguments (String keys): Values assigned to object properties after the constructor has been called.

Example of a complex seed:

$seed = [
    Button::class,           // Class name
    'hello',                 // Constructor argument 1
    'class.big red' => true, // Property assignment
    'icon' => ['book', 'red'] // Recursive seed for a property
];

$seed = [Button::class, 'hello', 'class.big red' => true, 'icon' => ['book', 'red']];

While the Columns class supports some responsiveness, for complex layouts requiring fine-grained control over CSS classes, it is recommended to create your own custom component templates.

For displaying large amounts of data, use the Lister class with a custom template instead of using Columns to ensure better performance.

The Atk4\Ui\Crud class extends the Grid class to provide a complete interface for managing records. It automatically handles adding, updating, deleting, and reading records by linking them to Model actions.

When to use Crud vs other components:

• Use Crud when you need a full interactive interface (Add/Edit/Delete/Read).
• Use Grid if you need a data grid with custom actions that are not the standard CRUD operations, or if you want to use a custom editing mechanism (like a separate page instead of a modal).
• Use Table if you only need to display a non-interactive table of data.

Crud::addTo($app)->setModel(new Country($app->db));

Agile UI distinguishes between how data is formatted and how it is visually enhanced to ensure consistency across the system.

• Data Presentation: Refers to displaying the value of the data in a different format (e.g., changing decimal separators like 123,123.00 to 123.123,00). Presentation is handled globally by Persistence\Ui to ensure a Form, Table, and custom View all show the same format.
• Data Decoration: Refers to adding visual elements like currency symbols or icons (e.g., a calendar icon for a date picker). Decoration is context-dependent and is performed by helper classes like Form\Control\Calendar or Table\Column\Money. The decorator controls the final output and can choose to use the presentation value or apply its own logic.

Every View has an $app property (provided via \Atk4\Core\AppScopeTrait). The framework automatically passes the App instance to all views in the render tree. This enables Dependency Injection, allowing you to access shared services like loggers or database connections from anywhere within a view.

Example of accessing a service from a view:

$view->getApp()->logger->log('Foo Bar');

ATK UI is part of a larger ecosystem and relies on the following frameworks to function. To build full-featured applications, you should be familiar with the documentation for all three:

• ATK UI: The user interface framework.
• ATK Data: Handles database integration and data modeling.
• ATK Core: The foundational framework for the ecosystem.

For deep technical implementation, refer to the official documentation sites for each component.

Agile UI supports a dynamic syntax called "Seed" to allow for concise component creation and property assignment. This pattern is used with the add() method (and its alias addTo()) and for direct property assignment.

// Using Seed in addTo()
Button::addTo($app, ['Hello']);

// Using Seed for property assignment
$button->icon = 'book';