Ui Awesome

https://github.com/yii2-framework/ui-awesome
Admin
Ui Awesome is a Yii2 framework extension that builds beautiful, accessible HTML and forms with a...
Tokens:6,184
Snippets:22
Trust Score:3.7
License:BSD-3-Clause
Update:10 months ago
Show doc for...
Tokens:
Raw
### Install Ui Awesome Extension (Bash)

Source: https://github.com/yii2-framework/ui-awesome/blob/main/README.md

This snippet shows the Composer command to install the Ui Awesome extension for Yii2. It assumes you have Composer installed and are running the command in your project's root directory.

```bash
composer require github_username/github_repository-name
```

--------------------------------

### Manage Language and Accessibility Attributes in Yii2 UI

Source: https://context7.com/yii2-framework/ui-awesome/llms.txt

Provides built-in support for internationalization (language) and accessibility (ARIA, role, tabindex) attributes, following WCAG standards. Examples show setting language and complex ARIA attributes.

```php
use yii\ui\html\flow\Div;

// Language attribute
$div = Div::tag()
    ->lang('es')
    ->content('Hola Mundo')
    ->render();
// Output: <div lang="es">
// Hola Mundo
// </div>

// Combined accessibility attributes
$button = Div::tag()
    ->id('dialog-close')
    ->attributes([
        'role' => 'button',
        'aria' => [
            'label' => 'Close dialog',
            'pressed' => 'false'
        ],
        'tabindex' => 0
    ])
    ->content('✕')
    ->render();
// Output: <div id="dialog-close" role="button" tabindex="0" aria-label="Close dialog" aria-pressed="false">
// ✕
// </div>

// Hidden elements for screen readers
$div = Div::tag()
    ->attributes(['aria' => ['hidden' => 'true']])
    ->content('Decorative content')
    ->render();
```

--------------------------------

### Configure Tag Instances with Defaults in Yii2 UI

Source: https://context7.com/yii2-framework/ui-awesome/llms.txt

Demonstrates how to instantiate HTML tags with default configurations that merge with global factory defaults using Yii2 UI. Shows overriding global defaults with instance-specific settings.

```php
use yii\ui\html\flow\Div;
use yii\ui\factory\SimpleFactory;

// Set global defaults
SimpleFactory::setDefaults(Div::class, [
    'class' => 'global-class',
    'data' => ['source' => 'global']
]);

// Pass defaults during instantiation
$div = Div::tag([
    'id' => 'instance-id',
    'class' => 'instance-class',
    'title' => 'Instance title'
])->render();
// User defaults override global defaults for class
// Output: <div class="instance-class" id="instance-id" title="Instance title" data-source="global">
// </div>

// Combine instance defaults with method calls
$div = Div::tag(['class' => 'base'])
    ->id('custom')
    ->content('Hello')
    ->render();
// Output: <div class="base" id="custom">
// Hello
// </div>

// Instance defaults with nested structures
$div = Div::tag([
    'data' => ['level' => 1],
    'style' => ['color' => 'blue']
])
->dataAttributes(['extra' => 'value'])
->render();

// Clean up
SimpleFactory::setDefaults(Div::class, []);
```

--------------------------------

### Begin/End Tag Pairs for Nested Content

Source: https://context7.com/yii2-framework/ui-awesome/llms.txt

The `Html::begin()` and `Html::end()` methods facilitate the progressive generation of HTML, allowing for complex nested structures like divs, sections, lists, and even complete HTML documents.

```APIDOC
## POST /yii2-framework/ui-awesome/html::beginEnd

### Description
Enables progressive HTML generation for complex nested structures by opening and closing HTML tags.

### Method
POST (or conceptually, static method calls in PHP)

### Endpoint
Not applicable for static methods, but represents the functions `yii\ui\html\Html::begin()` and `yii\ui\html\Html::end()`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None (These are static method calls).

**Method Signatures:**
`Html::begin(string $tag, array $attributes = []): string`
`Html::end(string $tag): string`

- **tag** (string) - Required - The HTML tag name or a constant representing the tag type (e.g., `Block::DIV`, `Lists::UL`).
- **attributes** (array) - Optional (for `begin()`) - An associative array of HTML attributes for the opening tag.

### Request Example
```php
use yii\ui\html\Html;
use yii\ui\tag\Block;
use yii\ui\tag\Lists;

