structural_pages/docs/DESIGN.md

Site Structure - Design Document

Overview

The site_structure module implements a hierarchical editorial structure and contextual navigation for institutional sites in Drupal 11. The module was designed for higher education institutions but is generic enough for other institutional contexts.

Problem

In Drupal, content is added in a flat manner (non-hierarchical), and menus are traditionally used to organize content into hierarchical structures. This creates user experience problems because content editors typically do not have permission to administer menus.

Solution

The module implements two complementary structures:

1. Taxonomic Structure (primary): Organization based on hierarchical taxonomy vocabulary
2. Parent-Child Structure (subsidiary): Direct hierarchy between pages for specific cases, supporting multiple entity types as parents

---

Conceptual Model

┌─────────────────────────────────────────────────────────────────────┐
│  PRIMARY STRUCTURE: site_section Taxonomy                           │
│                                                                     │
│  - Governs the overall organization of site information             │
│  - Defines breadcrumbs and URLs (via Pathauto)                      │
│  - Example: Undergraduate > Courses > Software Engineering          │
│  - Applied to content type: section_page                            │
├─────────────────────────────────────────────────────────────────────┤
│  SUBSIDIARY STRUCTURE: Parent-Child (field_parent_page)             │
│                                                                     │
│  - For specific cases: manuals, guides, sequential documentation    │
│  - Provides contextual navigation (Child pages View)                │
│  - Automatically inherits site section from parent (node/taxonomy)  │
│  - For user/group parents, context is the entity itself             │
│  - Applied to content type: content_page                            │
│  - Supports multiple parent types: content_page, section_page,      │
│    taxonomy terms, users, groups (configurable)                     │
├─────────────────────────────────────────────────────────────────────┤
│  page (core Drupal)                                                 │
│                                                                     │
│  - Remains untouched for generic use                                │
└─────────────────────────────────────────────────────────────────────┘

---

Components

1. Taxonomy Vocabulary: site_section

Property	Value
Machine name	site_section
Name	Site Section
Hierarchical	Yes
Description	Main hierarchical structure for site organization

Usage: This vocabulary defines site sections. Terms can be nested to create hierarchies (e.g., "Undergraduate" > "Courses" > "Engineering").

2. Content Type: section_page

Property	Value
Machine name	section_page
Name	Section Page
Description	Pages organized by site section

Fields:

Field	Type	Required	Cardinality	Description
title	String	Yes	1	Page title (core)
body	Text (formatted, long, with summary)	No	1	Page content
field_site_section	Entity reference (taxonomy)	Yes	1	Site section

3. Content Type: content_page

Property	Value
Machine name	content_page
Name	Content Page
Description	Pages with hierarchical parent-child structure

Fields:

Field	Type	Required	Cardinality	Description
title	String	Yes	1	Page title (core)
body	Text (formatted, long, with summary)	No	1	Page content
field_parent_page	Dynamic entity reference	No	1	Parent entity (configurable types)
field_site_section	Entity reference (taxonomy)	Conditional	1	Site section (inherited or manual)

Rules for field_site_section in content_page:

• If field_parent_page points to a taxonomy_term: uses the term itself as site section
• If field_parent_page points to a node: inherits field_site_section from parent
• If field_parent_page is empty (root page): must be filled manually

4. Dynamic Parent Reference

The field_parent_page uses the Dynamic Entity Reference module to support multiple entity types as parents. This is configurable via the admin interface.

Default allowed targets:

• node:content_page - Other content pages
• node:section_page - Section pages
• taxonomy_term:site_section - Site section terms
• user:user - User accounts
• group:* - All group types (requires Group module)

Context behavior by parent type:

• Node/Taxonomy: Content pages inherit field_site_section from the parent
• User: Content pages are associated with the user profile page (/user/{id}). The field_site_section is cleared as the context is the user itself.
• Group: Content pages are associated with the group. The field_site_section is cleared as the context is the group itself.

Configuration: /admin/config/local-modules/site-structure

5. Inheritance Logic

Implemented via hook_entity_presave():

When a content_page is saved:
    IF field_parent_page is filled:
        IF parent is user or group:
            Clear field_site_section (context is the entity itself)
        ELSE IF parent is taxonomy_term (site_section):
            Set field_site_section to the parent term ID
        ELSE IF parent is node with field_site_section:
            Copy field_site_section from parent node
    ELSE:
        Validate that field_site_section was filled manually

Additional validations:

• Prevent self-reference (page cannot be parent of itself)
• Prevent circularity (A → B → C → A) - only for node parents

6. Breadcrumb Builder

Custom service that overrides Drupal's default breadcrumb for section_page and content_page.

Logic:

1. Determine the root parent context by traversing the parent chain
2. Build breadcrumb based on context type:
   • User context: Home > User Name > Parent Nodes > Current Page
   • Group context: Home > Group Name > Parent Nodes > Current Page
   • Taxonomy context: Home > Term Hierarchy > Parent Nodes > Current Page
3. For content_page, also add node parents to the breadcrumb

Examples:

• Page "Chapter 1" has parent "User Guide" which is a section_page in "Documentation"
  • Breadcrumb: Home > Documentation > User Guide > Chapter 1
