From dde6601fdafc9a178ecd0fed09d547bcec78d0ec Mon Sep 17 00:00:00 2001 From: Oh My Felix Date: Tue, 23 Jun 2026 06:42:32 +0000 Subject: [PATCH] Docs: move documentation to README Co-authored-by: Felix --- .docs/README.md | 295 --------------------------------------------- README.md | 309 ++++++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 298 insertions(+), 306 deletions(-) delete mode 100644 .docs/README.md diff --git a/.docs/README.md b/.docs/README.md deleted file mode 100644 index ea8ebf2..0000000 --- a/.docs/README.md +++ /dev/null @@ -1,295 +0,0 @@ -# Nette menu - -## Content - -- [Setup](#setup) -- [Usage](#usage) -- [Templates](#templates) -- [Translations](#translations) -- [Authorization](#authorization) - -## Setup - -**Install package with composer:** - -```bash -composer require contributte/menu-control -``` - -**Register as nette extension:** - -```neon -extensions: - menu: Contributte\MenuControl\DI\MenuExtension - -menu: -``` - -## Usage - -You can write menu links as associated multi dimensional arrays. Because of this you are able to create any -structure of menus and submenus you may need. - -```neon -menu: - front: - items: - Home: - action: Front:Home: - Books: - link: '#' - items: - All: - action: Front:Books:all - Featured: - action: Front:Books:featured - admin: - items: - Users: - action: Admin:Users: - - Books: - action: Admin:Books: -``` - -```php -menuFactory = $menuFactory; - } - - protected function createComponentMenu(): MenuComponent - { - return $this->menuFactory->create('front'); - } - -} -``` - -```latte -{control menu} -{control menu:breadcrumbs} -{control menu:sitemap} -``` - -That structure in neon config will generate two menus: - -**front:** - -* Home (action: `Front:Home:`) -* Books (link: `#`) - + All (action: `Front:Books:all`) - + Featured (action: `Front:Books:featured`) - -**admin:** - -* Users (action: `Admin:Users:`) -* Books (action: `Admin:Books:`) - -## Templates - -This package includes 3 default templates (menu, breadcrumbs, sitemap). However only the default sitemap template -should be used in real project. The other two templates should only help you in the beginning with building your own -templates which will fit your's website look. - -* [menu.latte](../src/UI/templates/menu.latte) -* [breadcrumbs.latte](../src/UI/templates/breadcrumbs.latte) -* [sitemap.latte](../src/UI/templates/sitemap.latte) - -Changing templates can be done in your menu configuration: - -```neon -menu: - front: - templates: - menu: %appDir%/path/to/custom/menu.latte - breadcrumbs: %appDir%/path/to/custom/breadcrumbs.latte - sitemap: %appDir%/path/to/custom/sitemap.latte -``` - -**As you can see, each menu can have different templates.** - -### Visibility of items - -It may be useful to hide some links in specific situations. For that we have the `visibility` option on items where -you can tell on which template the link should be visible. - -```neon -menu: - front: - items: - Home: - action: Front:Home: - visibility: - menu: true - breadcrumbs: false - sitemap: true -``` - -### Mark active item via regex - -Menu item can be labeled as active by a regular expression (or array of regular expressions) that is compared to the entire Presenter's name and action. -You can set your regular expression via `include` setting. - -```neon -menu: - front: - items: - Home: - action: Front:Home: - include: '^Front\:Home\:[a-zA-Z\:]+$' # mark as active for all actions of "Front:Home:" presenter - Books: - action: Front:Books: - include: # mark as active for actions "Front:Books:default" and "Front:Books:edit" - - '^Front\:Books\:default$' - - '^Front\:Books\:edit$' -``` - -## Translations - -When displaying title of link in some template, we always work with translated titles. - -You have three options for translator: - -* Do nothing: Original `ReturnTranslator` class will be used. This translator just returns the given text. -* Set translator manually: Provide your own implementation of `Nette\Localization\ITranslator`. -* Set translator to `true`: Menu extension will try to find your translator in DI container automatically. - -```neon -services: - - App\MyOwnFrontTranslator - -menu: - front: - translator: @App\MyOwnFrontTranslator - admin: - translator: true -``` - -## Custom data - -Every link can contain additional data which can be later used eg. in your custom latte templates. - -```neon -menu: - admin: - items: - - Adminer: - link: http://localhost:20000 - data: - icon: fa fa-database - attrs: - target: _blank -``` - -```latte - - {$link->getRealTitle()} - -``` - -## Authorization - -Sometimes you may want to hide some links based on custom rules, that includes for example authorization from nette. - -This menu package uses custom `IAuthorizator` interface which you can use to write your own authorizators. - -```php -contributte.org | Contact 👨🏻‍💻 f3l1x.io | Twitter 🐦 @contributte