// Create nested block elements
echo Html::begin(Block::DIV, ['class' => 'container']);
echo Html::begin(Block::SECTION, ['id' => 'main']);
echo 'Content here';
echo Html::end(Block::SECTION);
echo Html::end(Block::DIV);

// Build lists dynamically
echo Html::begin(Lists::UL, ['class' => 'menu']);
foreach (['Home', 'About', 'Contact'] as $item) {
    echo Html::begin(Lists::LI);
    echo $item;
    echo Html::end(Lists::LI);
}
echo Html::end(Lists::UL);
```

### Response
#### Success Response (200)
- **string** (string) - The rendered HTML string representing the opening or closing tag.

#### Response Example
```html
<div class="container">
<section id="main">
Content here
</section>
</div>

<ul class="menu">
<li>
Home
</li>
<li>
About
</li>
<li>
Contact
</li>
</ul>
```
```

--------------------------------

### Building HTML Elements with Fluent Tag Classes (PHP)

Source: https://context7.com/yii2-framework/ui-awesome/llms.txt

Demonstrates how to use object-oriented tag classes in PHP to create HTML elements with fluent interfaces. Supports chaining attribute methods, using begin/end for structural tags, and nesting elements. Immutability is a key feature, ensuring configurations are not altered after creation.

```php
use yii\ui\html\flow\Div;
use yii\ui\html\phrasing\Span;

// Create a div with fluent methods
$div = Div::tag()
    ->class('container')
    ->id('main')
    ->content('Hello World')
    ->render();
// Output: <div class="container" id="main">
Hello World
</div>

// Chain multiple attribute methods
$styledDiv = Div::tag()
    ->class('card')
    ->style('padding: 20px; margin: 10px;')
    ->dataAttributes(['role' => 'panel', 'id' => 123])
    ->title('Information Card')
    ->content('<p>Card content</p>')
    ->render();
// Output: <div class="card" title="Information Card" data-role="panel" data-id="123" style="padding: 20px; margin: 10px;">
<p>Card content</p>
</div>

// Use begin/end with tag objects
echo Div::tag()->class('wrapper')->begin();
echo Span::tag()->content('Inner content')->render();
echo 'More content';
echo Div::end();
// Output: <div class="wrapper">
<span>Inner content</span>
More content
</div>

// Nested tag objects with immutability
$inner = Span::tag()->class('highlight')->content('Important');
$outer = Div::tag()
    ->class('container')
    ->content($inner->render())
    ->render();
```

--------------------------------

### Factory Pattern for Global Defaults and Tag Instantiation (PHP)

Source: https://context7.com/yii2-framework/ui-awesome/llms.txt

Illustrates the `SimpleFactory` class in PHP for managing global configurations and instantiating tags. It allows setting default attributes for tag classes, which are inherited by new instances. User-provided attributes can override these defaults. The factory also supports dynamic configuration of tag instances.

```php
use yii\ui\factory\SimpleFactory;
use yii\ui\html\flow\Div;

// Set global defaults for a tag class
SimpleFactory::setDefaults(Div::class, [
    'class' => 'default-container',
    'data' => ['component' => 'ui']
]);

// All new instances inherit defaults
$div1 = Div::tag()->render();
// Output: <div class="default-container" data-component="ui">
</div>

$div2 = Div::tag()->id('custom')->render();
// Output: <div class="default-container" id="custom" data-component="ui">
</div>

// User attributes override global defaults
$div3 = Div::tag(['class' => 'override'])->render();
// Output: <div class="override" data-component="ui">
</div>

// Retrieve current defaults
$defaults = SimpleFactory::getDefaults(Div::class);
// Returns: ['class' => 'default-container', 'data' => ['component' => 'ui']]

// Configure a tag instance dynamically
$configured = SimpleFactory::configure(
    Div::tag(),
    [
        'id' => 'dynamic',
        'class' => ['card', 'shadow'],
        'content' => 'Dynamic content'
    ]
);
echo $configured->render();
// Output: <div class="card shadow" id="dynamic">
Dynamic content
</div>

// Clear defaults
SimpleFactory::setDefaults(Div::class, []);
```

