From d11bcda6ce33a486ef4284f928d6c6bc9384e9e1 Mon Sep 17 00:00:00 2001 From: Oh My Felix Date: Mon, 6 Jul 2026 15:01:21 +0000 Subject: [PATCH] Docs: move documentation to README Co-authored-by: Felix --- .docs/README.md | 164 ----------------------------------------------- README.md | 167 +++++++++++++++++++++++++++++++++++++++++++++--- 2 files changed, 159 insertions(+), 172 deletions(-) delete mode 100644 .docs/README.md diff --git a/.docs/README.md b/.docs/README.md deleted file mode 100644 index f9f6305..0000000 --- a/.docs/README.md +++ /dev/null @@ -1,164 +0,0 @@ -# Contributte UI - -## Installation - -```bash -composer require contributte/ui -``` - -## Usage - -### Bundler - -```neon -services: - latte.latteFactory: - setup: - - addExtension(App\Model\ViteExtension(%wwwDir%/dist/manifest.json, /dist)) -``` - -### CSP Nonce Support - -The Vite extension automatically supports Content Security Policy nonces via the `uiNonce` variable provided by [`nette/application`](https://github.com/nette/application). - -```latte -{vitejs 'assets/js/app.js'} -{vitecss 'assets/js/app.js'} -``` - -When nonce is available, it's automatically injected: - -```html - - -``` - -To use nonce support, ensure your Nette application sets the nonce value in presenter or middleware: - -```php -$nonce = base64_encode(random_bytes(16)); -$this->template->uiNonce = $nonce; -header("Content-Security-Policy: script-src 'nonce-{$nonce}'; style-src 'nonce-{$nonce}'"); -``` - -### Paginator - -Register the factory: - -```neon -services: - - Contributte\UI\Paginator\PaginatorControlFactory -``` - -Create a data provider: - -```php -use Contributte\UI\Paginator\ArrayDataProvider; -use Contributte\UI\Paginator\PaginatorDataProvider; -use Nette\Utils\Paginator; - -// Using built-in ArrayDataProvider -$provider = new ArrayDataProvider($data); - -// Or implement your own -class MyDataProvider implements PaginatorDataProvider -{ - public function page(Paginator $paginator): array - { - $paginator->setItemCount($this->getTotalCount()); - return $this->fetchItems($paginator->getOffset(), $paginator->getLength()); - } -} -``` - -Use in presenter: - -```php -use Contributte\UI\Paginator\PaginatorControlFactory; - -class ArticlePresenter extends Nette\Application\UI\Presenter -{ - public function __construct( - private PaginatorControlFactory $paginatorFactory, - ) {} - - protected function createComponentPaginator(): PaginatorControl - { - $provider = new ArrayDataProvider($this->articles); - $control = $this->paginatorFactory->create($provider, itemsPerPage: 10); - $control->onPagination[] = fn() => $this->redrawControl('articles'); - return $control; - } - - public function renderDefault(): void - { - $this->template->articles = $this['paginator']->getPage(); - } -} -``` - -Render in template: - -```latte -
-
...
- {control paginator} -
-``` - -Custom template: - -```php -$control->setTemplateFile(__DIR__ . '/templates/myPaginator.latte'); -``` - -Built-in templates: `bootstrap4.latte`, `bootstrap5.latte` (default). - -## Examples - -### Vite - -```js -import { defineConfig } from 'vite'; -import { resolve } from 'path'; - -export default defineConfig(({ mode }) => { - const DEV = mode === 'development'; - - return { - resolve: { - alias: { - '@': resolve(__dirname, 'assets/js'), - '~': resolve(__dirname, 'node_modules'), - }, - }, - server: { - open: false, - hmr: false, - }, - build: { - manifest: true, - assetsDir: '', - outDir: './www/dist/', - emptyOutDir: false, - minify: DEV ? false : 'esbuild', - rollupOptions: { - output: { - manualChunks: undefined, - chunkFileNames: DEV ? '[name].js' : '[name]-[hash].js', - entryFileNames: DEV ? '[name].js' : '[name].[hash].js', - assetFileNames: DEV ? '[name].[ext]' : '[name].[hash].[ext]', - }, - input: { - app: './assets/js/app.js' - } - } - }, - } -}); -``` - - ---------------- - -Thanks for testing, reporting and contributing. diff --git a/README.md b/README.md index 049a106..850ff94 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,16 @@ Website 🚀 contributte.org | Contact 👨🏻‍💻 f3l1x.io | Twitter 🐦 @contributte

-## Usage +UI helpers for Nette applications, including Vite asset tags, CSP nonce support and paginator controls. + +## Versions + +| State | Version | Branch | Nette | PHP | +|-------------|---------|----------|-------|---------| +| dev | `^0.3` | `master` | 3.2+ | `>=8.2` | +| stable | `^0.2` | `master` | 3.1+ | `>=8.1` | + +## Installation To install latest version of `contributte/ui` use [Composer](https://getcomposer.org). @@ -26,17 +35,159 @@ To install latest version of `contributte/ui` use [Composer](https://getcomposer composer require contributte/ui ``` -## Documentation +## Usage -For details on how to use this package, check out our [documentation](.docs). +### Bundler -## Versions +```neon +services: + latte.latteFactory: + setup: + - addExtension(Contributte\UI\Bundler\ViteExtension(%wwwDir%/dist/manifest.json, /dist)) +``` -| State | Version | Branch | Nette | PHP | -|-------------|---------|----------|-------|---------| -| dev | `^0.3` | `master` | 3.1+ | `>=8.1` | -| stable | `^0.2` | `master` | 3.1+ | `>=8.1` | +### CSP Nonce Support + +The Vite extension automatically supports Content Security Policy nonces via the `uiNonce` variable provided by [`nette/application`](https://github.com/nette/application). + +```latte +{vitejs 'assets/js/app.js'} +{vitecss 'assets/js/app.js'} +``` + +When nonce is available, it is automatically injected: + +```html + + +``` + +To use nonce support, ensure your Nette application sets the nonce value in presenter or middleware: + +```php +$nonce = base64_encode(random_bytes(16)); +$this->template->uiNonce = $nonce; +header("Content-Security-Policy: script-src 'nonce-{$nonce}'; style-src 'nonce-{$nonce}'"); +``` + +### Paginator + +Register the factory: +```neon +services: + - Contributte\UI\Paginator\PaginatorControlFactory +``` + +Create a data provider: + +```php +use Contributte\UI\Paginator\ArrayDataProvider; +use Contributte\UI\Paginator\PaginatorDataProvider; +use Nette\Utils\Paginator; + +// Using built-in ArrayDataProvider +$provider = new ArrayDataProvider($data); + +// Or implement your own +class MyDataProvider implements PaginatorDataProvider +{ + public function page(Paginator $paginator): array + { + $paginator->setItemCount($this->getTotalCount()); + return $this->fetchItems($paginator->getOffset(), $paginator->getLength()); + } +} +``` + +Use in presenter: + +```php +use Contributte\UI\Paginator\PaginatorControlFactory; +use Contributte\UI\Paginator\ArrayDataProvider; +use Contributte\UI\Paginator\PaginatorControl; + +class ArticlePresenter extends Nette\Application\UI\Presenter +{ + public function __construct( + private PaginatorControlFactory $paginatorFactory, + ) {} + + protected function createComponentPaginator(): PaginatorControl + { + $provider = new ArrayDataProvider($this->articles); + $control = $this->paginatorFactory->create($provider, itemsPerPage: 10); + $control->onPagination[] = fn() => $this->redrawControl('articles'); + return $control; + } + + public function renderDefault(): void + { + $this->template->articles = $this['paginator']->getPage(); + } +} +``` + +Render in template: + +```latte +
+
...
+ {control paginator} +
+``` + +Custom template: + +```php +$control->setTemplateFile(__DIR__ . '/templates/myPaginator.latte'); +``` + +Built-in templates: `bootstrap4.latte`, `bootstrap5.latte` (default). + +## Examples + +### Vite + +```js +import { defineConfig } from 'vite'; +import { resolve } from 'path'; + +export default defineConfig(({ mode }) => { + const DEV = mode === 'development'; + + return { + resolve: { + alias: { + '@': resolve(__dirname, 'assets/js'), + '~': resolve(__dirname, 'node_modules'), + }, + }, + server: { + open: false, + hmr: false, + }, + build: { + manifest: true, + assetsDir: '', + outDir: './www/dist/', + emptyOutDir: false, + minify: DEV ? false : 'esbuild', + rollupOptions: { + output: { + manualChunks: undefined, + chunkFileNames: DEV ? '[name].js' : '[name]-[hash].js', + entryFileNames: DEV ? '[name].js' : '[name].[hash].js', + assetFileNames: DEV ? '[name].[ext]' : '[name].[hash].[ext]', + }, + input: { + app: './assets/js/app.js' + } + } + }, + } +}); +``` ## Development