diff --git a/LICENSE.md b/LICENSE.md index bc5674f..6a920d6 100644 --- a/LICENSE.md +++ b/LICENSE.md @@ -1,17 +1,17 @@ -Copyright © 2008 by Yii Software (https://www.yiiframework.com/) +Copyright © 2008 by Yii Software () All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: - * Redistributions of source code must retain the above copyright +* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above copyright +* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. - * Neither the name of Yii Software nor the names of its +* Neither the name of Yii Software nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. diff --git a/README.md b/README.md index ac49b54..16e9b0b 100644 --- a/README.md +++ b/README.md @@ -21,6 +21,10 @@ This [Yii Framework](https://www.yiiframework.com/) package encapsulates [Bulma](https://bulma.io) components and plugins in terms of Yii widgets, and thus makes using Bulma components/plugins in Yii applications convenient. +## Requirements + +- PHP 8.0 or higher. + ## Installation ```shell @@ -31,9 +35,9 @@ composer require yiisoft/yii-bulma --prefer-dist There are several ways to install the assets, they are: -1.- Using the [AssetPackagist](https://asset-packagist.org/) package manager. +1. Using the [AssetPackagist](https://asset-packagist.org/) package manager. -Add to composer.json the following: +Add to composer.json file the following: ```json { @@ -68,7 +72,7 @@ Once the changes are made, you can install the assets using the following comman composer update --prefer-dist ``` -2.- Using the [npm-asset](https://www.npmjs.com/) package manager. +2. Using the [npm-asset](https://www.npmjs.com/) package manager. Run the following command at the root directory of your application. @@ -100,7 +104,6 @@ By registering the Asset in the `resources/layout/main.php` it will be available If you need it registered for individual view (such as `resources/views/site/contact.php`) only, register it in that view. - ```php use Yiisoft\Yii\Bulma\Asset\BulmaAsset; @@ -141,48 +144,27 @@ $this->setCssFiles($assetManager->getCssFiles()); $this->setJsFiles($assetManager->getJsFiles()); ``` -## Widgets usage - -We will quickly and easily describe how to use widgets, and be able to use all the power of -the Bulma CSS framework with PHP: +## Documentation -- [Breadcrumbs](docs/breadcrumbs.md) -- [Dropdown](docs/dropdown.md) -- [Menu](docs/menu.md) -- [Message](docs/message.md) -- [Modal](docs/modal.md) -- [ModalCard](docs/modalcard.md) -- [NavBar](docs/navbar.md) -- [Panel](docs/panel.md) -- [ProgressBar](docs/progressbar.md) -- [Tabs](docs/tabs.md) +- [Guides](docs/guide/README.md) +- [Internals](docs/internals.md) -## Testing +## Support -### Unit testing - -The package is tested with [PHPUnit](https://phpunit.de/). To run tests: - -```shell -./vendor/bin/phpunit -``` +If you need help or have a question, the [Yii Forum](https://forum.yiiframework.com/c/yii-3-0/63) is a good place for that. +You may also check out other [Yii Community Resources](https://www.yiiframework.com/community). -### Mutation testing +## Support the project -The package tests are checked with [Infection](https://infection.github.io/) mutation framework with -[Infection Static Analysis Plugin](https://github.com/Roave/infection-static-analysis-plugin). To run it: - -```shell -./vendor/bin/roave-infection-static-analysis-plugin -``` - -### Static analysis +[![Open Collective](https://img.shields.io/badge/Open%20Collective-sponsor-7eadf1?logo=open%20collective&logoColor=7eadf1&labelColor=555555)](https://opencollective.com/yiisoft) -The code is statically analyzed with [Psalm](https://psalm.dev/). To run static analysis: +## Follow updates -```shell -./vendor/bin/psalm -``` +[![Official website](https://img.shields.io/badge/Powered_by-Yii_Framework-green.svg?style=flat)](https://www.yiiframework.com/) +[![Twitter](https://img.shields.io/badge/twitter-follow-1DA1F2?logo=twitter&logoColor=1DA1F2&labelColor=555555?style=flat)](https://twitter.com/yiiframework) +[![Telegram](https://img.shields.io/badge/telegram-join-1DA1F2?style=flat&logo=telegram)](https://t.me/yii3en) +[![Facebook](https://img.shields.io/badge/facebook-join-1DA1F2?style=flat&logo=facebook&logoColor=ffffff)](https://www.facebook.com/groups/yiitalk) +[![Slack](https://img.shields.io/badge/slack-join-1DA1F2?style=flat&logo=slack)](https://yiiframework.com/go/slack) ## License @@ -190,15 +172,3 @@ The Yii Framework Bulma Integration is free software. It is released under the t Please see [`LICENSE`](./LICENSE.md) for more information. Maintained by [Yii Software](https://www.yiiframework.com/). - -### Support the project - -[![Open Collective](https://img.shields.io/badge/Open%20Collective-sponsor-7eadf1?logo=open%20collective&logoColor=7eadf1&labelColor=555555)](https://opencollective.com/yiisoft) - -### Follow updates - -[![Official website](https://img.shields.io/badge/Powered_by-Yii_Framework-green.svg?style=flat)](https://www.yiiframework.com/) -[![Twitter](https://img.shields.io/badge/twitter-follow-1DA1F2?logo=twitter&logoColor=1DA1F2&labelColor=555555?style=flat)](https://twitter.com/yiiframework) -[![Telegram](https://img.shields.io/badge/telegram-join-1DA1F2?style=flat&logo=telegram)](https://t.me/yii3en) -[![Facebook](https://img.shields.io/badge/facebook-join-1DA1F2?style=flat&logo=facebook&logoColor=ffffff)](https://www.facebook.com/groups/yiitalk) -[![Slack](https://img.shields.io/badge/slack-join-1DA1F2?style=flat&logo=slack)](https://yiiframework.com/go/slack) diff --git a/composer.json b/composer.json index 9b324c0..ca6c88d 100644 --- a/composer.json +++ b/composer.json @@ -13,7 +13,7 @@ "issues": "https://github.com/yiisoft/yii-bulma/issues?state=open", "forum": "https://www.yiiframework.com/forum/", "wiki": "https://www.yiiframework.com/wiki/", - "irc": "irc://irc.freenode.net/yii", + "irc": "ircs://irc.libera.chat:6697/yii", "chat": "https://t.me/yii3en", "source": "https://github.com/yiisoft/yii-bulma" }, diff --git a/docs/guide/README.md b/docs/guide/README.md new file mode 100644 index 0000000..75bbf53 --- /dev/null +++ b/docs/guide/README.md @@ -0,0 +1,5 @@ +# Yii Framework Bulma Integration + +- [English](en/README.md) +- [Português - Brasil](pt-BR/README.md) +- [Internals](internals.md) diff --git a/docs/guide/en/README.md b/docs/guide/en/README.md new file mode 100644 index 0000000..8a3f546 --- /dev/null +++ b/docs/guide/en/README.md @@ -0,0 +1,17 @@ +# Yii Framework Bulma Integration + +## Widgets usage + +We will quickly and easily describe how to use widgets, and be able to use all the power of +the Bulma CSS framework with PHP: + +- [Breadcrumbs](breadcrumbs.md) +- [Dropdown](dropdown.md) +- [Menu](menu.md) +- [Message](message.md) +- [Modal](modal.md) +- [ModalCard](modalcard.md) +- [NavBar](navbar.md) +- [Panel](panel.md) +- [ProgressBar](progressbar.md) +- [Tabs](tabs.md) diff --git a/docs/guide/en/breadcrumbs.md b/docs/guide/en/breadcrumbs.md new file mode 100644 index 0000000..72f29cc --- /dev/null +++ b/docs/guide/en/breadcrumbs.md @@ -0,0 +1,88 @@ +# Breadcrumbs widget + +### [The Bulma breadcrumb](https://bulma.io/documentation/components/breadcrumb/) is a simple navigation component + +

+
+ +

+ +## Usage + +```php +register(BulmaAsset::class); + +$this->setCssFiles($assetManager->getCssFiles()); +$this->setJsFiles($assetManager->getJsFiles()); +?> + +// The Font-Awesome Asset must be added, in this case we are going to use an external library. + + +attributes(['class' => 'is-centered']) + ->homeItem([ + 'label' => 'Index', + 'url' => '/index', + 'icon' => 'fas fa-home', + 'iconAttributes' => ['class' => 'icon'] + ]) + ->items([ + [ + 'label' => 'About', + 'url' => '/about', + 'icon' => 'fas fa-thumbs-up', + 'iconAttributes' => ['class' => 'icon'] + ] + ]) + ->render() ?> +``` + +The code above generates the following HTML: + +```html + +``` + +## Setters + +All setters are immutable and return a new instance of the `Yiisoft\Yii\Bulma\Breadcrumbs` class with the specified value. + +Method | Description | Default +-------|-------------|--------- +`activeItemTemplate(string $value)`| Template used to render each active item in the breadcrumbs. | `
  • {link}
    • \n` +`ariaLabel` | Defines a string value that labels the current element. | `breadcrumbs` +`attributes(array $value)` | HTML attributes for the widget container nav tag. | `[]` +`autoIdPrefix(string $value)` | Prefix to the automatically generated widget ID. | `w` +`encode()` | Enable/Disable encoding for labels. | `false` +`homeItem(?array $value)` | The first item in the breadcrumbs (called home link). | `['label' => 'Home', 'url' => '/']` +`id(string $value)` | Widget ID. | `''` +`items(array $value)` | List of items to appear in the breadcrumbs. | `[]` +`itemsAttributes(array $value)` | HTML attributes for the items widget. | `[]` +`itemTemplate(string $value)` | Template used to render each inactive item in the breadcrumbs. | `
  • {icon}{link}
    • \n` + +### Items structure is an array of the following structure + +```php +[ + [ + 'label' => 'Home', + 'url' => '/', + 'template' => '
  • {icon}{label}
    • ', + 'encode' => true, + 'icon' => 'fas fa-home', + 'iconAttributes' => ['class' => 'icon'], + ], +] +``` diff --git a/docs/dropdown.md b/docs/guide/en/dropdown.md similarity index 100% rename from docs/dropdown.md rename to docs/guide/en/dropdown.md diff --git a/docs/menu.md b/docs/guide/en/menu.md similarity index 100% rename from docs/menu.md rename to docs/guide/en/menu.md diff --git a/docs/message.md b/docs/guide/en/message.md similarity index 97% rename from docs/message.md rename to docs/guide/en/message.md index 28823d6..8ed6786 100644 --- a/docs/message.md +++ b/docs/guide/en/message.md @@ -1,6 +1,6 @@ # Message widget -### [The message component](https://bulma.io/documentation/components/message/) displays a message like the following: +### [The message component](https://bulma.io/documentation/components/message/) displays a message like the following


    @@ -20,9 +20,6 @@ necessary JavaScript. Alternatively, you can use your own JavaScript code. ```php
    -

    +

    ## Usage ```php The modal structure: + - `modal`: the main container - - `modal-background`: a transparent overlay that can act as a click target to close the modal - - `modal-card`: ... - - `modal-card-head`: ... - - `modal-card-title`: ... - - `modal-card-body`: ... - - `modal-card-foot`: ... + - `modal-background`: a transparent overlay that can act as a click target to close the modal + - `modal-card`: ... + - `modal-card-head`: ... + - `modal-card-title`: ... + - `modal-card-body`: ... + - `modal-card-foot`: ... ## Usage ```php
    @@ -33,9 +33,6 @@ You can use Navbar the following way: ```php
    @@ -11,9 +11,6 @@ ```php
    @@ -11,9 +11,6 @@ ```php {icon}{link}\n` -### Items structure is an array of the following structure: +### Items structure is an array of the following structure ```php [ diff --git a/docs/guide/pt-BR/dropdown.md b/docs/guide/pt-BR/dropdown.md new file mode 100644 index 0000000..186a40c --- /dev/null +++ b/docs/guide/pt-BR/dropdown.md @@ -0,0 +1,118 @@ +# Dropdown widget + +### [The dropdown component](https://bulma.io/documentation/components/dropdown/) is a container for a dropdown button and a dropdown menu. + +

    +
    + +

    + +HTML generated consists of: + +- `dropdown` the main container. +- `dropdown-trigger` the container for a button. +- `dropdown-menu` the toggleable menu, hidden by default. +- `dropdown-content` the dropdown box, with a white background and a shadow. +- `dropdown-item` each single item of the dropdown, which can either be a a or a div. +- `dropdown-divider` a horizontal line to separate dropdown items. + +## Usage + +```php +/** + * @var Yiisoft\Assets\AssetManager $assetManager + * @var Yiisoft\View\WebView $this + */ + +/* Register assets in view */ + +$assetManager->registerMany([ + BulmaAsset::class, + BulmaJsAsset::class +]); + +$this->setCssFiles($assetManager->getCssFiles()); +$this->setJsFiles($assetManager->getJsFiles()); +?> + +buttonLabel('Russian cities') + ->items([ + ['label' => 'San petesburgo', 'url' => '#'], + ['label' => 'Moscu', 'url' => '#'], + ['label' => 'Novosibirsk', 'url' => '#'], + '-', + ['label' => 'Ekaterinburgo', 'url' => '#'], + ]) + ->render(); +?> +``` + +The code above generates the following HTML: + +```html +
    +
    + +
    + +
    +``` + +## Setters + +All setters are immutable and return a new instance of the `Yiisoft\Yii\Bulma\Dropdown` class with the specified value. + +Method | Description | Default +-------|-------------|--------- +`attributes(array $value)` | Sets the HTML attributes for the dropdown container. | `[]` +`autoIdPrefix(string $value)` | Prefix to the automatically generated widget ID. | `w` +`buttonAttributes(array $values)` | The HTML attributes for the dropdown button. | `[]` +`buttonIconAttributes(array $values)` | The HTML attributes for the dropdown button icon. | `['class' => 'icon is-small']` +`buttonIconCssClass(string $value)` | Set icon CSS class for the dropdown button. | `''` +`buttonIconText(string $value)` | Set icon text for the dropdown button. | `'↓'` +`buttonLabel(string $value)` | Set label for the dropdown button. | `'Click Me'` +`buttonLabelAttributes(array $values)` | The HTML attributes for the dropdown button label. | `[]` +`contentCssClass(string $value)` | Set CSS class for dropdown content. | `'dropdown-content'` +`cssClass(string $value)` | Set CSS class for the dropdown container. | `'dropdown'` +`dividerCssClass(string $value)` | Set CSS class for horizontal line separating dropdown items. | `'dropdown-divider'` +`enclosedByContainer(bool $value = false)` | Whether the widget should be enclosed by a container. | `true` +`id(string $value)` | Set the ID of the dropdown. | `''` +`itemActiveCssClass(string $value)` | Set CSS class for active dropdown item. | `'is-active'` +`itemCssClass(string $value)` | Set CSS class for dropdown item. | `'dropdown-item'` +`itemDisabledStyleCss(string $value)` | Set Style attributes for disabled dropdown item. | `'opacity:.65;pointer-events:none;'` +`itemHeaderCssClass(string $value)` | Set CSS class for dropdown item header. | `'dropdown-header'` +`items(array $value)` | Set the dropdown items. | `[]` +`menuCssClass(string $value)` | Set CSS class for dropdown menu. | `'dropdown-menu'` +`submenu(bool $value)` | Set whether the dropdown is a submenu. | `false` +`submenuAttributes(array $values)` | The HTML attributes for the dropdown submenu. | `[]` +`triggerCssClass(string $value)` | Set CSS class for dropdown trigger. | `'dropdown-trigger'` + +### Items structure is an array of the following structure: + +```php +[ + [ + 'label' => '', + 'url' => '', + 'urlAttributes' => [], + 'iconText' => '', + 'iconCssClass' => '', + 'iconAttributes' => [], + 'active' => false, + 'disabled' => false, + 'enclose' => false, + 'submenu' => false, + ], +] diff --git a/docs/guide/pt-BR/menu.md b/docs/guide/pt-BR/menu.md new file mode 100644 index 0000000..21c0cf3 --- /dev/null +++ b/docs/guide/pt-BR/menu.md @@ -0,0 +1,138 @@ +# Menu widget + +### [The Bulma menu](https://bulma.io/documentation/components/menu/) is a vertical navigation component. + +

    +
    + +

    + +HTML generated consists of: +- The `menu` container. +- Informative `menu-label` labels. +- Interactive `menu-list` lists that can be nested up to 2 levels. + +## Usage + +```php +/** + * @var Yiisoft\Assets\AssetManager $assetManager + * @var Yiisoft\View\WebView $this + */ + +use Yiisoft\Yii\Bulma\Asset\BulmaAsset; +use Yiisoft\Yii\Bulma\Menu; + +/* Register assets in view */ + +$assetManager->register(BulmaAsset::class); + +$this->setCssFiles($assetManager->getCssFiles()); +$this->setJsFiles($assetManager->getJsFiles()); +?> + +brand( + '
    ' . "\n" . '
    ' . "\n" . + 'Brand Example' . "\n" . '
    ' . "\n" . '
    ' + ) + ->currentPath('site/index') + ->items([ + ['label' => 'General', + 'items' => [ + [ + 'label' => 'Dashboard', + 'url' => 'site/index', + 'icon' => 'mdi mdi-desktop-mac', + 'iconAttributes' => ['class' => 'icon'] + ], + [ + 'label' => 'Logout', + 'url' => 'site/logout', + 'icon' => 'mdi mdi-logout', + 'iconAttributes' => ['class' => 'icon'] + ], + ] + ], + ['label' => 'Users', + 'items' => [ + ['label' => 'Manager', 'url' => 'user/index'], + ['label' => 'Export', 'url' => 'user/export'] + ] + ], + ]) + ->render() ?> +``` + +HTML produced is like the following: + +```html + +``` + +Method | Description | Default +-------|-------------|--------- +`activateParents()` | Whether to activate parent menu items when one of the corresponding child menu items is active. | `true` +`activeCssClass(string $value)` | The CSS class to be appended to the active menu item. | `is-active` +`autoIdPrefix(string $value)` | Prefix to the automatically generated widget ID. | `w` +`attributes(array $value)` | HTML attributes for the widget container nav tag. | `[]` +`brand(string $value)` | Custom brand content. | `''` +`currentPath(string $value)` | Allows you to assign the current path of the URL from request controller. | `''` +`deactivateItems()` | Disable active items according to their current path. | `false` +`firstItemCssClass(string $value)` | The CSS class for the first item in the main menu or each submenu. | `''` +`hiddenEmptyItems()` | Whether to hide empty menu items. | `false` +`id(string $value)` | Widget ID. | `''` +`itemAttributes(array $value)` | List of HTML attributes shared by all menu. | `[]` +`items(array $value)` | List of menu items. | `[]` +`itemsTag(?string $value)` | Tag name of the container element, `null` value means that container tag will not be rendered. | `ul` +`labelTemplate(string $value)`| The template used to render the body of a menu which is NOT a link. | `''` +`lastItemCssClass(string $value)` | The CSS class that will be assigned to the last item in the main menu or each submenu. | `''` +`subMenuTemplate(string $value)` | The template used to render a list of sub-menus. | `` +`urlTemplate(string $value)` | The template used to render the body of a menu which is a link. | `{icon}{label}` + +### Items structure is an array of the following structure: + +```php +[ + [ + 'label' => '', + 'labelTemplate' => '', + 'url' => '', + 'urlAttributes' => [], + 'urlTemplate' => '', + 'items' => [], + 'itemAtrributes' => [], + 'icon' => '',, + 'iconAttributes' => [], + 'active' => false, + 'submenuTemplate' => '', + 'encode' => false, + 'visible' => true, + ], +] diff --git a/docs/guide/pt-BR/message.md b/docs/guide/pt-BR/message.md new file mode 100644 index 0000000..8ed6786 --- /dev/null +++ b/docs/guide/pt-BR/message.md @@ -0,0 +1,79 @@ +# Message widget + +### [The message component](https://bulma.io/documentation/components/message/) displays a message like the following + +

    +
    + +

    + +HTML generated consists of: + +- A `message` container. +- An optional `message-header` that can hold a title, and a "delete" element. +- A `message-body` for the longer body of the message. + +In order for the message to be close-able you can use the asset `BulmaJsAsset::class`, which registers +necessary JavaScript. Alternatively, you can use your own JavaScript code. + +## Usage + +```php +registerMany([ + BulmaAsset::class, + BulmaJsAsset::class, +]); + +$this->setCssFiles($assetManager->getCssFiles()); +$this->setJsFiles($assetManager->getJsFiles()); +?> + +attributes(['class' => 'has-text-justified']) + ->body('Holy guacamole! You should check in on some of those fields below.') + ->headerColor('is-success') + ->headerMessage('Very important') + ->size('is-large') ?> +``` + +The code above generates the following HTML: + +```html +
    +
    +

    Very important

    + +
    +
    + Holy guacamole! You should check in on some of those fields below. +
    +
    +``` + +## Setters + +All setters are immutable and return a new instance of the `Yiisoft\Yii\Bulma\Message` class with the specified value. + +Method | Description | Default +-------|-------------|--------- +`attributes(array $value)` | The HTML attributes | `[]` +`autoIdPrefix(string $value)` | Prefix to the automatically generated widget ID. | `w` +`body(string $value)` | Message body. | `''` +`bodyAttributes(array $value)` | HTML attributes for the body tag. | `[]` +`bodyCssClass(string $value)` | CSS class for the body container. | `''` +`closeButtonAttributes(array $value)`| HTML attributes for rendering the close button tag. | `[]` +`encode()` | Enable/Disable encoding for labels. | `false` +`headerAttributes(array $value)` | HTML attributes for the header tag. | `[]` +`headerColor(string $value)` | Message color. Options available are: (`Message::COLOR_DARK`, `Message::COLOR_PRIMARY`, `Message::COLOR_LINK`, `Message::COLOR_INFO`, `Message::COLOR_SUCCESS`, `Message::COLOR_WARNING`, `Message::COLOR_DANGER`). | `Message::COLOR_DARK` +`headerMessage(string $value)` | Message header. | `''` +`id(string $value)` | Widget ID. | `''` +`size(string $value)` | Message widget size. Default is normal. Options available are: (`Message::SIZE_SMALL`, `Message::SIZE_MEDIUM`, `Message::SIZE_LARGE`. | `normal` +`withoutCloseButton(bool $value)` | Whether the close button is disabled. | `false` +`withoutHeader(bool $value)` | Whether the header is disabled. | `false` diff --git a/docs/guide/pt-BR/modal.md b/docs/guide/pt-BR/modal.md new file mode 100644 index 0000000..f289146 --- /dev/null +++ b/docs/guide/pt-BR/modal.md @@ -0,0 +1,137 @@ +# Modal widget + +A base [modal](https://bulma.io/documentation/components/modal/) overlay, in which you can include any content you want + +The modal structure: + +- `modal`: the main container + - `modal-background`: a transparent overlay that can act as a click target to close the modal + - `modal-content`: a horizontally and vertically centered container, in which you can include any content + - `modal-close`: a simple cross located in the top right corner + +

    +
    + +

    + +## Usage + +```php +register(BulmaAsset::class); + +$this->setCssFiles($assetManager->getCssFiles()); +$this->setJsFiles($assetManager->getJsFiles()); + +// Note: Bulma does not include any JavaScript interaction. You will have to implement the class toggle yourself. +// Example of a toggle: +$modalJS = << 0) { + $modalButtons.forEach(function ($el) { + $el.addEventListener('click', function () { + var target = $el.dataset.target; + openModal(target); + }); + }); + } + + if ($modalCloses.length > 0) { + $modalCloses.forEach(function ($el) { + $el.addEventListener('click', function () { + closeModals(); + }); + }); + } + + function openModal(target) { + var $target = document.getElementById('modal'); + rootEl.classList.add('is-clipped'); + $target.classList.add('is-active'); + } + + function closeModals() { + rootEl.classList.remove('is-clipped'); + $modals.forEach(function ($el) { + $el.classList.remove('is-active'); + }); + } + + function getAll(selector) { + var parent = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : document; + + return Array.prototype.slice.call(parent.querySelectorAll(selector), 0); + } + + document.addEventListener('keydown', function (event) { + var e = event || window.event; + + if (e.keyCode === 27) { + closeModals(); + closeDropdowns(); + } + }); +JS; + +$this->registerJs($modalJS); +?> + +id('modal') + ->begin() . + Div::tag() + ->class('box') + ->content('Say hello...') + ->render() . PHP_EOL . + Modal::end() ?> +``` + +The code above generates the following HTML: + +```html + + +``` + +## Setters + +All setters are immutable and return a new instance of the `Yiisoft\Yii\Bulma\Modal` class with the specified value. + +Method | Description | Default +-------|-------------|--------- +`attributes(array $value)` | The HTML attributes. | `[]` +`autoIdPrefix(string $value)` | Prefix to the automatically generated widget ID. | `w` +`backgroundClass(string $value)` | Class for the modal background. | `modal-background` +`buttonClass(string $value)` | Class for the modal button. | `button modal-button` +`closeButtonAttributes(array $value)` | HTML attributes for the close button tag. | [`class` => `modal-close`, `aria-label` => `close`] +`closeButtonSize(string $value)` | Close button size. Options available are: (`Modal::SIZE_SMALL`, `Modal::SIZE_MEDIUM`, `Modal::SIZE_LARGE`). | Default size is normal. +`contentAttributes(array $value)`| HTML attributes for the content tag. | `[]` +`contentClass(string $value)` | Class for the modal content. | `modal-content` +`id(string $value)` | Widget ID. | `''` +`modalClass(string $value)` | Class for the modal. | `modal` +`toggleButtonAttributes(array $value)` | HTML attributes for the toogle button tag. | [`class` => `button`, `aria-haspopup` => `true`] +`toggleButtonColor(string $value)` | Toggle button color. Options available are: (`Modal::COLOR_PRIMARY`, `Modal::COLOR_LINK`, `Modal::COLOR_INFO`, `Modal::COLOR_SUCCESS`, `Modal::COLOR_WARNING`, `Modal::COLOR_DANGER`, `Modal::COLOR_DARK`). | Default setting empty whitout color. +`toggleButtonLabel(string $value)` | Toggle button label, | `Toggle button` +`toggleButtonSize(string $value)` | Size toggle button. Options available are: (`Modal::SIZE_SMALL`, `Modal::SIZE_MEDIUM`, `Modal::SIZE_LARGE`). | Default setting empty normal. +`withoutCloseButton(bool $value)` | Whether the close button is disabled. | `false` +`withoutToggleButton(bool $value)` | Whether the toggle button is disabled. | `false` diff --git a/docs/guide/pt-BR/modalcard.md b/docs/guide/pt-BR/modalcard.md new file mode 100644 index 0000000..d593942 --- /dev/null +++ b/docs/guide/pt-BR/modalcard.md @@ -0,0 +1,127 @@ +# Modal card widget + +### A classic [modal](https://bulma.io/documentation/components/modal/) overlay, in which you can include any content you want + +

    +
    + +

    + +The modal structure: + +- `modal`: the main container + - `modal-background`: a transparent overlay that can act as a click target to close the modal + - `modal-card`: ... + - `modal-card-head`: ... + - `modal-card-title`: ... + - `modal-card-body`: ... + - `modal-card-foot`: ... + +## Usage + +```php +registerMany([ + BulmaAsset::class, + BulmaJsAsset::class, +]); + +$this->setCssFiles($assetManager->getCssFiles()); +$this->setJsFiles($assetManager->getJsFiles()); + +// @link https://bulmajs.tomerbe.co.uk/docs/0.12/2-core-components/modal/ +$modalJS = <<registerJs($modalJS); +?> + +footer( + Button::tag() + ->class('button is-success') + ->content('Save changes') . + Button::tag() + ->class('button is-danger is-outline') + ->content('Cancel') + ) + ->title('Modal title.') + ->begin() ?> + class('image is-4by3') + ->content(Img::tag()->src('https://bulma.io/images/placeholders/1280x960.png')) ?> + +``` + +The code above generates the following HTML: + +```html + + +``` + +## Setters + +All setters are immutable and return a new instance of the `Yiisoft\Yii\Bulma\ModalCard` class with the specified value. + +Method | Description | Default +-------|-------------|--------- +`attributes(array $value)` | The HTML attributes. | `[]` +`autoIdPrefix(string $value)` | Prefix to the automatically generated widget ID. | `w` +`backgroundClass(string $value)` | The class for the modal background. | `modal-background` +`bodyAttributes(array $value)` | HTML attributes for the body tag.| [] +`bodyClass(string $value)` | The class for the modal body. | `modal-card-body` +`buttonClass(string $value)` | The class for the modal button. | `button modal-button` +`cardAttributes(array $value)` | HTML attributes for the card. | [] +`cardClass(string $value)` | The class for the modal card. | `modal-card` +`closeButtonAttributes(array $value)` | HTML attributes for the close button. | [] +`closeButtonCssClass(string $value)` | The class for the close button. | `button delete` +`closeButtonSize(string $value)` | Сlose button size. Options available are: (`ModalCard::SIZE_SMALL`, `ModalCard::SIZE_MEDIUM`, `ModalCard::SIZE_LARGE`). | Default setting is "normal". +`contentClass(string $value)` | The class for the modal card content. | `modal-card-content` +`footer(string $value)` | The footer content. | `''` +`footerAttributes(array $value)` | HTML attributes for the footer. | [] +`footerClass(string $value)` | The class for the modal card footer. | `modal-card-foot` +`headerAttributes(array $value)` | HTML attributes for the header. | [] +`headerClass(string $value)` | The class for the modal card header. | `modal-card-head` +`id(string $value)` | Widget ID. | `''` +`title(string $value)` | The title content. | `''` +`titleAttributes(array $value)` | HTML attributes for the title. | [] +`titleClass(string $value)` | The class for the modal card title. | `modal-card-title` +`toggleButtonAttributes(array $value)` | HTML attributes for the toggle button. | [] +`toggleButtonColor(string $value)` | Toggle button color. Options available are: (`ModalCard::COLOR_PRIMARY`, `ModalCard::COLOR_INFO`, `ModalCard::COLOR_SUCCESS`, `ModalCard::COLOR_WARNING`, `ModalCard::COLOR_DANGER`, `ModalCard::COLOR_DARK`). | `''` +`toggleButtonId(?string $value)` | Toggle button ID. | `''` +`toggleButtonLabel(string $value)` | Toggle button label. | `'Toggle button'` +`toggleButtonSize(string $value)` | Toggle button size. Options available are: (`ModalCard::SIZE_SMALL`, `ModalCard::SIZE_MEDIUM`, `ModalCard::SIZE_LARGE`). | Default setting is "normal". +`withoutCloseButton(bool $value)` | Whether the close button is disabled. | `false` +`withoutToggleButton(bool $value)` | Whether the toggle button is disabled. | `false` diff --git a/docs/guide/pt-BR/navbar.md b/docs/guide/pt-BR/navbar.md new file mode 100644 index 0000000..98b4ca3 --- /dev/null +++ b/docs/guide/pt-BR/navbar.md @@ -0,0 +1,184 @@ +# Navbar and nav widget + +### [The navbar component](https://bulma.io/documentation/components/navbar/) is a responsive and versatile horizontal navigation bar + +

    +
    + +

    + +

    +
    + +

    + +

    +
    + +

    + +HTML generated consists of: + +- `navbar` the main container. +- `navbar-brand` the left side, always visible, which usually contains the logo and optionally some links or icons. +- `navbar-burger` the hamburger icon, which toggles the navbar menu on touch devices. +- `navbar-menu` the right side, hidden on touch devices, visible on a desktop. +- `navbar-start` the left part of the menu, which appears next to the navbar brand on desktop. +- `navbar-end` the right part of the menu, which appears at the end of the navbar. +- `navbar-item` each single item of the navbar, which can either be an a or a div. + +## Usage + +You can use Navbar the following way: + +```php +registerMany([ + BulmaAsset::class, + BulmaJsAsset::class +]); + +$this->setCssFiles($assetManager->getCssFiles()); +$this->setJsFiles($assetManager->getJsFiles()); +?> + +// The Font-Awesome Asset must be added, in this case we are going to use an external library. + + +attributes(['class' => 'is-black', 'data-sticky' => '', 'data-sticky-shadow' => '']) + ->brandImage('yii-logo.jpg') + ->brandText('My Project') + ->brandUrl('/') + ->begin() +?> + +enclosedByEndMenu() + ->items([ + [ + 'label' => 'Setting Account', + 'url' => '/setting/account', + 'icon' => 'fas fa-user-cog', + 'iconAttributes' => ['class' => 'icon'] + ], + [ + 'label' => 'Profile', + 'url' => '/profile', + 'icon' => 'fas fa-users', + 'iconAttributes' => ['class' => 'icon'] + ], + [ + 'label' => 'Admin' . Html::img( + '../../docs/images/icon-avatar.png', + ['class' => 'img-rounded', 'aria-expanded' => 'false'] + ), + 'items' => [ + ['label' => 'Logout', 'url' => '/auth/logout'], + ], + 'encode' => false + ] + ]) + ->render() +?> + + +``` + +The code above generates the following HTML: + +```html + +``` + +## Setters + +All setters are immutable and return a new instance of the `Yiisoft\Yii\Bulma\NavBar` class with the specified value. + +Method | Description | Default +-------|-------------|--------- +`ariaLabel(string $value)` | The ARIA label of the navbar. | `'main navigation'` +`attributes(array $values)` | HTML attributes for the widget container nav. | `[]` +`autoIdPrefix(string $value)` | Prefix to the automatically generated widget ID. | `w` +`brandAttributes(array $values)` | HTML attributes for the navbar brand. | `[]` +`brandCssClass(string $value)` | CSS class for the navbar brand. | `'navbar-brand'` +`brandImage(string $value)` | Image for the navbar brand. | `''` +`brandImageAttributes(array $values)` | HTML attributes for the navbar brand image. | `[]` +`brandText(string $value)` | Text for the navbar brand. | `''` +`brandTextAttributes(array $values)` | HTML attributes for the navbar brand text. | `[]` +`brandUrl(string $value)` | URL for the navbar brand. | `''` +`burgerAttributes(array $values)` | HTML attributes for the navbar burger. | `[]` +`burgerCssClass(string $value)` | CSS class for the navbar burger. | `'navbar-burger'` +`buttonLinkAriaExpanded(string $value)` | The ARIA expanded attribute of the button link. | `'false'` +`buttonLinkAriaLabelText(string $value)` | The ARIA label text of the button link. | `'menu'` +`buttonLinkContent(string $value)` | The content of the button link. | `''` +`buttonLinkRole(string $value)` | The role of the button link. | `'button'` +`cssClass(string $value)` | CSS class for the navbar. | `'navbar'` +`id(string $value)` | Set the ID of the navbar. | `''` +`itemCssClass(string $value)` | CSS class for the navbar item. | `'navbar-item'` +`role(string $value)` | The role of the navbar. | `'navigation'` + +All setters are immutable and return a new instance of the `Yiisoft\Yii\Bulma\Nav` class with the specified value. + +Method | Description | Default +-------|-------------|--------- +`activateParents()` | Activate parent menu items when the current menu item is activated. | `false` +`attributes(array $values)` | HTML attributes for the widget container | `[]` +`currentPath(string $value)` | Allows you to assign the current path of the url from request controller. | `''` +`enclosedByEndMenu()` | Align the menu items to the right. | `false` +`enclosedByStartMenu()` | Align the menu items to the left. | `false` +`items(array $value)` | The menu items. | `[]` +`withoutActivateItems()` | Disable activate items according to whether their currentPath. | `false` + +### Items structure is an array of the following structure + +```php +[ + [ + 'label' => '', + 'url' => '', + 'urlAttributes' => [], + 'dropdownAttributes' => [], + 'iconText' => '', + 'iconCssClass' => '', + 'iconAttributes' => [], + 'items' => [], + 'active' => false, + 'disable' => false, + 'visible' => false, + 'encode' => false, + ], +] diff --git a/docs/guide/pt-BR/panel.md b/docs/guide/pt-BR/panel.md new file mode 100644 index 0000000..ca2f6db --- /dev/null +++ b/docs/guide/pt-BR/panel.md @@ -0,0 +1,156 @@ +# Panel widget + +### A composable [panel](https://bulma.io/documentation/components/panel/), for compact controls + +

    +
    + +

    + +## Usage + +```php +registerMany([ + BulmaAsset::class, + BulmaJsAsset::class, +]); + +$this->setCssFiles($assetManager->getCssFiles()); +$this->setJsFiles($assetManager->getJsFiles()); + +$template = << +

    + + + + +

    + + {panelItems} +
    + +
    + {panelEnd} +HTML; + +echo Panel::widget() + ->template($template) + ->tabs([ + [ + 'label' => 'All', + 'active' => true, + 'urlAttributes' => ['data-all' => true], + 'items' => [ + [ + 'label' => 'bulma', + 'icon' => 'fas fa-book', + 'urlAttributes' => ['data-category' => 'All'], + ], + [ + 'label' => 'marksheet', + 'icon' => 'fas fa-book', + 'urlAttributes' => ['data-category' => 'All'], + ], + ], + ], + ['label' => 'Public', 'urlAttributes' => ['data-target' => 'Public']], + ['label' => 'Private', 'urlAttributes' => ['data-target' => 'Private']], + ['label' => 'Sources', 'urlAttributes' => ['data-target' => 'Sources']], + ['label' => 'Forks', 'urlAttributes' => ['data-target' => 'Fork']], + ]) + ->render() +``` + +HTML produced is like the following: + +```html + +``` + +## Reference + +Method | Description | Default +-------|-------------|--------- +`attributes(array $value)` | HTML attributes for the widget container nav tag. | `[]` +`autoIdPrefix(string $value)` | Prefix to the automatically generated widget ID. | `w` +`blockClass(string $value)` | CSS class for the panel block. | `panel-block` +`color(string $value)` | Color panel Options available are: (`Panel::COLOR_DARK`, `Panel::COLOR_PRIMARY`, `Panel::COLOR_LINK`, `Panel::COLOR_INFO`, `Panel::COLOR_SUCCESS`, `Panel::COLOR_WARNING`, `Panel::COLOR_DANGER`) | `''` +`cssClass(string $value)` | CSS class for the widget container nav tag. | `''` +`heading(string $value)` | Text of the brand heading. | `''` +`headingAttributes(array $value)` | HTML attributes of the heading. | [`class` => `panel-heading`] +`iconClass(string $value)` | CSS class for the panel icon. | `panel-icon` +`id(string $value)` | Widget ID. | `''` +`isActiveClass(string $value)` | CSS class for the active tab. | `is-active` +`tabClass(string $value)` | CSS class for the panel tab. | `panel-tab` +`tabs(array $value)` | List of panel tabs items. | `[]` +`tabsAttributes(array $value)` | HTML attributes for the tabs container tag. | `[]` +`template(string $value)` | String the template for rendering panel. | `{panelBegin}{panelHeading}{panelTabs}{panelItems}{panelEnd}` + +### Tabs structure is an array of the following structure + +```php +[ + [ + 'label' => '', + 'url' => '', + 'active' => false, + 'urlAttributes' => [], + 'encode' => false, + 'items' => [ + [ + 'label' => '', + 'icon' => '', + 'url' => '', + 'urlAttributes' => [], + 'encode' => false, + ], + ], + ], +] diff --git a/docs/guide/pt-BR/progressbar.md b/docs/guide/pt-BR/progressbar.md new file mode 100644 index 0000000..7ecdf7a --- /dev/null +++ b/docs/guide/pt-BR/progressbar.md @@ -0,0 +1,56 @@ +# Progress Bar widget + +[The Bulma progress bar](https://bulma.io/documentation/elements/progress/) is a simple CSS class that styles the native +`` [HTML element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/progress). + +Loading widget looks like the following: + +

    + +

    + +In progress widget looks like this: + +

    + +

    + +## Usage + +```php +register(BulmaAsset::class); + +$this->setCssFiles($assetManager->getCssFiles()); + +echo ProgressBar::widget() + ->size('is-medium') + ->color('is-info') + ->maxValue(100) + ->value(75); +``` + +The code above generates the following HTML: + +```html +75% +``` + +## Setters + +All setters are immutable and return a new instance of the `Yiisoft\Yii\Bulma\ProgressBar` class with the specified value. + +Method | Description | Default +-------|-------------|--------- +`attributes(array $value)` | The HTML attributes. | `[]` +`autoIdPrefix(string $value)` | Prefix to the automatically generated widget ID. | `w` +`color(string $value)` | Bar color. Options available are: (`ProgressBar::COLOR_PRIMARY`, `ProgressBar::COLOR_LINK`, `ProgressBar::COLOR_INFO`, `ProgressBar::COLOR_SUCCESS`, `ProgressBar::COLOR_WARNING`, `ProgressBar::COLOR_DANGER`, `ProgressBar::COLOR_DARK`). | Default is no color. +`id(string $value)` | Widget ID. | `''` +`maxValue(int $value)` | Maximum progress value. `0` means no maximum. | `100` +`size(string $value)` | Bar size. Options available are: (`ProgressBar::SIZE_SMALL`, `ProgressBar::SIZE_MEDIUM`, `ProgressBar::SIZE_LARGE`). | Default setting is normal. +`value(float $value)` | The progress value. Set to `0` to display a loading animation. | `0` diff --git a/docs/guide/pt-BR/tabs.md b/docs/guide/pt-BR/tabs.md new file mode 100644 index 0000000..ebd5e77 --- /dev/null +++ b/docs/guide/pt-BR/tabs.md @@ -0,0 +1,113 @@ +# Tabs widget + +### Responsive horizontal [navigation tabs](https://bulma.io/documentation/components/tabs/), with different styles + +

    +
    + +

    + +## Usage + +```php +registerMany([ + BulmaAsset::class, + BulmaJsAsset::class, +]); + +$this->setCssFiles($assetManager->getCssFiles()); +$this->setJsFiles($assetManager->getJsFiles()); + +echo Tabs::widget() + ->alignment(Tabs::ALIGNMENT_CENTERED) + ->size(Tabs::SIZE_LARGE) + ->style(Tabs::STYLE_BOX) + ->items([ + [ + 'label' => 'Pictures', + 'icon' => 'fas fa-image', + 'active' => true, + 'content' => 'Some text about pictures', + 'contentAttributes' => [ + 'class' => 'is-active', + ], + ], + ['label' => 'Music', 'icon' => 'fas fa-music', 'content' => 'Some text about music'], + ['label' => 'Videos', 'icon' => 'fas fa-film', 'content' => 'Some text about videos'], + ['label' => 'Documents', 'icon' => 'far fa-file-alt', 'content' => 'Some text about documents'], + ]); +``` + +HTML produced is like the following: + +```html +
    + +
    + +
    +
    Some text about pictures
    +
    Some text about music
    +
    Some text about videos
    +
    Some text about documents
    +
    +``` + +## Reference + +Method | Description | Default +-------|-------------|--------- +`alignment(string $value)` | Alignment of the tabs list. | `''` +`attributes(array $value)` | HTML attributes for the widget container nav tag. | `[]` +`autoIdPrefix(string $value)` | Prefix to the automatically generated widget ID. | `w` +`currentPath(string $value)` | Allows you to assign the current path of the URL from request controller. | `` +`deactivateItems()` | Disable active items according to their current path. | `false` +`id(string $value)` | Widget ID. | `''` +`items(array $value)` | List of tab items. | `[]` +`size(string $value)` | Size of the tabs list. | `is-small`, `is-medium`, `is-large` +`style(string $value)` | Style of the tabs list. | `''` +`tabsContentAttributes(array $value)` | List of HTML attributes for the `tabs-content` container. | `[]` +`withoutEncodeLabels()` | When tags Labels HTML should not be encoded. | `false` | diff --git a/docs/internals.md b/docs/internals.md new file mode 100644 index 0000000..8dc4049 --- /dev/null +++ b/docs/internals.md @@ -0,0 +1,45 @@ +# Internals + +## Unit testing + +The package is tested with [PHPUnit](https://phpunit.de/). To run tests: + +```shell +./vendor/bin/phpunit +``` + +## Mutation testing + +The package tests are checked with [Infection](https://infection.github.io/) mutation framework with +[Infection Static Analysis Plugin](https://github.com/Roave/infection-static-analysis-plugin). To run it: + +```shell +./vendor/bin/roave-infection-static-analysis-plugin +``` + +## Static analysis + +The code is statically analyzed with [Psalm](https://psalm.dev/). To run static analysis: + +```shell +./vendor/bin/psalm +``` + +## Rector + +Use [Rector](https://github.com/rectorphp/rector) to make codebase follow some specific rules or +use either newest or any specific version of PHP: + +```shell +./vendor/bin/rector +``` + +## Composer require checker + +This package uses [composer-require-checker](https://github.com/maglnet/ComposerRequireChecker) to check if all dependencies are correctly defined in `composer.json`. + +To run the checker, execute the following command: + +```shell +./vendor/bin/composer-require-checker +```