-## Usage +Menu control for Nette applications with configurable menus, breadcrumbs, sitemaps, translations, authorization, and custom link generation. + +## Versions + +| State | Version | Branch | Nette | PHP | +|--------|---------|----------|--------|---------| +| dev | `^3.3` | `master` | `3.1+` | `>=8.1` | +| stable | `^3.2` | `master` | `3.1+` | `>=8.1` | +| stable | `^2.2` | `v2.2` | `3.0` | `>=7.1` | +| stable | `^2.1` | `v2.1` | `2.4` | `>=7.1` | + +## Content + +- [Installation](#installation) +- [Usage](#usage) +- [Templates](#templates) +- [Translations](#translations) +- [Custom data](#custom-data) +- [Authorization](#authorization) +- [Link generator](#link-generator) +- [Menu loader](#menu-loader) + +## Installation To install the latest version of `contributte/menu-control` use [Composer](https://getcomposer.org). @@ -26,24 +48,289 @@ To install the latest version of `contributte/menu-control` use [Composer](https composer require contributte/menu-control ``` -## Documentation +Register as Nette extension: -For details on how to use this package, check out our [documentation](.docs). +```neon +extensions: + menu: Contributte\MenuControl\DI\MenuExtension -## Versions +menu: +``` -| State | Version | Branch | Nette | PHP | -|--------|---------|----------|--------|---------| -| dev | `^3.3` | `master` | `3.1+` | `>=8.1` | -| stable | `^3.2` | `master` | `3.1+` | `>=8.1` | -| stable | `^2.2` | `v2.2` | `3.0` | `>=7.1` | -| stable | `^2.1` | `v2.1` | `2.4` | `>=7.1` | +## Usage + +You can write menu links as associated multi dimensional arrays. Because of this you are able to create any +structure of menus and submenus you may need. + +```neon +menu: + front: + items: + Home: + action: Front:Home: + Books: + link: '#' + items: + All: + action: Front:Books:all + Featured: + action: Front:Books:featured + admin: + items: + Users: + action: Admin:Users: + + Books: + action: Admin:Books: +``` + +```php +menuFactory = $menuFactory; + } + + protected function createComponentMenu(): MenuComponent + { + return $this->menuFactory->create('front'); + } + +} +``` + +```latte +{control menu} +{control menu:breadcrumbs} +{control menu:sitemap} +``` + +That structure in neon config will generate two menus: + +**front:** + +* Home (action: `Front:Home:`) +* Books (link: `#`) + + All (action: `Front:Books:all`) + + Featured (action: `Front:Books:featured`) + +**admin:** + +* Users (action: `Admin:Users:`) +* Books (action: `Admin:Books:`) + +## Templates + +This package includes 3 default templates (menu, breadcrumbs, sitemap). However only the default sitemap template +should be used in real project. The other two templates should only help you in the beginning with building your own +templates which will fit your's website look. + +* [menu.latte](src/UI/templates/menu.latte) +* [breadcrumbs.latte](src/UI/templates/breadcrumbs.latte) +* [sitemap.latte](src/UI/templates/sitemap.latte) + +Changing templates can be done in your menu configuration: + +```neon +menu: + front: + templates: + menu: %appDir%/path/to/custom/menu.latte + breadcrumbs: %appDir%/path/to/custom/breadcrumbs.latte + sitemap: %appDir%/path/to/custom/sitemap.latte +``` + +**As you can see, each menu can have different templates.** + +### Visibility of items + +It may be useful to hide some links in specific situations. For that we have the `visibility` option on items where +you can tell on which template the link should be visible. + +```neon +menu: + front: + items: + Home: + action: Front:Home: + visibility: + menu: true + breadcrumbs: false + sitemap: true +``` + +### Mark active item via regex + +Menu item can be labeled as active by a regular expression (or array of regular expressions) that is compared to the entire Presenter's name and action. +You can set your regular expression via `include` setting. + +```neon +menu: + front: + items: + Home: + action: Front:Home: + include: '^Front\:Home\:[a-zA-Z\:]+$' # mark as active for all actions of "Front:Home:" presenter + Books: + action: Front:Books: + include: # mark as active for actions "Front:Books:default" and "Front:Books:edit" + - '^Front\:Books\:default$' + - '^Front\:Books\:edit$' +``` + +## Translations + +When displaying title of link in some template, we always work with translated titles. + +You have three options for translator: + +* Do nothing: Original `ReturnTranslator` class will be used. This translator just returns the given text. +* Set translator manually: Provide your own implementation of `Nette\Localization\ITranslator`. +* Set translator to `true`: Menu extension will try to find your translator in DI container automatically. + +```neon +services: + - App\MyOwnFrontTranslator + +menu: + front: + translator: @App\MyOwnFrontTranslator + admin: + translator: true +``` + +## Custom data + +Every link can contain additional data which can be later used eg. in your custom latte templates. + +```neon +menu: + admin: + items: + + Adminer: + link: http://localhost:20000 + data: + icon: fa fa-database + attrs: + target: _blank +``` + +```latte + + {$link->getRealTitle()} + +``` + +## Authorization + +Sometimes you may want to hide some links based on custom rules, that includes for example authorization from nette. + +This menu package uses custom `IAuthorizator` interface which you can use to write your own authorizators. + +```php +