hugo/docs/content/en/methods/page/IsDescendant.md
2023-12-04 15:24:01 +01:00

2.5 KiB

title description categories keywords action
IsDescendant Reports whether PAGE1 in a descendant of PAGE2.
related returnType signatures
methods/page/Ancestors
methods/page/CurrentSection
methods/page/FirstSection
methods/page/InSection
methods/page/IsAncestor
methods/page/Parent
methods/page/Sections
bool
PAGE1.IsDescendant PAGE2

{{% include "methods/page/_common/definition-of-section.md" %}}

With this content structure:

content/
├── auctions/
│   ├── 2023-11/
│   │   ├── _index.md
│   │   ├── auction-1.md
│   │   └── auction-2.md
│   ├── 2023-12/
│   │   ├── _index.md
│   │   ├── auction-3.md
│   │   └── auction-4.md
│   ├── _index.md
│   ├── bidding.md
│   └── payment.md
└── _index.md

When rendering the "auctions" page:

{{ with .Site.GetPage "/" }}
  {{ $.IsDescendant . }} → true
{{ end }}

{{ with .Site.GetPage "/auctions" }}
  {{ $.IsDescendant . }} → false
{{ end }}

{{ with .Site.GetPage "/auctions/2023-11" }}
  {{ $.IsDescendant . }} → false
{{ end }}

{{ with .Site.GetPage "/auctions/2023-11/auction-2" }}
  {{ $.IsDescendant . }} → false
{{ end }}

In the examples above we are coding defensively using the with statement, returning nothing if the page does not exist. By adding an else clause we can do some error reporting:

{{ $path := "/auctions/2023-11" }}
{{ with .Site.GetPage $path }}
  {{ $.IsDescendant . }} → true
{{ else }}
  {{ errorf "Unable to find the section with path %s" $path }}
{{ end }}

Understanding context

Inside of the with block, the context (the dot) is the section Page object, not the Page object passed into the template. If we were to use this syntax:

{{ with .Site.GetPage "/auctions" }}
  {{ .IsDescendant . }} → true
{{ end }}

The result would be wrong when rendering the "auction-1" page because we are comparing the section page to itself.

{{% note %}} Use the $ to get the context passed into the template. {{% /note %}}

{{ with .Site.GetPage "/auctions" }}
  {{ $.IsDescendant . }} → true
{{ end }}

{{% note %}} Gaining a thorough understanding of context is critical for anyone writing template code. {{% /note %}}