From 00e9f19560f28d29b9a4d96a8bfbcd0d41e88f24 Mon Sep 17 00:00:00 2001 From: Joe Mooring Date: Sun, 11 Feb 2024 20:55:28 -0800 Subject: [PATCH] Add Paginator methods --- content/en/methods/paginator/First.md | 29 ++++++++++++ content/en/methods/paginator/HasNext.md | 29 ++++++++++++ content/en/methods/paginator/HasPrev.md | 29 ++++++++++++ content/en/methods/paginator/Last.md | 27 ++++++++++++ content/en/methods/paginator/Next.md | 29 ++++++++++++ .../en/methods/paginator/NumberOfElements.md | 23 ++++++++++ content/en/methods/paginator/PageNumber.md | 22 ++++++++++ content/en/methods/paginator/PageSize.md | 22 ++++++++++ content/en/methods/paginator/Pagers.md | 22 ++++++++++ content/en/methods/paginator/Pages.md | 22 ++++++++++ content/en/methods/paginator/Prev.md | 29 ++++++++++++ .../paginator/TotalNumberOfElements.md | 23 ++++++++++ content/en/methods/paginator/TotalPages.md | 22 ++++++++++ content/en/methods/paginator/URL.md | 22 ++++++++++ .../en/methods/paginator/_common/_index.md | 13 ++++++ .../paginator/_common/pagination-template.md | 7 +++ content/en/methods/paginator/_index.md | 12 +++++ content/en/templates/pagination.md | 44 +------------------ data/embedded_template_urls.toml | 36 +++++++++++++++ layouts/shortcodes/eturl.html | 36 +++++++++++++++ 20 files changed, 456 insertions(+), 42 deletions(-) create mode 100644 content/en/methods/paginator/First.md create mode 100644 content/en/methods/paginator/HasNext.md create mode 100644 content/en/methods/paginator/HasPrev.md create mode 100644 content/en/methods/paginator/Last.md create mode 100644 content/en/methods/paginator/Next.md create mode 100644 content/en/methods/paginator/NumberOfElements.md create mode 100644 content/en/methods/paginator/PageNumber.md create mode 100644 content/en/methods/paginator/PageSize.md create mode 100644 content/en/methods/paginator/Pagers.md create mode 100644 content/en/methods/paginator/Pages.md create mode 100644 content/en/methods/paginator/Prev.md create mode 100644 content/en/methods/paginator/TotalNumberOfElements.md create mode 100644 content/en/methods/paginator/TotalPages.md create mode 100644 content/en/methods/paginator/URL.md create mode 100644 content/en/methods/paginator/_common/_index.md create mode 100644 content/en/methods/paginator/_common/pagination-template.md create mode 100644 content/en/methods/paginator/_index.md create mode 100644 data/embedded_template_urls.toml create mode 100644 layouts/shortcodes/eturl.html diff --git a/content/en/methods/paginator/First.md b/content/en/methods/paginator/First.md new file mode 100644 index 00000000000..7c3998deecf --- /dev/null +++ b/content/en/methods/paginator/First.md @@ -0,0 +1,29 @@ +--- +title: First +description: Returns the first Pager object in the Pagers collection. +categories: [] +keywords: [] +action: + related: + - /methods/paginator/Last + - /methods/paginator/Next + - /methods/paginator/Prev + - /methods/paginator/HasNext + - /methods/paginator/HasPrev + returnType: page.Pager + signatures: [PAGINATOR.First] +--- + + + +{{< code file=layouts/partials/pagination.html >}} +{{ with .Paginator}} + {{ with .First }} + First + {{ end }} +{{ end }} +{{< /code >}} + +{{% include "methods/paginator/_common/pagination-template.md" %}} + +[pager]: /getting-started/glossary/#pager diff --git a/content/en/methods/paginator/HasNext.md b/content/en/methods/paginator/HasNext.md new file mode 100644 index 00000000000..0e2df647bf6 --- /dev/null +++ b/content/en/methods/paginator/HasNext.md @@ -0,0 +1,29 @@ +--- +title: HasNext +description: Reports whether there is a Pager object after the current Pager object. +categories: [] +keywords: [] +action: + related: + - /methods/paginator/First + - /methods/paginator/Last + - /methods/paginator/Next + - /methods/paginator/Prev + - /methods/paginator/HasPrev + returnType: bool + signatures: [PAGINATOR.HasNext] +--- + + + +{{< code file=layouts/partials/pagination.html >}} +{{ with .Paginator}} + {{ if .HasNext }} + Next + {{ end }} +{{ end }} +{{< /code >}} + +{{% include "methods/paginator/_common/pagination-template.md" %}} + +[pager]: /getting-started/glossary/#pager diff --git a/content/en/methods/paginator/HasPrev.md b/content/en/methods/paginator/HasPrev.md new file mode 100644 index 00000000000..a757564e590 --- /dev/null +++ b/content/en/methods/paginator/HasPrev.md @@ -0,0 +1,29 @@ +--- +title: HasPrev +description: Reports whether there is a Pager object before the current Pager object. +categories: [] +keywords: [] +action: + related: + - /methods/paginator/First + - /methods/paginator/Last + - /methods/paginator/Next + - /methods/paginator/Prev + - /methods/paginator/HasNext + returnType: bool + signatures: [PAGINATOR.HasPrev] +--- + + + +{{< code file=layouts/partials/pagination.html >}} +{{ with .Paginator}} + {{ if .HasPrev }} + Previous + {{ end }} +{{ end }} +{{< /code >}} + +{{% include "methods/paginator/_common/pagination-template.md" %}} + +[pager]: /getting-started/glossary/#pager diff --git a/content/en/methods/paginator/Last.md b/content/en/methods/paginator/Last.md new file mode 100644 index 00000000000..43f94804701 --- /dev/null +++ b/content/en/methods/paginator/Last.md @@ -0,0 +1,27 @@ +--- +title: Last +description: Returns the last Pager object in the Pagers collection. +categories: [] +keywords: [] +action: + related: + - /methods/paginator/First + - /methods/paginator/Next + - /methods/paginator/Prev + - /methods/paginator/HasNext + - /methods/paginator/HasPrev + returnType: page.Pager + signatures: [PAGINATOR.Last] +--- + + + +{{< code file=layouts/partials/pagination.html >}} + {{ with .Last }} + Last + {{ end }} +{{< /code >}} + +{{% include "methods/paginator/_common/pagination-template.md" %}} + +[pager]: /getting-started/glossary/#pager diff --git a/content/en/methods/paginator/Next.md b/content/en/methods/paginator/Next.md new file mode 100644 index 00000000000..e523881c66b --- /dev/null +++ b/content/en/methods/paginator/Next.md @@ -0,0 +1,29 @@ +--- +title: Next +description: Returns the next Pager object in the Pagers collection. +categories: [] +keywords: [] +action: + related: + - /methods/paginator/First + - /methods/paginator/Last + - /methods/paginator/Prev + - /methods/paginator/HasNext + - /methods/paginator/HasPrev + returnType: page.Pager + signatures: [PAGINATOR.Next] +--- + + + +{{< code file=layouts/partials/pagination.html >}} +{{ with .Paginator}} + {{ with .Next }} + Next + {{ end }} +{{ end }} +{{< /code >}} + +{{% include "methods/paginator/_common/pagination-template.md" %}} + +[pager]: /getting-started/glossary/#pager diff --git a/content/en/methods/paginator/NumberOfElements.md b/content/en/methods/paginator/NumberOfElements.md new file mode 100644 index 00000000000..e24631d9861 --- /dev/null +++ b/content/en/methods/paginator/NumberOfElements.md @@ -0,0 +1,23 @@ +--- +title: NumberOfElements +description: Returns the number of Page objects in the current Pager object. +categories: [] +keywords: [] +action: + related: + - /methods/paginator/TotalNumberOfElements + returnType: int + signatures: [PAGINATOR.NumberOfElements] +--- + + + +{{< code file=layouts/partials/pagination.html >}} +{{ with .Paginator}} + +{{ end }} +{{< /code >}} + +{{% include "methods/paginator/_common/pagination-template.md" %}} + +[pager]: /getting-started/glossary/#pager diff --git a/content/en/methods/paginator/PageNumber.md b/content/en/methods/paginator/PageNumber.md new file mode 100644 index 00000000000..43096ccfe29 --- /dev/null +++ b/content/en/methods/paginator/PageNumber.md @@ -0,0 +1,22 @@ +--- +title: PageNumber +description: Returns the number of the current Pager object in the collection of Pager objects. +categories: [] +keywords: [] +action: + related: [] + returnType: int + signatures: [PAGINATOR.PageNumber] +--- + + + +{{< code file=layouts/partials/pagination.html >}} +{{ with .Paginator}} + +{{ end }} +{{< /code >}} + +{{% include "methods/paginator/_common/pagination-template.md" %}} + +[pager]: /getting-started/glossary/#pager diff --git a/content/en/methods/paginator/PageSize.md b/content/en/methods/paginator/PageSize.md new file mode 100644 index 00000000000..7d3caf9b82b --- /dev/null +++ b/content/en/methods/paginator/PageSize.md @@ -0,0 +1,22 @@ +--- +title: PageSize +description: Returns the maximum number of Page objects in each Pager object. +categories: [] +keywords: [] +action: + related: [] + returnType: int + signatures: [PAGINATOR.PageSize] +--- + + + +{{< code file=layouts/partials/pagination.html >}} +{{ with .Paginator}} + +{{ end }} +{{< /code >}} + +{{% include "methods/paginator/_common/pagination-template.md" %}} + +[pager]: /getting-started/glossary/#pager diff --git a/content/en/methods/paginator/Pagers.md b/content/en/methods/paginator/Pagers.md new file mode 100644 index 00000000000..38e46691863 --- /dev/null +++ b/content/en/methods/paginator/Pagers.md @@ -0,0 +1,22 @@ +--- +title: Pagers +description: Returns a collection of Pager objects. +categories: [] +keywords: [] +action: + related: [] + returnType: page.pagers + signatures: [PAGINATOR.Pagers] +--- + + + +{{< code file=layouts/partials/pagination.html >}} +{{ with .Paginator}} + +{{ end }} +{{< /code >}} + +{{% include "methods/paginator/_common/pagination-template.md" %}} + +[pager]: /getting-started/glossary/#pager diff --git a/content/en/methods/paginator/Pages.md b/content/en/methods/paginator/Pages.md new file mode 100644 index 00000000000..6a23488c356 --- /dev/null +++ b/content/en/methods/paginator/Pages.md @@ -0,0 +1,22 @@ +--- +title: Pages +description: Returns a collection of Page objects in the current Pager object. +categories: [] +keywords: [] +action: + related: [] + returnType: page.Pages + signatures: [PAGINATOR.Pages] +--- + + + +{{< code file=layouts/partials/pagination.html >}} +{{ with .Paginator}} + +{{ end }} +{{< /code >}} + +{{% include "methods/paginator/_common/pagination-template.md" %}} + +[pager]: /getting-started/glossary/#pager diff --git a/content/en/methods/paginator/Prev.md b/content/en/methods/paginator/Prev.md new file mode 100644 index 00000000000..f91a9eea5b8 --- /dev/null +++ b/content/en/methods/paginator/Prev.md @@ -0,0 +1,29 @@ +--- +title: Prev +description: Returns the previous Pager object in the Pagers collection. +categories: [] +keywords: [] +action: + related: + - /methods/paginator/First + - /methods/paginator/Last + - /methods/paginator/Next + - /methods/paginator/HasNext + - /methods/paginator/HasPrev + returnType: page.Pager + signatures: [PAGINATOR.Prev] +--- + + + +{{< code file=layouts/partials/pagination.html >}} +{{ with .Paginator}} + {{ with .Prev }} + Previous + {{ end }} +{{ end }} +{{< /code >}} + +{{% include "methods/paginator/_common/pagination-template.md" %}} + +[pager]: /getting-started/glossary/#pager diff --git a/content/en/methods/paginator/TotalNumberOfElements.md b/content/en/methods/paginator/TotalNumberOfElements.md new file mode 100644 index 00000000000..abfafd732a4 --- /dev/null +++ b/content/en/methods/paginator/TotalNumberOfElements.md @@ -0,0 +1,23 @@ +--- +title: TotalNumberOfElements +description: Returns the number of Page objects in all Pager objects. +categories: [] +keywords: [] +action: + related: + - /methods/paginator/NumberOfElements + returnType: int + signatures: [PAGINATOR.TotalNumberOfElements] +--- + + + +{{< code file=layouts/partials/pagination.html >}} +{{ with .Paginator}} + +{{ end }} +{{< /code >}} + +{{% include "methods/paginator/_common/pagination-template.md" %}} + +[pager]: /getting-started/glossary/#pager diff --git a/content/en/methods/paginator/TotalPages.md b/content/en/methods/paginator/TotalPages.md new file mode 100644 index 00000000000..43d9dc02f75 --- /dev/null +++ b/content/en/methods/paginator/TotalPages.md @@ -0,0 +1,22 @@ +--- +title: TotalPages +description: Returns the number of Pager objects. +categories: [] +keywords: [] +action: + related: [] + returnType: int + signatures: [PAGINATOR.TotalPages] +--- + + + +{{< code file=layouts/partials/pagination.html >}} +{{ with .Paginator}} + +{{ end }} +{{< /code >}} + +{{% include "methods/paginator/_common/pagination-template.md" %}} + +[pager]: /getting-started/glossary/#pager diff --git a/content/en/methods/paginator/URL.md b/content/en/methods/paginator/URL.md new file mode 100644 index 00000000000..66aebab25c6 --- /dev/null +++ b/content/en/methods/paginator/URL.md @@ -0,0 +1,22 @@ +--- +title: URL +description: Returns the relative URL of the current Pager object. +categories: [] +keywords: [] +action: + related: [] + returnType: string + signatures: [PAGINATOR.URL] +--- + + + +{{< code file=layouts/partials/pagination.html >}} +{{ with .Paginator}} + +{{ end }} +{{< /code >}} + +{{% include "methods/paginator/_common/pagination-template.md" %}} + +[pager]: /getting-started/glossary/#pager diff --git a/content/en/methods/paginator/_common/_index.md b/content/en/methods/paginator/_common/_index.md new file mode 100644 index 00000000000..47d5812fba5 --- /dev/null +++ b/content/en/methods/paginator/_common/_index.md @@ -0,0 +1,13 @@ +--- +cascade: + _build: + list: never + publishResources: false + render: never +--- + + diff --git a/content/en/methods/paginator/_common/pagination-template.md b/content/en/methods/paginator/_common/pagination-template.md new file mode 100644 index 00000000000..6f2a4e9015f --- /dev/null +++ b/content/en/methods/paginator/_common/pagination-template.md @@ -0,0 +1,7 @@ +--- +# Do not remove front matter. +--- + +See Hugo's [embedded pagination template] for a complete example of using this and other `Paginator` methods. + +[embedded pagination template]: {{% eturl pagination %}} diff --git a/content/en/methods/paginator/_index.md b/content/en/methods/paginator/_index.md new file mode 100644 index 00000000000..762104225c4 --- /dev/null +++ b/content/en/methods/paginator/_index.md @@ -0,0 +1,12 @@ +--- +title: Paginator methods +linkTitle: Paginator +description: Use these methods with a Paginator object. +categories: [] +keywords: [] +menu: + docs: + parent: methods +--- + +Use these methods with a Paginator object. diff --git a/content/en/templates/pagination.md b/content/en/templates/pagination.md index 0854a684476..3e00d815e5b 100644 --- a/content/en/templates/pagination.md +++ b/content/en/templates/pagination.md @@ -91,49 +91,9 @@ Without the `where` filter, the above example is even simpler: {{ end }} ``` -If you want to build custom navigation, you can do so using the `.Paginator` object, which includes the following properties: +If you want to build custom navigation, you can do so using the `Paginator` object, which provides the following methods: -PageNumber -: The current page's number in the pager sequence - -URL -: The relative URL to the current pager - -Pages -: The pages in the current pager - -NumberOfElements -: The number of elements on this page - -HasPrev -: Whether there are page(s) before the current - -Prev -: The pager for the previous page - -HasNext -: Whether there are page(s) after the current - -Next -: The pager for the next page - -First -: The pager for the first page - -Last -: The pager for the last page - -Pagers -: A list of pagers that can be used to build a pagination menu - -PageSize -: Size of each pager - -TotalPages -: The number of pages in the paginator - -TotalNumberOfElements -: The number of elements on all pages in this paginator +{{< list-pages-in-section path=/methods/paginator titlePrefix=. omitElementIDs=true >}} ## Additional information diff --git a/data/embedded_template_urls.toml b/data/embedded_template_urls.toml new file mode 100644 index 00000000000..7bb2e4eee00 --- /dev/null +++ b/data/embedded_template_urls.toml @@ -0,0 +1,36 @@ +# Used by the embedded template URL (eturl.html) shortcode. +# Quoted all keys because some are not valid identifiers. + +# BaseURL +'base_url' = 'https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates' + +# Templates +'alias' = 'alias.html' +'disqus' = 'disqus.html' +'google_analytics' = 'google_analytics.html' +'opengraph' = 'opengraph.html' +'pagination' = 'pagination.html' +'schema' = 'schema.html' +'twitter_cards' = 'twitter_cards.html' + +'robots' = '_default/robots.txt' +'rss' = '_default/rss.xml' +'sitemap' = '_default/sitemap.xml' +'sitemapindex' = '_default/sitemapindex.xml' + +# Render hooks +'render-image' = '_default/_markup/render-image.html' +'render-link' = '_default/_markup/render-link.html' +'render-codeblock-goat' = '_default/_markup/render-codeblock-goat.html' + +# Shortcodes +'figure' = 'shortcodes/figure.html' +'gist' = 'shortcodes/gist.html' +'highlight' = 'shortcodes/highlight.html' +'instagram' = 'shortcodes/instagram.html' +'param' = 'shortcodes/param.html' +'ref' = 'shortcodes/ref.html' +'relref' = 'shortcodes/relref.html' +'twitter' = 'shortcodes/twitter.html' +'vimeo' = 'shortcodes/vimeo.html' +'youtube' = 'shortcodes/youtube.html' diff --git a/layouts/shortcodes/eturl.html b/layouts/shortcodes/eturl.html new file mode 100644 index 00000000000..c0cf30aec7b --- /dev/null +++ b/layouts/shortcodes/eturl.html @@ -0,0 +1,36 @@ +{{- /* +Renders an absolute URL to the source code for an embedded template. + +Accepts either positional or named parameters, and depends on the +embedded_templates.toml file in the data directory. + +@param {string} filename The embedded template's file name, excluding extension. + +@returns template.HTML + +@example {{% et robots.txt %}} +@example {{% et filename=robots.txt %}} +*/}} + +{{- /* Get parameters. */}} +{{- $filename := "" -}} +{{- if .IsNamedParams -}} + {{- $filename = .Get "filename" -}} +{{- else -}} + {{- $filename = .Get 0 -}} +{{- end -}} + +{{- /* Render. */}} +{{- with $filename -}} + {{- with site.Data.embedded_template_urls -}} + {{- with index . $filename -}} + {{- urls.JoinPath site.Data.embedded_template_urls.base_url . -}} + {{- else -}} + {{- errorf "The %q shortcode was unable to find a URL for the embedded template named %q. Check the name. See %s" $.Name $filename $.Position -}} + {{- end -}} + {{- else -}} + {{- errorf "The %q shortcode was unable to find the embedded_template_urls data file in the site's data directory. See %s" $.Name $.Position -}} + {{- end -}} +{{- else -}} + {{- errorf "The %q shortcodes requires a named or positional parameter, the file name of the embedded template, excluding its extension. See %s" .Name .Position -}} +{{- end -}}