--------------------------------

### Static HTML Element Rendering

Source: https://context7.com/yii2-framework/ui-awesome/llms.txt

The `Html::element()` method allows for quick rendering of any HTML element, supporting automatic content encoding and attribute processing for security and flexibility.

```APIDOC
## POST /yii2-framework/ui-awesome/html::element

### Description
Renders any HTML element with automatic content encoding and attribute processing.

### Method
POST (or conceptually, a static method call in PHP)

### Endpoint
Not applicable for static methods, but represents the function `yii\ui\html\Html::element()`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None (This is a static method call, parameters are passed directly to the method).

**Method Signature:**
`Html::element(string $tag, string $content = '', array $attributes = [], bool $encode = false): string`

- **tag** (string) - Required - The HTML tag name or a constant representing the tag type (e.g., `Block::DIV`).
- **content** (string) - Optional - The content of the HTML element. Defaults to an empty string.
- **attributes** (array) - Optional - An associative array of HTML attributes for the element. Can include class names as arrays, data attributes, and ARIA attributes. Defaults to an empty array.
- **encode** (bool) - Optional - Whether to encode the content to prevent XSS attacks. Defaults to `false`.

### Request Example
```php
use yii\ui\html\Html;
use yii\ui\tag\Block;

// Render a div with raw HTML content
$html = Html::element(Block::DIV, '<span>Test Content</span>', ['class' => 'test-class']);

// Render with encoded content for security
$html = Html::element(Block::DIV, '<script>alert("XSS")</script>', ['class' => 'safe'], true);
```

### Response
#### Success Response (200)
- **string** (string) - The rendered HTML string.

#### Response Example
```html
<div class="test-class">
<span>Test Content</span>
</div>

<div class="safe">
&lt;script&gt;alert(&quot;XSS&quot;)&lt;/script&gt;
</div>
```
```

--------------------------------

### Begin/End Tag Pairs for Nested HTML with Yii2 UI Awesome

Source: https://context7.com/yii2-framework/ui-awesome/llms.txt

Enables progressive HTML generation for complex nested structures using begin and end tag methods. Ideal for building dynamic forms, lists, and complete HTML documents.

```php
use yii\ui\html\Html;
use yii\ui\tag\Block;
use yii\ui\tag\Lists;
use yii\ui\tag\Table;
use yii\ui\tag\Root;

// Create nested block elements
echo Html::begin(Block::DIV, ['class' => 'container']);
echo Html::begin(Block::SECTION, ['id' => 'main']);
echo 'Content here';
echo Html::end(Block::SECTION);
echo Html::end(Block::DIV);
// Output: <div class="container">
<section id="main">
Content here
</section>
</div>

// Build lists dynamically
echo Html::begin(Lists::UL, ['class' => 'menu']);
foreach (['Home', 'About', 'Contact'] as $item) {
    echo Html::begin(Lists::LI);
    echo $item;
    echo Html::end(Lists::LI);
}
echo Html::end(Lists::UL);

// Create complete HTML documents
echo Html::begin(Root::HTML, ['lang' => 'en']);
echo Html::begin(Root::HEAD);
echo '<title>Page Title</title>';
echo Html::end(Root::HEAD);
echo Html::begin(Root::BODY);
echo 'Body content';
echo Html::end(Root::BODY);
echo Html::end(Root::HTML);
```

--------------------------------

### Inline Element Rendering with Yii2 UI Awesome

Source: https://context7.com/yii2-framework/ui-awesome/llms.txt

