mirror of
https://github.com/YunoHost/doc.git
synced 2024-09-03 20:06:26 +02:00
78 lines
4 KiB
Markdown
78 lines
4 KiB
Markdown
# Advanced Usage
|
|
|
|
## Presenting
|
|
|
|
The plugin, like the Reveal.js-library, makes available a Presenter-mode. There are two modes available for using this: Locally, with `sync: 'browser'`, or remotely, with `sync: 'poll'`. When running locally, you need to access your presentation with a special URL -- `http://yourgrav.tld/book?admin=yes&showNotes=true` -- **and in a new window from the same browser** open the same URL without these parameters -- `http://yourgrav.tld/book`.
|
|
|
|
The synchronization between Presenter-mode and the Presentation happens by sending data from one browser-window to the other, requiring JavaScript. When running remotely, the synchronization happens by polling and checking if the presentation has changed.
|
|
|
|
**Note:** The polling approach needs a stable server to work, more so than Grav itself. It has been tested extensively with PHP 7.1 and 7.2, running on Caddy Server and with PHP's built-in server, with a fairly standard production-setup of PHP. If your server-connection crashes with a 502 error -- usually with the error "No connection could be made because the target machine actively refused it.", it is because PHP is set up to forcibly time out despite being long-polled.
|
|
|
|
## Embedding
|
|
|
|
A Presentation-shortcode is available for embedding a presentation in another Page; `[presentation="route/to/presentation"]`. This creates an iFrame with the presentation in it. You can also add your own classes to the iFrame with the `class`-parameter: `[presentation src="introduction-to-ux/chromeless:true" class="class-one class-two"]`, or default classes with the `shortcode_classes`-option.
|
|
|
|
## Twig
|
|
|
|
Any template can be changed by making a copy of the [plugin's templates](https://github.com/OleVik/grav-plugin-presentation/tree/master/templates) in /user/themes/yourtheme/, and editing it.
|
|
|
|
### Changing the footer
|
|
|
|
Using the `footer`-setting you can append a Twig-template to each section globally, or a specific page's section. For example, `footer: "partials/presentation_footer.html.twig"` will render the theme's `partials/presentation_footer.html.twig`-template and append it to the section(s). If the element was constructed like this: `<div class="footer">My footer</div>`, you could style it like this:
|
|
|
|
```css
|
|
.reveal .slides .footer {
|
|
display: block;
|
|
position: absolute;
|
|
bottom: 2em;
|
|
}
|
|
```
|
|
|
|
You can also arbitrarily execute Twig within a page's Markdown by enabling it in the FrontMatter with:
|
|
|
|
```yaml
|
|
twig_first: true
|
|
process:
|
|
twig: true
|
|
```
|
|
|
|
For example, `<p>{{ site.author.name }}</p>` will render the name of the author defined in site.yaml.
|
|
|
|
## Creating a menu
|
|
|
|
The plugin makes a `presentation_menu`-variable available through Twig on pages which use the fullscreen-template, which can be used to construct an overall menu of pages. It is an array with anchors and titles for each page, and a list of them with links to sections can be constructed like this:
|
|
|
|
```
|
|
<ul id="menu" class="menu">
|
|
{% for anchor, title in presentation_menu %}
|
|
<li>
|
|
<a href="#{{ anchor }}">{{ title }}</a>
|
|
</li>
|
|
{% endfor %}
|
|
</ul>
|
|
```
|
|
|
|
Each slide is assigned an `id`-attribute based on the page's slug and its index, as well as a `data-title`-attribute containing the title of the page. A menu could also be made using this data with JavaScript: `document.getElementById('presentation').querySelectorAll('*[id]')`.
|
|
|
|
## Creating a shortcode or shortcode-alias
|
|
|
|
In your theme's or plugin's PHP-file, subscribe to the `onShortcodeHandlers`-event and register and/or alias shortcodes:
|
|
|
|
```php
|
|
public static function getSubscribedEvents()
|
|
{
|
|
return [
|
|
'onShortcodeHandlers' => ['onShortcodeHandlers', 0]
|
|
];
|
|
}
|
|
|
|
public function onShortcodeHandlers()
|
|
{
|
|
// Register shortcodes
|
|
$this->grav['shortcode']->registerAllShortcodes(__DIR__ . '/shortcodes');
|
|
// Add a shortcode-alias
|
|
$this->grav['shortcode']->getHandlers()->addAlias('link-overlay-alias', 'link-overlay');
|
|
}
|
|
```
|
|
|
|
For the `addAlias()`-method, the first parameter is the name of the alias, the second is the original name of the shortcode.
|