Added page-include-tag-value hack

2025-08-16 12:42:20 +01:00 · 2025-08-16 12:42:20 +01:00 · 102518bb66
commit 102518bb66
parent 9ba2dbaebe
2 changed files with 58 additions and 0 deletions
--- a/content/page-include-tag-value/functions.php
+++ b/content/page-include-tag-value/functions.php
@ -0,0 +1,25 @@
+<?php 
+  
+use BookStack\Entities\Models\Page; 
+use BookStack\Facades\Theme; 
+use BookStack\Theming\ThemeEvents; 
+  
+// Listen to page include parsing events  
+Theme::listen(ThemeEvents::PAGE_INCLUDE_PARSE, function (string $tagReference, string $replacementHTML, Page $currentPage, ?Page $referencedPage) { 
+  
+ // Allow default behaviour for non-tag-based includes  
+ if (!str_starts_with($tagReference, '0tag:')) { 
+ return null; 
+ } 
+  
+ // Get the target tag name from the include reference  
+ $tagName = explode(':', $tagReference)[1]; 
+  
+ // Fetch the tag value from the page, parent chapter, or parent book  
+ $tagValue = $currentPage->tags()->where('name', '=', $tagName)->first()?->value ?? 
+ $currentPage->chapter?->tags()->where('name', '=', $tagName)->first()?->value ?? 
+ $currentPage->book?->tags()->where('name', '=', $tagName)->first()?->value ?? ''; 
+  
+ // Return the tag value to be used for the include  
+ return $tagValue; 
+}); 
--- a/content/page-include-tag-value/index.md
+++ b/content/page-include-tag-value/index.md
@ -0,0 +1,33 @@
+++ 
+title = "Tag Values in Page Content via Includes" 
+author = "@ssddanbrown" 
+date = 2025-08-16T00:00:00Z 
+updated = 2025-08-16T00:00:00Z 
+tested = "v25.07.1" 
+++ 
+  
+This hack allows you to dynamically pull in the value of tags into page content, via customizing how [page include tags](/docs/user/reusing-page-content/#include-tags) are parsed.  
+This hack will attempt to use tags on the page itself, then look to the parent chapter (if existing), then the parent book's tags. 
+  
+#### Usage 
+  
+Within page content, insert [an include tag](/docs/user/reusing-page-content/#include-tags) with the following specific format: 
+  
+```text 
+{{@0tag:<tag-name>}} 
+``` 
+  
+Replacing `<tag-name>` with the name of your intended tag. The tag lookup is performed case-insensitive, so don't worry about correct casing. The hack will then replace the include tag with the value of any relevant tags found, or otherwise blank out the include tag. 
+  
+As an example, if I had a tag with name `Color` and value `Blue`, I'd use the include tag `{{@0tag:color}}` which will be replaced with `Blue` (using the tag value) when the page is shown. 
+  
+#### Considerations 
+  
+- This is subject to many of the same limitations as page includes, so the values won't show in things like preview snippets. 
+- This implementation does not consider permissions/access to parent chapter/book for tag values, so values may be used from chapters/books which the user does not have access to view. 
+- Tag name matching is case-insensitive. 
+  
+  
+#### Code 
+  
+{{<hack file="functions.php" type="logical">}}