Optimizes rendering for inline-level HTML elements without adding line breaks. Supports content encoding for security and allows for multiple attributes.

```php
use yii\ui\html\Html;
use yii\ui\tag\Inline;

// Render inline elements without encoding
$link = Html::inline(Inline::A, 'Click Here', ['href' => '/page', 'class' => 'btn']);
// Output: <a class="btn" href="/page">Click Here</a>

// Render with content encoding
$code = Html::inline(Inline::CODE, '<script>', ['class' => 'highlight'], true);
// Output: <code class="highlight">&lt;script&gt;</code>

// Complex inline element with multiple attributes
$span = Html::inline(Inline::SPAN, 'Important', [
    'id' => 'notice',
    'class' => ['text-red', 'font-bold'],
    'data' => ['priority' => 'high'],
    'title' => 'Please review'
]);
// Output: <span class="text-red font-bold" id="notice" title="Please review" data-priority="high">Important</span>
```

--------------------------------

### Static HTML Element Rendering with Yii2 UI Awesome

Source: https://context7.com/yii2-framework/ui-awesome/llms.txt

Renders any HTML element using static methods, including automatic content encoding for security. Supports block, inline, and void elements with attribute processing. Useful for quick generation of HTML snippets.

```php
use yii\ui\html\Html;
use yii\ui\tag\Block;
use yii\ui\tag\Inline;
use yii\ui\tag\Voids;

// Render a div with raw HTML content
$html = Html::element(Block::DIV, '<span>Test Content</span>', ['class' => 'test-class']);
// Output: <div class="test-class">
<span>Test Content</span>
</div>

// Render with encoded content for security
$html = Html::element(Block::DIV, '<script>alert("XSS")</script>', ['class' => 'safe'], true);
// Output: <div class="safe">
&lt;script&gt;alert(&quot;XSS&quot;)&lt;/script&gt;
</div>

// Render inline elements
$span = Html::element(Inline::SPAN, 'inline content', ['id' => 'inline']);
// Output: <span id="inline">inline content</span>

// Render void elements (self-closing tags)
$img = Html::element(Voids::IMG, '', [
    'class' => ['profile', 'rounded'],
    'data' => ['role' => 'avatar', 'id' => 42]
]);
// Output: <img class="profile rounded" data-role="avatar" data-id="42">
```

--------------------------------

### Inline Element Rendering

Source: https://context7.com/yii2-framework/ui-awesome/llms.txt

The `Html::inline()` method is optimized for rendering inline-level HTML elements without introducing unwanted line breaks. It supports content encoding for security.

```APIDOC
## POST /yii2-framework/ui-awesome/html::inline

### Description
Optimizes rendering for inline-level elements without line breaks, with optional content encoding.

### Method
POST (or conceptually, a static method call in PHP)

### Endpoint
Not applicable for static methods, but represents the function `yii\ui\html\Html::inline()`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None (This is a static method call).

**Method Signature:**
`Html::inline(string $tag, string $content = '', array $attributes = [], bool $encode = false): string`

- **tag** (string) - Required - The HTML tag name or a constant representing the inline tag type (e.g., `Inline::SPAN`, `Inline::CODE`).
- **content** (string) - Optional - The content of the inline element. Defaults to an empty string.
- **attributes** (array) - Optional - An associative array of HTML attributes for the element.
- **encode** (bool) - Optional - Whether to encode the content for security. Defaults to `false`.

### Request Example
```php
use yii\ui\html\Html;
use yii\ui\tag\Inline;

// Render inline elements without encoding
$link = Html::inline(Inline::A, 'Click Here', ['href' => '/page', 'class' => 'btn']);

// Render with content encoding
$code = Html::inline(Inline::CODE, '<script>', ['class' => 'highlight'], true);

// Complex inline element with multiple attributes
$span = Html::inline(Inline::SPAN, 'Important', [
    'id' => 'notice',
    'class' => ['text-red', 'font-bold'],
    'data' => ['priority' => 'high'],
    'title' => 'Please review'
]);
```

### Response
#### Success Response (200)
- **string** (string) - The rendered inline HTML string.

#### Response Example
```html
<a class="btn" href="/page">Click Here</a>

