Variables de thème

Lorsque vous concevez un thème, Grav vous donne accès à toutes sortes d'objets et de variables à partir de vos modèles Twig. Le cadre de modélisation Twig fournit des moyens puissants pour lire et manipuler ces objets et variables. Ceci est entièrement expliqué dans leur propre documentation ainsi que résumé succinctement dans notre propre documentation.

Dans Twig, vous pouvez appeler des méthodes qui ne prennent aucun paramètre en appelant simplement le nom de la méthode et en omettant les parenthèses (). Si vous devez transmettre des paramètres, vous devez également les fournir après le nom de la méthode. page.content est équivalent à page.content().

Objets de base

Plusieurs objets principaux sont disponibles pour un modèle Twig, et chaque objet possède un ensemble de variables et de fonctions.

variable base_dir

La variable {{ base_dir }} renvoie le répertoire du fichier de base de l'installation de Grav.

variable base_url

Le {{ base_url }} renvoie l'URL de base au site Grav, que cela affiche ou non l'URL complète dépend de l'option absolute_urls dans la configuration du système.

variable base_url_relative

Le {{ base_url_relative }} renvoie l'URL de base au site Grav, sans les informations sur l'hôte.

variable base_url_absolute

Le {{ base_url_absolute }} renvoie l'URL de base au site Grav, y compris les informations sur l'hôte.

variable base_url_simple

Le {{ base_url_simple }} renvoie l'URL de base au site Grav, sans le code de langue.

variable home_url

Le {{ home_url }} est particulièrement utile pour renvoyer vers la page d'accueil de votre site. Il est similaire à base_url mais prend en compte la langue actuellement active.

variable html_lang

Le {{ html_lang }} renvoie la langue active.

Le {{ theme_url }} renvoie l'URL relative au thème actuel.

Cela renverra la langue active actuelle si elle est fournie, sinon utilisez l'option configurée site.default_lang, sinon revenez à en.

variable theme_dir

La variable {{ theme_dir }}renvoie le dossier du répertoire de fichiers du thème actuel.

Lors de la création de liens vers des ressources telles que des images ou des fichiers JavaScript et CSS, il est recommandé d'utiliser la fonction url() en combinaison avec le flux theme:// comme décrit sur la page Balises Filtres & Functions TWIG. Pour JavaScript et CSS, Asset Manager est encore plus simple à utiliser mais dans certains cas comme le chargement dynamique ou conditionnel des assets, cela ne fonctionnera pas.

variable language_codes

Le {{ language_codes }} renvoie la liste des langues disponibles du site.

objet assets

Asset Manager ajoute un moyen simple de gérer CSS et JavaScript dans votre site.

1 | {% do assets.addCss('theme://css/foo.css') %}
2 | {% do assets.addInlineCss('a { color: red; }') %}
3 | {% do assets.addJs('theme://js/something.js') %}
4 | {% do assets.addInlineJs('alert("Warming!");') %}

En savoir plus sur Asset Manager.

ASTUCE : Il est recommandé d'utiliser à la place la balise styles et la .

objet config

Vous pouvez accéder à n'importe quel paramètre de configuration Grav défini dans les fichiers YAML dans /user/config via l'objet config. Par example:

