--- /dev/null
+---
+title: "BookStack Hacks"
+url: "/hacks"
+---
+Hacks for BookStack
\ No newline at end of file
--- /dev/null
++++
+title = "Applying Hacks"
++++
+
+
+The hacks provided on this part of the site generally fall into one of three types:
+
+- [Head HTML](#head-html)
+- [Visual Theme System](#visual-theme-system)
+- [Logical Theme System](#logical-theme-system)
+
+Some hacks may use a combination of these types.
+The type of hack required will be shown alongside any example code blocks.
+Detailed below are the steps required to use each type of hack.
+
+---
+
+### Head HTML
+
+Head HTML can simply be placed into the "Custom HTML Head Content" customization
+setting that's found within the BookStack interface.
+Just copy and paste the code into that setting box then press the save button below.
+Keep in mind that any code added won't be applied to when on the customization settings page. This is to ensure you can access the page to remove code in the event of an issue.
+
+If there's already code in the "Custom HTML Head Content" customization
+setting box, you can usually create a new line and add your code below.
+
+---
+
+### Visual Theme System
+
+The visual theme system is used to override and add templates, text and icons within BookStack.
+Use of the visual theme system requires access to the BookStack host system to edit and create files.
+Ideally you'd have some PHP & HTML knowledge to be able to maintain and customize your hacks as required.
+
+- [Getting Started Video](https://www.youtube.com/watch?v=gLy_2GBse48)
+- [Developer Info](https://github.com/BookStackApp/BookStack/blob/development/dev/docs/visual-theme-system.md)
+
+To use this you'll first need to follow the [Theme Folder Setup](#theme-folder-setup) section below to have an active theme folder at the ready.
+
+For any visual theme files you need to apply, simply create them relative to your theme folder path. For example, if the hack I need to apply is labelled `common/parts/header.blade.php`, and my theme folder is at `themes/custom` within my BookStack instance, I'd create the directory `common` within my theme folder, then create a `parts` directory within that, then copy the code into a `header.blade.php` file within that.
+
+In the event you already have a file at the required theme folder path, things become a little tricky since as the files would need to be carefully merged, ideally by a developer familiar with the code and languages in use.
+
+---
+
+### Logical Theme System
+
+The logical theme system is used to extend BookStack system functionality.
+Use of the logical theme system requires access to the BookStack host system to edit and create files.
+Ideally you'd have some PHP knowledge to be able to maintain and customize your hacks as required.
+
+- [Getting Started Video](https://www.youtube.com/watch?v=YVbpm_35crQ)
+- [Developer Info](https://github.com/BookStackApp/BookStack/blob/development/dev/docs/logical-theme-system.md)
+
+To use this you'll first need to follow the [Theme Folder Setup](#theme-folder-setup) section below to have an active theme folder at the ready.
+
+Most logical theme hacks will make use of a `functions.php` file.
+This simple represents a `functions.php` that needs to exist directly within
+your theme folder.
+
+For other files you need to apply, simply create them relative to your theme folder path. For example, if the hack I need to apply is labelled `includes/spanner.php`, and my theme folder is at `themes/custom` within my BookStack instance, I'd create the directory `includes` within my theme folder, then copy the code into a `spanner.php` file within that.
+
+In the event you already have a file at the required theme folder path, things become a little tricky since as the files would need to be carefully merged, ideally by a developer familiar with the code and languages in use.
+
+---
+
+### Theme Folder Setup
+
+A theme folder needs to be set-up when using either the logical or visual theme system. To achieve this, create a folder for your theme within your BookStack themes directory. As an example we'll use `custom` as our theme name, so we'd create a `themes/custom` folder. You then need to tell BookStack to use your theme via the `APP_THEME` option in your .env file. For example: `APP_THEME=my_theme`.
+
+And that's it set-up! You now have a theme folder ready to be used.
\ No newline at end of file
--- /dev/null
+<?php
+
+use BookStack\Actions\ActivityType;
+use BookStack\Entities\Models\Book;
+use BookStack\Entities\Models\Chapter;
+use BookStack\Entities\Models\Page;
+use BookStack\Facades\Theme;
+use BookStack\Theming\ThemeEvents;
+
+/**
+ * Auto-sort the contents of the given book.
+ * This sorts in name order, ascending, with chapters first.
+ */
+function autoSortBook(Book $book) {
+ $chapters = $book->chapters()->orderBy('name', 'asc')->get(['id', 'priority']);
+ $pages = $book->pages()->orderBy('name', 'asc')
+ ->where('draft', '=', false)
+ ->get(['id', 'priority']);
+ $chapterCount = $chapters->count();
+
+ foreach ($chapters as $index => $chapter) {
+ $chapter->priority = $index;
+ $chapter->save();
+ }
+
+ foreach ($pages as $index => $page) {
+ $page->priority = $chapterCount + $index;
+ $page->save();
+ }
+}
+
+// Listen to the activity logged theme event to run our custom logic
+Theme::listen(ThemeEvents::ACTIVITY_LOGGED, function (string $type, $detail) {
+
+ // The activity events we're triggering sort upon.
+ $sortActivityTypes = [
+ ActivityType::PAGE_CREATE,
+ ActivityType::PAGE_UPDATE,
+ ActivityType::CHAPTER_CREATE,
+ ActivityType::CHAPTER_UPDATE,
+ ];
+
+ // The name of the book-level tag which indicates auto-sort should run.
+ // Set to empty string ('') to run for all books.
+ $tagName = 'autosort';
+
+ // If it's one of our activity types, correctly tagged, run the auto-sort logic
+ if (in_array($type, $sortActivityTypes) && ($detail instanceof Page || $detail instanceof Chapter)) {
+ $book = $detail->book;
+ if (empty($tagName) || $book->tags()->where('name', '=', $tagName)->exists()) {
+ autoSortBook($detail->book);
+ }
+ }
+
+});
\ No newline at end of file
--- /dev/null
++++
+title = "Autosort Tagged Books"
+author = "@ssddanbrown"
+date = 2023-01-23T20:00:00Z
+updated = 2023-01-23T20:00:00Z
+tested = "v22.11.1"
++++
+
+
+This is a hack to BookStack to enable auto-sorting of book chapters and pages upon page or chapter create/update. It sorts by name, ascending, with chapters first. By default it will run for any book with an `Autosort` tag assigned.
+
+#### Options
+
+Customize the tag name, if desired, by tweaking the string at around line 45. Set this to empty to run for all books.
+
+#### Code
+
+{{<hack file="functions.php" type="logical">}}
--- /dev/null
+<script>
+document.addEventListener('DOMContentLoaded', function() {
+ const links = document.querySelectorAll('.page-content a');
+ for (const link of links) {
+ links[i].target = '_blank';
+ }
+});
+</script>
\ No newline at end of file
--- /dev/null
++++
+title = "Force Page Content Links to Open in New Tabs"
+author = "@ssddanbrown"
+date = 2023-01-27T00:00:00Z
+updated = 2023-01-27T00:00:00Z
+tested = "v22.11.1"
++++
+
+This hack will force HTML links, within the main content body of a page, to
+open in a new tab.
+
+#### Considerations
+
+This works via JavaScript, so is not assured to run since a user could have
+JavaScript disabled although this is relatively rare.
+
+#### Code
+
+{{<hack file="head.html" type="head">}}
--- /dev/null
+<p class="callout info">
+ Please login using the email provided by Barry during your induction.
+</p>
\ No newline at end of file
--- /dev/null
++++
+title = "Custom Login Form Message"
+author = "@ssddanbrown"
+date = 2023-01-27T00:00:00Z
+updated = 2023-01-27T00:00:00Z
+tested = "v22.11.1"
++++
+
+This logical theme system hack allows you to show a custom message on the login form, above the inputs and below the title.
+
+Change the contents of the file to suit your desired message.
+
+#### Code
+
+{{<hack file="auth/parts/login-message.blade.php" type="visual">}}
projects / hacks / commitdiff