<code class="highlight">&lt;script&gt;</code>

<span class="text-red font-bold" id="notice" title="Please review" data-priority="high">Important</span>
```
```

--------------------------------

### Void Element Rendering with Yii2 UI Awesome

Source: https://context7.com/yii2-framework/ui-awesome/llms.txt

Handles self-closing HTML elements like img, input, br, and hr. Supports multiple attributes for customization.

```php
use yii\ui\html\Html;
use yii\ui\tag\Voids;

// Render an image with multiple attributes
$img = Html::void(Voids::IMG, [
    'src' => '/images/photo.jpg',
    'alt' => 'Profile Photo',
    'class' => ['rounded', 'shadow'],
    'width' => 200,
    'height' => 200
]);
// Output: <img class="rounded shadow" src="/images/photo.jpg" alt="Profile Photo" width="200" height="200">

// Form inputs
$input = Html::void(Voids::INPUT, [
    'type' => 'text',
    'name' => 'username',
    'class' => 'form-control',
    'required' => true,
    'placeholder' => 'Enter username'
]);
// Output: <input class="form-control" name="username" type="text" required placeholder="Enter username">

// Line breaks and horizontal rules
$br = Html::void(Voids::BR);
$hr = Html::void(Voids::HR, ['class' => 'divider']);
```

--------------------------------

### Void Element Rendering

Source: https://context7.com/yii2-framework/ui-awesome/llms.txt

The `Html::void()` method is specifically designed for rendering void (self-closing) HTML elements such as `img`, `input`, `br`, and `hr`, supporting all necessary attributes.

```APIDOC
## POST /yii2-framework/ui-awesome/html::void

### Description
Handles rendering for void (self-closing) HTML elements like `img`, `input`, `br`, and `hr`.

### Method
POST (or conceptually, a static method call in PHP)

### Endpoint
Not applicable for static methods, but represents the function `yii\ui\html\Html::void()`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None (This is a static method call).

**Method Signature:**
`Html::void(string $tag, array $attributes = []): string`

- **tag** (string) - Required - The HTML tag name or a constant representing the void tag type (e.g., `Voids::IMG`, `Voids::INPUT`).
- **attributes** (array) - Optional - An associative array of HTML attributes for the void element.

### Request Example
```php
use yii\ui\html\Html;
use yii\ui\tag\Voids;

// Render an image with multiple attributes
$img = Html::void(Voids::IMG, [
    'src' => '/images/photo.jpg',
    'alt' => 'Profile Photo',
    'class' => ['rounded', 'shadow'],
    'width' => 200,
    'height' => 200
]);

// Form inputs
$input = Html::void(Voids::INPUT, [
    'type' => 'text',
    'name' => 'username',
    'class' => 'form-control',
    'required' => true,
    'placeholder' => 'Enter username'
]);

// Line breaks and horizontal rules
$br = Html::void(Voids::BR);
$hr = Html::void(Voids::HR, ['class' => 'divider']);
```

### Response
#### Success Response (200)
- **string** (string) - The rendered void HTML string.

#### Response Example
```html
<img class="rounded shadow" src="/images/photo.jpg" alt="Profile Photo" width="200" height="200">

<input class="form-control" name="username" type="text" required placeholder="Enter username">

<br>
<hr class="divider">
```
```

--------------------------------

### Manage CSS Classes with Yii2 UI HTML Flow

Source: https://context7.com/yii2-framework/ui-awesome/llms.txt

Utilities for adding, merging, overriding, removing, and managing CSS classes on HTML elements using the Yii2 UI HTML Flow component. Supports single classes, multiple classes, and array-based class definitions.