{{ config.system.pages.theme }}{# returns the currently configured theme #}

objet site

Un alias de l'objet config.site. Ceci représente la configuration définie dans le fichier site.yaml.

objet system

Un alias de l'objet config.system. Ceci représente la configuration dans le fichier principal system.yaml.

objet theme

Un alias de l'objet config.theme. Cela représente la configuration du thème actif actuel. Les paramètres du plugin sont disponibles via config.plugins.

objet page

Parce que Grav est construit en utilisant la structure définie dans le dossier pages/ , chaque page est représentée par un objet page.

L'objet page est probablement l'objet le plus important avec lequel vous travaillerez car il contient toutes les informations sur la page actuelle sur laquelle vous vous trouvez.

La liste complète des méthodes de l'objet Page est disponible sur le site API (PAGE NON CONSTRUITE). Voici une liste des méthodes que vous trouverez les plus utiles.

summary()

Cela renvoie une version tronquée ou raccourcie de votre contenu. Vous pouvez fournir un paramètre size facultatif pour spécifier la longueur maximale du résumé, en caractères. Alternativement, si aucune taille n'est fournie, la valeur peut être obtenue via la variable à l'échelle du site summary.size à partir de votre configuration site.yaml.

{{ page.summary|brut }}

ou alors

{{ page.summary(50)|raw }}

Une troisième option consiste à utiliser un délimiteur manuel de === dans votre contenu. Tout ce qui précède le délimiteur sera utilisé pour le résumé.

content()

Cela renvoie l'intégralité du contenu HTML de votre page.

{{ page.content|raw }}

Cela renvoie les en-têtes de page tels que définis dans le front-matter YAML de la page. Par exemple une page avec les en-têtes suivants :

1 | title: My Page
2 | author: Joe Bloggs

peut être utilisé:

The author of this page is: {{ page.header.author|e }}

media()

Cela renvoie un objet Media contenant tous les médias associés à une page. Ceux-ci incluent des images, des vidéos et d'autres fichiers. Vous pouvez accéder aux méthodes multimédias comme décrit dans la documentation multimédia pour le contenu. Parce qu'il agit comme un tableau, les filtres et fonctions Twig peuvent être utilisés. Remarque : les images SVG sont traitées comme des fichiers, et non comme des images, car elles ne peuvent pas être manipulées à l'aide de filtres d'image twig.

Obtenir un fichier ou une image spécifique :

{% set my_pdf = page.media['myfile.pdf'] %}

Obtenez la première image :

{% set first_image = page.media.images|premier %}

Bouclez sur toutes les images et affichez la balise HTML pour l'afficher :

{% for image in page.media.images %}
   {{ image.html|raw }}
{% endfor %}

title()

Cela renvoie le titre de la page tel qu'il est défini dans la variable title des en-têtes YAML de la page elle-même.

title: My Page

Cela renvoie la valeur de la variable menu des en-têtes YAML de la page. Si aucun n'est fourni, il s'agit par défaut du titre.

1 | title: My Page
2 | menu: my-page

visible()

Ceci renvoie si la page est visible ou non. Par défaut, les pages avec une valeur numérique suivie d'un point sont visibles par défaut (01.somefolder1) tandis que celles sans (subfolder2) ne sont pas considérées comme visibles. Cela peut être remplacé dans les en-têtes de page :

1 | title: My Page
2 | visible: true

routable()

Ceci renvoie si oui ou non une page est routable par Grav. Cela signifie que si vous pouvez pointer votre navigateur vers la page et recevoir le contenu en retour. Les pages non routables peuvent être utilisées dans des modèles, des plugins, etc., mais ne peuvent pas être atteintes directement. Cela peut être défini dans les en-têtes de page :

1 | title: My Page
2 | routable: true

slug()

Cela renvoie le nom direct tel qu'il est affiché dans l'URL de cette page, par exemplemy-blog-post.

URL([include_host = false])

Cela renvoie l'URL de la page, par exemple :

{{ page.url|e }} {# could return /my-section/my-category/my-blog-post #}

ou alors

{{ page.url(true)|e }} {# could return http://mysite.com/my-section/my-category/my-blog-post #}

permalink()

Cela renvoie l'URL avec les informations sur l'hôte. Particulièrement utile lorsque vous avez besoin d'un lien rapide accessible de n'importe où.

canonical()

Cela renvoie l'URL qui est la version "préférée" ou le lien vers une page particulière. Cette valeur sera par défaut l'URL normale à moins que la page n'ait remplacé l'option en-tête de page canonical:.

route()

Cela renvoie le routage interne d'une page. Ceci est principalement utilisé pour le routage interne et la répartition des pages.

home()

Cela renvoie true ou false selon que cette page est configurée ou non comme page d'accueil. Ce paramètre se trouve dans le fichier system.yaml.

root()

Cela renvoie true ou false selon que cette page est ou non la page racine de la hiérarchie de l'arborescence.

active()

Cela renvoie true ou false selon que cette page est ou non actuellement la page à laquelle votre navigateur accède. Ceci est particulièrement utile en navigation pour savoir si la page sur laquelle vous vous trouvez est la page active.

modular()

Cela renvoietrue ou false selon que cette page est modulaire ou non.

activeChild()

Ceci renvoie si oui ou non l'URL de cet URI contient l'URL de la page active. Ou en d'autres termes, est l'URL de cette page dans l'URL actuelle. Encore une fois, cela est utile lors de la construction de votre navigation et vous souhaitez savoir si la page sur laquelle vous parcourez est le parent d'une page enfant active.

find(url)

Cela renvoie un objet de page tel que spécifié par une URL de route.

{% include 'modular/author-detail.html.twig' with {'page': page.find('/authors/billy-bloggs')} %}

collection()

Cela renvoie la collection de pages pour ce contexte tel que déterminé par les en-têtes de page de collection.

1 | {% for child in page.collection %}
2 |   {% include 'partials/blog_item.html.twig' with {'page':child, 'truncate':true} %}
3 | {% endfor %}

currentPosition()

Cela renvoie l'index de la page en cours par rapport à ses frères et sœurs.

isFirst()

Cela renvoie true ou false selon que cette page est la première de ses frères et sœurs.

isLast()

Cela renvoie true ou false selon que cette page est la dernière de ses frères et sœurs.

nextSibling()

Cela renvoie la page suivante du tableau de frères et sœurs en fonction de la position actuelle.

prevSibling()

Cela renvoie la page précédente du tableau de frères et sœurs en fonction de la position actuelle.

nextSibling() et prevSibling() ordonnent les pages dans une structure semblable à une pile. Cela fonctionne mieux dans une situation de blog, où le premier article de blog a nextSibling null et prevSibling est l'article de blog précédent. Si ce sens de commande vous embrouille, nous vous suggérons d'utiliser page.adjacentSibling(-1) pour pointer vers la page suivante au lieu de page.nextSibling() afin de réduire la confusion que la terminologie pourrait créer. Vous pouvez également définir une constante dans le thème et l'utiliser pour une meilleure lisibilité, comme page.adjacentSibling(NEXT_PAGE)

children()

Cela renvoie un tableau de pages enfants pour la page, tel que défini dans la structure de contenu des pages.

orderBy()

Cela renvoie le type de commande pour tous les enfants triés de la page. Les valeurs incluent généralement : default, title, date et folder. Cette valeur est généralement configurée dans les en-têtes de page.

orderDir()

Cela renvoie la direction de l'ordre pour tous les enfants triés de la page. Les valeurs peuvent être asc pour l'ordre croissant ou desc pour l'ordre décroissant. Cette valeur est généralement configurée dans les en-têtes de page.

orderManual()

Cela renvoie un tableau de classement manuel des pages pour tous les enfants de la page. Cette valeur est généralement configurée dans les en-têtes de page.

maxCount()

Cela renvoie le nombre maximal de pages enfants pouvant être renvoyées. Cette valeur est généralement configurée dans les en-têtes de page.

children.count()

Cela renvoie le nombre de pages enfants de la page.

children.current()

Cela renvoie l'élément enfant actuel. Peut être utilisé lors de l'itération sur les enfants.

children.next()

Cela renvoie l'enfant suivant dans le tableau d'enfants.

children.prev()

Cela renvoie l'enfant précédent dans le tableau d'enfants.

children.nth(position)

Cela renvoie l'enfant identifié par position qui est un entier de 0 à children.count() - 1 dans le tableau des enfants.

children.sort(orderBy, orderDir)

Réorganise les enfants en fonction d'un orderBy (default, title, date et folder) et orderDir (asc ou desc)

parent()

Cela renvoie l'objet de page parent pour cette page. Ceci est très utile lorsque vous avez besoin de remonter dans l'arborescence imbriquée des pages.

isPage()

Cela renvoie true ou false selon que cette page est associée à un fichier .md réel plutôt qu'à un simple dossier de routage.

isDir()

Cela renvoie true ou false selon que cette page est uniquement un dossier pour le routage.

id()

Cela renvoie un identifiant unique pour la page.

modified()

Cela renvoie un horodatage de la dernière modification de la page.

date()

Cela renvoie l'horodatage de la date de la page. Généralement, cela est défini dans les en-têtes pour représenter la date d'une page ou d'un article. Si aucune valeur n'est définie explicitement, l'horodatage de modification du fichier est utilisé.

template()

Cela renvoie le nom du modèle de page sans l'extension .md. Par exemple default.

filePath()

Cela renvoie le chemin d'accès complet au fichier de la page. Par exemple /Users/votrenom/sites/grav/user/pages/01.home/default.md.

filePathClean()

Cela renvoie le chemin relatif à partir de la racine du site Grav. Par exemple user/pages/01.home/default.md.

path()

Cela renvoie le chemin complet du répertoire contenant la page. Par exemple /Users/votrenom/sites/grav/user/pages/01.home.

folder()

Cela renvoie le nom du dossier de la page. Par exemple 01.home.

taxonomy()

Cela renvoie un tableau de la taxonomie associée à une page. Celles-ci peuvent être itérées. Ceci est particulièrement utile pour afficher des éléments tels que des balises :

1 | {% for tag in page.taxonomy.tag %}
2 |    <a href="search/tag:{{ tag }}">{{ tag }}</a>
3 | {% endfor %}

Objet pages

L'objet pages est la page racine qui représente un arbre imbriqué de chaque objet de page que Grav connaît. Ceci est particulièrement utile pour la création d'un sitemap, la navigation ou si vous souhaitez trouver une page en particulier.

Cet objet n'est pas le même que grav.pages qui est une instance de la classe Pages.

children method

Cela renvoie les pages enfants immédiates sous la forme d'un tableau d'objets de page. Comme l'objet pages représente l'arborescence entière, vous pouvez parcourir entièrement chaque page du dossier Grav pages/.

Obtenez les pages de niveau supérieur pour un menu simple :

1 | <ul class="navigation">
2 |     {% for page in pages.children %}
3 |         {% if page.visible %}
4 |             <li><a href="{{ page.url }}">{{ page.menu }}</a></li>
5 |         {% endif %}
6 |     {% endfor %}
7 |</ul>

Objet media

Il existe un nouvel objet qui vous permet d'accéder aux médias qui se trouvent en dehors des objets Page via les flux PHP de Twig. Cela fonctionne de la même manière que la liaison d'images dans le contenu en utilisant des flux pour accéder aux images et un traitement multimédia pour manipuler le thème.

{{ media['user://media/bird.png'].resize(50, 50).rotate(90).html()|raw }}

Objet uri

La liste complète des méthodes de l'objet Uri est disponible sur le site de l'API(PAGE NON CONSTRUITE) . Voici une liste des méthodes que vous trouverez les plus utiles.

L'objet Uri a plusieurs méthodes pour accéder à des parties de l'URI actuel. Pour l'URL complète http://mysite.com/grav/section/category/page.json/param1:foo/param2:bar/?query1=baz&query2=qux :

path()

Cela renvoie la partie chemin de l'URL : (par exemple,uri.path = /section/category/page)

paths()

Cela renvoie le tableau des éléments de chemin : (par exemple, uri.paths = [section, catégorie, page])

route([absolute = false][, domain = false])

Cela renvoie la route sous forme d'URL absolue ou relative. (par exemple uri.route(true) = http://mysite.com/grav/section/category/page ou uri.route() = /section/category/page)

params()

Cela renvoie la partie params de l'URL : (par exemple, uri.params = /param1:foo/param2:bar)

param(id)

Cela renvoie la valeur d'un paramètre particulier. (par exemple, uri.param('param1') = foo)

query()

Cela renvoie la partie requête de l'URL : (par exemple, uri.query = query1=bar&query2=qux)

quer(id)

Vous pouvez également récupérer des éléments de requête spécifiques : (par exemple, uri.query('query1') = bar)

URL([include_host = true])

Cela renvoie l'URL complète avec ou sans l'hôte. (par exemple uri.url(false) = grav/section/category/page/param:foo?query=bar)

extension()

Cela renvoie l'extension, ou renverra html s'il n'est pas fourni : (par exemple, uri.extension = json)

host()

Cela renvoie la partie hôte de l'URL. (par exemple, uri.host = mysite.com)

base()

Cela renvoie la partie de base de l'URL. (par exemple, uri.base = http://monsite.com)

rootUrl([include_host = false])

Cela renvoie l'URL racine à l'instance grav. (par exemple uri.rootUrl() = http://monsite.com/grav)

referrer()

Cela renvoie les informations de référence pour cette page.

L'objet d'en-tête est un alias pour page.header() de la page d'origine. C'est un moyen pratique d'accéder aux en-têtes de page d'origine lorsque vous parcourez d'autres objets page de pages enfants ou de collections.

content string

L'objet de contenu est un alias pour la page.content() de la page d'origine.

Pour afficher le contenu de la page, vous devez :

{{ content|raw }}

Objet de taxonomie

L'objet Taxonomy global qui contient toutes les informations de taxonomie pour le site. Pour plus d'informations, voir Taxonomy.

Objet navigateur

La liste complète des méthodes de l'objet Browser est disponible sur le site API. Voici une liste des méthodes que vous trouverez les plus utiles.

Grav a un support intégré pour déterminer par programmation la plate-forme, le navigateur et la version de l'utilisateur.

1 | {{ browser.platform|e }}   # macintosh
2 | {{ browser.browser|e }}    # chrome
3 | {{ browser.version|e }}    # 41

Objet utilisateur

Vous pouvez accéder indirectement à l'objet utilisateur actuellement connecté via l'objet Grav. Cela vous permet d'accéder à des données telles que username, fullname, title, et email.

1 | {{ grav.user.username|e }}  # admin
2 | {{ grav.user.fullname|e }}  # Billy Bloggs
3 | {{ grav.user.title|e }}     # Administrator
4 | {{ grav.user.email|e }}     # billy@bloggs.com

Ajout de variables personnalisées

Vous pouvez facilement ajouter des variables personnalisées de différentes manières. Si la variable est une variable à l'échelle du site, vous pouvez placer la variable dans votre fichier user/config/site.yaml puis y accéder via :

{{ site.my_variable|e }}

Alternativement, si la variable n'est nécessaire que pour une page particulière, vous pouvez ajouter la variable au front-matter YAML de votre page et y accéder via l'objet page.header. Par example:

title: My Page
author: Joe Bloggs

pourrait être utilisé comme :

The author of this page is: {{ page.header.author|e }}

Ajout d'objets personnalisés

Un moyen avancé d'ajouter des objets personnalisés consiste à utiliser un plugin pour ajouter des objets à l'objet Twig. Ceci est un sujet avancé et est couvert plus en détail dans le chapitre plugins.

Variables de thème

Objets de base

variable base_dir

variable base_url

variable base_url_relative

variable base_url_absolute

variable base_url_simple

variable home_url

variable html_lang

variable theme_dir

variable language_codes

objet assets

objet config

objet site

objet system

objet theme

objet page

summary()

content()

header()

media()

title()

menu()

visible()

routable()

slug()

URL([include_host = false])

permalink()

canonical()

route()

home()

root()

active()

modular()

activeChild()

find(url)

collection()

currentPosition()

isFirst()

isLast()

nextSibling()

prevSibling()

children()

orderBy()

orderDir()

orderManual()

maxCount()

children.count()

children.current()

children.next()

children.prev()

children.nth(position)

children.sort(orderBy, orderDir)

parent()

isPage()

isDir()

id()

modified()

date()

template()

filePath()

filePathClean()

path()

folder()

taxonomy()

Objet pages

children method

Objet media

Objet uri

path()

paths()

route([absolute = false][, domain = false])

params()

param(id)

query()

quer(id)

URL([include_host = true])

extension()

host()

base()