• Page "My Notes" has parent user "John Doe"
  • Breadcrumb: Home > John Doe > My Notes
• Page "Meeting Minutes" has parent group "Research Team"
  • Breadcrumb: Home > Research Team > Meeting Minutes

7. Pathauto Tokens

Custom token for hierarchical URL generation.

Token	Description	Example
[node:site-section-path]	Path based on taxonomy hierarchy	undergraduate/courses

Suggested URL pattern: [node:site-section-path]/[node:title]

Result: /undergraduate/courses/software-engineering

8. View: child_pages

View that lists child pages of the current content_page.

Property	Value
Display	Block
Filter	field_parent_page = Current node ID (contextual)
Sort	Title (A-Z) or weight (if implemented)
Usage	Sidebar navigation in guides/manuals

9. Settings Form

Configuration form at /admin/config/local-modules/site-structure that allows administrators to:

• Select which node bundles can be used as parents
• Select which taxonomy vocabularies can be used as parents
• Changes automatically update the field configuration

---

File Structure

site_structure/
├── site_structure.info.yml              # Metadata and dependencies
├── site_structure.module                # Hooks (presave, tokens)
├── site_structure.install               # Installation hooks
├── site_structure.services.yml          # Service registration
├── site_structure.routing.yml           # Route definitions
├── site_structure.links.menu.yml        # Admin menu links
│
├── config/
│   ├── install/
│   │   ├── site_structure.settings.yml  # Default settings
│   │   ├── taxonomy.vocabulary.site_section.yml
│   │   │
│   │   ├── node.type.section_page.yml
│   │   ├── field.storage.node.field_site_section.yml
│   │   ├── field.field.node.section_page.field_site_section.yml
│   │   ├── core.entity_form_display.node.section_page.default.yml
│   │   ├── core.entity_view_display.node.section_page.default.yml
│   │   │
│   │   ├── node.type.content_page.yml
│   │   ├── field.storage.node.field_parent_page.yml  # dynamic_entity_reference
│   │   ├── field.field.node.content_page.field_parent_page.yml
│   │   ├── field.field.node.content_page.field_site_section.yml
│   │   ├── core.entity_form_display.node.content_page.default.yml
│   │   ├── core.entity_view_display.node.content_page.default.yml
│   │   │
│   │   ├── pathauto.pattern.section_page.yml
│   │   ├── pathauto.pattern.content_page.yml
│   │   ├── pathauto.pattern.site_section_term.yml
│   │   │
│   │   └── views.view.child_pages.yml
│   │
│   └── schema/
│       └── site_structure.schema.yml    # Config schema
│
├── translations/
│   └── pt-br.po                         # Portuguese (Brazil) translation
│
├── src/
│   ├── Breadcrumb/
│   │   └── SectionBreadcrumbBuilder.php
│   │
│   └── Form/
│       └── SiteStructureSettingsForm.php
│
└── docs/
    └── DESIGN.md                        # This document

---

Dependencies

Core Modules (Drupal 11)

• node
• taxonomy
• views
• field
• text
• user

Contrib Modules

• token - For custom tokens
• pathauto - For automatic URL generation
• dynamic_entity_reference - For multi-type parent references

Optional Modules

• group - For group entity support as parent type

---

Editor Workflow

Creating a Section Page (section_page)

1. Navigate to Content > Add content > Section Page
2. Fill in title and body
3. Select the appropriate site section
4. Save
5. URL and breadcrumb are generated automatically

Creating a Content Page (content_page)

1. Create root page (anchored to taxonomy term):

   • Add content > Content Page
   • In "Parent Page", select a site_section term
   • Site section is set automatically from the term
   • Save

2. Create root page (anchored to section_page):

   • Add content > Content Page
   • In "Parent Page", select a section_page
   • Site section is inherited from the section_page
   • Save

3. Create child pages:

   • Add content > Content Page
   • In "Parent Page", select another content_page
   • Site section is inherited automatically
   • Save

4. The child pages View appears automatically on parent pages

---

Administration

Configuring Allowed Parent Types

1. Navigate to /admin/config/local-modules/site-structure
2. Select which content types (nodes) can be used as parents
3. Select which taxonomy vocabularies can be used as parents
4. Save configuration
5. Field configuration is updated automatically

---

Group Integration

The module supports the Group module for content organization:

• Content pages can have groups as parent entities
• When a content_page has a group as parent, the context is the group itself
• Breadcrumbs show: Home > Group Name > Parent Nodes > Current Page
• field_site_section is cleared for group-parented content (context is the group)
• Per-section permissions can be implemented via Groups

Configuration: Enable group types in the settings form at /admin/config/local-modules/site-structure

---

Installation Verification

1. drush en site_structure -y
2. Verify vocabulary at /admin/structure/taxonomy
3. Verify content types at /admin/structure/types
4. Create test hierarchical terms
5. Create section_page and verify breadcrumb/URL
6. Create root content_page with taxonomy term as parent
7. Create child content_page, verify inheritance
8. Verify child pages View
9. Test settings form at /admin/config/local-modules/site-structure

---

Changelog

Version	Date	Description
1.0.0	-	Initial version
1.1.0	-	Added dynamic_entity_reference support for multi-type parents
1.2.0	-	Added user and group entity support as parent types