Skip to content

Commit

Permalink
Adds stand-alone usage to documentation
Browse files Browse the repository at this point in the history 
Signed-off-by: Frank Brückner <dev@froschdesignstudio.de>
  • Loading branch information
@froschdesign
froschdesign committed Jun 21, 2020
1 parent 1e7334a commit e5539ed
Show file tree
Hide file tree
Showing 2 changed files with 302 additions and 0 deletions.
300 changes: 300 additions & 0 deletions docs/book/application-integration/stand-alone.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,300 @@
# Stand-Alone

The paginator can also be used stand-alone, outside of a Mezzio or laminas-mvc
application.

The example uses the following directory structure:

```treeview
example-app/
|-- public/
| `-- index.php
|-- templates/
| `-- pagination-control.phtml
`-- vendor
`-- …
```

## Create and Configure Paginator

[Create a paginator and a related adapter](../usage.md#paginating-data-collections),
set the item count for one page and the current page number in `public/index.php`:

```php
// Create paginator
$paginator = new Laminas\Paginator\Paginator(
new Laminas\Paginator\Adapter\ArrayAdapter($albums)
);

// Configure paginator
$paginator->setItemCountPerPage(4);
$paginator->setCurrentPageNumber((int) $_GET['page'] ?: 1);
```

<details><summary>Example Data</summary>

```php
$albums = [
[
'artist' => "David Bowie",
'title' => "The Next Day (Deluxe Version)",
],
[
'artist' => "Bastille",
'title' => "Bad Blood",
],
[
'artist' => "Bruno Mars",
'title' => "Unorthodox Jukebox",
],
[
'artist' => "Emeli Sandé",
'title' => "Our Version of Events (Special Edition)",
],
[
'artist' => "Bon Jovi",
'title' => "What About Now (Deluxe Version)",
],
[
'artist' => "Justin Timberlake",
'title' => "The 20/20 Experience (Deluxe Version)",
],
[
'artist' => "Bastille",
'title' => "Bad Blood (The Extended Cut)",
],
[
'artist' => "P!nk",
'title' => "The Truth About Love",
],
[
'artist' => "Sound City - Real to Reel",
'title' => "Sound City - Real to Reel",
],
[
'artist' => "Jake Bugg",
'title' => "Jake Bugg",
],
];
```

</details>

## Output Pure Data

The data of each sub-array is returned by iteration over the paginator:

```php
foreach ($paginator as $item) {
var_dump($item['artist']); // "Bon Jovi", "Justin Timberlake", …
var_dump($item['title']); // "What About Now (Deluxe Version)", "The 20/20 Experience (Deluxe Version)", …
}
```

Retrieving the [current status data of the paginator](../usage.md#listing-of-properties):

```php
var_dump($paginator->getPages()->previous); // 1
var_dump($paginator->getPages()->next); // 3
```

## Usage with laminas-view

### Create View Script

[Create a view script](https://docs.laminas.dev/laminas-view/view-scripts/) in
`templates/pagination-control.phtml`:

```php
<?php
/**
* @var Laminas\View\Renderer\PhpRenderer $this
* @var int $pageCount
* @var int $previous
* @var int $next
* @var int $current
* @var array<int, int> $pagesInRange
*/
?>

<?php if ($pageCount): ?>
<nav aria-label="Page navigation example">
<ul class="pagination">
<!-- Previous page link -->
<?php if (isset($previous)): ?>
<li class="page-item">
<a class="page-link" href="index.php?page=<?= $previous ?>">Previous</a>
</li>
<?php else: ?>
<li class="page-item disabled">
<a class="page-link" href="#" tabindex="-1" aria-disabled="true">Previous</a>
</li>
<?php endif; ?>

<!-- Numbered page links -->
<?php foreach ($pagesInRange as $page): ?>
<?php if ($page !== $current): ?>
<li class="page-item">
<a class="page-link" href="index.php?page=<?= $page ?>">
<?= $page ?>
</a>
</li>
<?php else: ?>
<!-- Current page -->
<li class="page-item active" aria-current="page">
<a class="page-link" href="#"><?= $page ?> <span class="sr-only">(current)</span></a>
</li>
<?php endif; ?>
<?php endforeach; ?>

<!-- Next page link -->
<?php if (isset($this->next)): ?>
<li class="page-item">
<a class="page-link" href="index.php?page=<?= $next ?>">Next</a>
</li>
<?php else: ?>
<li class="page-item disabled">
<a class="page-link" href="#" tabindex="-1" aria-disabled="true">Next</a>
</li>
<?php endif; ?>
</ul>
</nav>
<?php endif; ?>
```

### Setup

[Set a resolver for templates](https://docs.laminas.dev/laminas-view/php-renderer/#usage)
and set template for the [related view helper](../usage.md#rendering-pages-with-view-scripts)
in `public/index.php`:

```php
// Create template resolver
$templateResolver = new Laminas\View\Resolver\TemplatePathStack([
'script_paths' => [__DIR__ . '/../templates'],
]);

// Setup renderer
/** @var Laminas\View\Renderer\PhpRenderer $renderer */
$renderer = $paginator->getView();
$renderer->setResolver($templateResolver);

// Set template for related view helper
$renderer->plugin('paginationControl')->setDefaultViewPartial('pagination-control');
```

### Render Output

```php
echo $paginator->render();
```

Output:

```html
<nav aria-label="Page navigation example">
<ul class="pagination">
<!-- Previous page link -->
<li class="page-item">
<a class="page-link" href="index.php?page=1">Previous</a>
</li>

<!-- Numbered page links -->
<li class="page-item">
<a class="page-link" href="index.php?page=1">
1
</a>
</li>
<!-- Current page -->
<li class="page-item active" aria-current="page">
<a class="page-link" href="#">2 <span class="sr-only">(current)</span></a>
</li>
<li class="page-item">
<a class="page-link" href="index.php?page=3">
3
</a>
</li>

<!-- Next page link -->
<li class="page-item">
<a class="page-link" href="index.php?page=3">Next</a>
</li>
</ul>
</nav>
```

<details><summary>Show full code example</summary>

```php
<?php

require_once __DIR__ . '/../vendor/autoload.php';

$albums = [
[
'artist' => "David Bowie",
'title' => "The Next Day (Deluxe Version)",
],
[
'artist' => "Bastille",
'title' => "Bad Blood",
],
[
'artist' => "Bruno Mars",
'title' => "Unorthodox Jukebox",
],
[
'artist' => "Emeli Sandé",
'title' => "Our Version of Events (Special Edition)",
],
[
'artist' => "Bon Jovi",
'title' => "What About Now (Deluxe Version)",
],
[
'artist' => "Justin Timberlake",
'title' => "The 20/20 Experience (Deluxe Version)",
],
[
'artist' => "Bastille",
'title' => "Bad Blood (The Extended Cut)",
],
[
'artist' => "P!nk",
'title' => "The Truth About Love",
],
[
'artist' => "Sound City - Real to Reel",
'title' => "Sound City - Real to Reel",
],
[
'artist' => "Jake Bugg",
'title' => "Jake Bugg",
],
];

// Create paginator
$paginator = new Laminas\Paginator\Paginator(
new Laminas\Paginator\Adapter\ArrayAdapter($albums)
);
$paginator->setItemCountPerPage(4);
$paginator->setCurrentPageNumber((int) $_GET['page'] ?: 1);

// Create template resolver
$templateResolver = new Laminas\View\Resolver\TemplatePathStack([
'script_paths' => [__DIR__ . '/../templates'],
]);

// Setup renderer
/** @var Laminas\View\Renderer\PhpRenderer $renderer */
$renderer = $paginator->getView();
$renderer->setResolver($templateResolver);

// Set template for related view helper
$renderer->plugin('paginationControl')->setDefaultViewPartial('pagination-control');

// Render output
echo $paginator->render();
```

</details>
2 changes: 2 additions & 0 deletions mkdocs.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,8 @@ nav:
- Reference:
- Configuration: configuration.md
- "Advanced Usage": advanced.md
- 'Application Integration':
- 'Stand-Alone': application-integration/stand-alone.md
site_name: laminas-paginator
site_description: 'Paginate collections of data from arbitrary sources.'
repo_url: 'https://github.com/laminas/laminas-paginator'
Expand Down

0 comments on commit e5539ed

Please sign in to comment.