```php
use yii\ui\html\flow\Div;

// Add single class
$div = Div::tag()->class('container')->render();
// Output: <div class="container">
// </div>

// Add multiple classes
$div = Div::tag()
    ->class('card')
    ->class('shadow')
    ->class('rounded')
    ->render();

// Override with new class (second parameter true)
$div = Div::tag()
    ->class('old-class')
    ->class('new-class', true)  // Replaces old-class
    ->render();
// Output: <div class="new-class">
// </div>

// Remove class by setting to null
$div = Div::tag()
    ->class('initial')
    ->class(null)  // Removes class
    ->render();
// Output: <div>
// </div>

// Pass array of classes
$div = Div::tag()
    ->attributes(['class' => ['btn', 'btn-primary', 'btn-lg']])
    ->render();
// Output: <div class="btn btn-primary btn-lg">
// </div>
```

--------------------------------

### Manage Data Attributes with Yii2 UI HTML Flow

Source: https://context7.com/yii2-framework/ui-awesome/llms.txt

System for attaching structured custom data to HTML elements, including support for JSON encoding of complex nested data. Demonstrates simple and complex data attribute management.

```php
use yii\ui\html\flow\Div;

// Simple data attributes
$div = Div::tag()
    ->dataAttributes(['id' => '123', 'type' => 'article'])
    ->render();
// Output: <div data-id="123" data-type="article">
// </div>

// Complex nested data with JSON encoding
$div = Div::tag()
    ->dataAttributes([
        'config' => [
            'autoplay' => true,
            'speed' => 300,
            'slides' => ['image1.jpg', 'image2.jpg']
        ],
        'api-url' => 'https://api.example.com'
    ])
    ->render();
// Output: <div data-api-url="https://api.example.com" data-config='{"autoplay":true,"speed":300,"slides":["image1.jpg","image2.jpg"]}'>
// </div>

// Alternative syntax via attributes
$div = Div::tag()
    ->attributes([
        'data' => [
            'user-id' => 42,
            'role' => 'admin'
        ]
    ])
    ->render();
// Output: <div data-user-id="42" data-role="admin">
// </div>
```

--------------------------------

### Rendering and Encoding HTML Attributes (PHP)

Source: https://context7.com/yii2-framework/ui-awesome/llms.txt

Explains the `Attributes::render()` method in PHP for processing attribute arrays. It handles automatic encoding, sorting, and type conversions for attributes, including basic, data, ARIA, and style attributes. This method is crucial for preventing XSS vulnerabilities.

```php
use yii\ui\helpers\Attributes;

// Basic attribute rendering with automatic ordering
$attrs = Attributes::render([
    'type' => 'text',
    'name' => 'username',
    'class' => ['form-control', 'input-lg'],
    'required' => true
]);
// Output:  class="form-control input-lg" name="username" type="text" required

// Data attributes expansion
$attrs = Attributes::render([
    'class' => 'widget',
    'data' => [
        'role' => 'user',
        'id' => 42,
        'config' => ['theme' => 'dark', 'lang' => 'en']
    ]
]);
// Output:  class="widget" data-role="user" data-id="42" data-config='{"theme":"dark","lang":"en"}'

// ARIA attributes for accessibility
$attrs = Attributes::render([
    'aria' => [
        'label' => 'Close dialog',
        'hidden' => 'false',
        'expanded' => 'true'
    ],
    'role' => 'button'
]);
// Output:  role="button" aria-label="Close dialog" aria-hidden="false" aria-expanded="true"

// Style attribute from array
$attrs = Attributes::render([
    'style' => [
        'color' => 'red',
        'font-size' => '14px',
        'padding' => '10px 20px'
    ]
]);
// Output:  style="color: red; font-size: 14px; padding: 10px 20px;"

// XSS prevention with automatic encoding
$attrs = Attributes::render([
    'title' => '<script>alert("XSS")</script>',
    'data' => ['value' => '"><script>evil()</script>']
]);
// Output:  title="&lt;script&gt;alert(&quot;XSS&quot;)&lt;/script&gt;" data-value="&quot;&gt;&lt;script&gt;evil()&lt;/script&gt;"
```
Tokens:
Raw