From: Dan Brown <redacted>
Date: Sun, 12 Feb 2023 22:53:28 +0000 (+0000)
Subject: Added license and hacks from gists
X-Git-Url: http://source.bookstackapp.com/hacks/commitdiff_plain/d38fb806ad772b173d562018730d058e87024c29

Added license and hacks from gists
---

diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..b8e7b0e
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Dan Brown and the BookStack Project contributors.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
\ No newline at end of file
diff --git a/content/notify-favourited-pages/functions.php b/content/notify-favourited-pages/functions.php
new file mode 100644
index 0000000..955b9bf
--- /dev/null
+++ b/content/notify-favourited-pages/functions.php
@@ -0,0 +1,57 @@
+<?php
+
+use BookStack\Actions\ActivityType;
+use BookStack\Auth\User;
+use BookStack\Entities\Models\Page;
+use BookStack\Facades\Theme;
+use BookStack\Notifications\MailNotification;
+use BookStack\Theming\ThemeEvents;
+use Illuminate\Notifications\Messages\MailMessage;
+
+// This customization notifies page-updates via email to users that have marked
+// that updated page as a favourite.
+
+// This notification class represents the notification that'll be sent to users.
+// The text of the notification can be customized within the 'toMail' function.
+class PageUpdatedNotification extends MailNotification {
+
+    protected Page $page;
+    protected User $updater;
+
+    public function __construct(Page $page, User $updater)
+    {
+        $this->page = $page;
+        $this->updater = $updater;
+    }
+
+    public function toMail($notifiable)
+    {
+        return (new MailMessage())
+            ->subject('BookStack page update notification')
+            ->line("The page \"{$this->page->name}\" has been updated by \"{$this->updater->name}\"")
+            ->action('View Page', $this->page->getUrl());
+    }
+}
+
+// This function does the work of sending notifications to the relevant users that have
+// marked the given page as a favourite.
+function notifyThoseThatHaveFavouritedPage(Page $page) {
+    // Find those we need to notify, and find the current updater of the page
+    $userIds = $page->favourites()->pluck('user_id');
+    $usersToNotify = User::query()->whereIn('id', $userIds)
+        ->where('id', '!=', $page->updated_by)
+        ->get();
+    $updater = User::query()->findOrFail($page->updated_by);
+
+    // Send a notification to each of the users we want to notify
+    foreach ($usersToNotify as $user) {
+        $user->notify(new PageUpdatedNotification($page, $updater));
+    }
+}
+
+// Listen to page update events and kick-start our notification logic
+Theme::listen(ThemeEvents::ACTIVITY_LOGGED, function(string $type, $detail) {
+    if ($type === ActivityType::PAGE_UPDATE && $detail instanceof Page) {
+        notifyThoseThatHaveFavouritedPage($detail);
+    }
+});
diff --git a/content/notify-favourited-pages/index.md b/content/notify-favourited-pages/index.md
new file mode 100644
index 0000000..4005db3
--- /dev/null
+++ b/content/notify-favourited-pages/index.md
@@ -0,0 +1,23 @@
++++
+title = "Notify Updates for Favourited pages"
+author = "@ssddanbrown"
+date = 2022-12-01T20:00:00Z
+updated = 2022-12-01T20:00:00Z
+tested = "v22.11"
++++
+
+
+This hack sends out page update notification emails to all users that have marked that page as a favourite.
+
+#### Considerations
+
+- The sending of emails may slow down page update actions, and these could be noisy if a user edits a page many times quickly. 
+- You may run into email system rate-limits with the amount of emails being sent.
+
+#### Options
+
+- You can customize the email message, if desired, by editing the lines of text within the toMail part at around lines 30-32 of the `functions.php` code.
+
+#### Code
+
+{{<hack file="functions.php" type="logical">}}
diff --git a/content/notify-tagged-page-updates/functions.php b/content/notify-tagged-page-updates/functions.php
new file mode 100644
index 0000000..bdf6ff9
--- /dev/null
+++ b/content/notify-tagged-page-updates/functions.php
@@ -0,0 +1,89 @@
+<?php
+
+use BookStack\Actions\ActivityType;
+use BookStack\Actions\Tag;
+use BookStack\Auth\Role;
+use BookStack\Auth\User;
+use BookStack\Entities\Models\Page;
+use BookStack\Facades\Theme;
+use BookStack\Notifications\MailNotification;
+use BookStack\Theming\ThemeEvents;
+use Illuminate\Notifications\Messages\MailMessage;
+
+// This customization notifies page updates to users within roles named via a tag  on a parent book.
+// For example, If a tag, with name `Notify` and value `Admins, Viewers` is applied to a book, updates to pages within
+// will be notified via email to all users within the "Admins" and "Viewers" roles.
+// Note: This is not officially supported, may break upon update, and the email sending may slow down operations.
+//       Also, users could be spammed with emails on repeated updates.
+//       Also, might hit email system rate-limits.
+//       Also, this relies on role names being stable.
+
+// This notification class represents the notification that'll be sent to users.
+// The text of the notification can be customized within the 'toMail' function.
+class PageUpdatedNotification extends MailNotification {
+
+    protected Page $page;
+    protected User $updater;
+
+    public function __construct(Page $page, User $updater)
+    {
+        $this->page = $page;
+        $this->updater = $updater;
+    }
+
+    public function toMail($notifiable)
+    {
+        return (new MailMessage())
+            ->subject('BookStack page update notification')
+            ->line("The page \"{$this->page->name}\" has been updated by \"{$this->updater->name}\"")
+            ->action('View Page', $this->page->getUrl());
+    }
+}
+
+// This function does the work of sending notifications to the
+// relevant users that are in roles denoted by a tag on the parent book.
+function notifyRequiredUsers(Page $page) {
+
+    // Get our relevant tag
+    /** @var ?Tag $notifyTag */
+    $notifyTag = Tag::query()
+        ->where('entity_type', '=', 'book')
+        ->where('entity_id', '=', $page->book_id)
+        ->where('name', '=', 'notify')
+        ->first();
+    if (!$notifyTag) {
+        return;
+    }
+
+    // Get the roles named via the tag
+    $roleNames = array_filter(array_map(fn($str) => trim($str) , explode(',', $notifyTag->value)));
+    $roleIds = Role::query()->whereIn('display_name', $roleNames)->pluck('id');
+    if (count($roleNames) === 0 || $roleIds->isEmpty()) {
+        return;
+    }
+
+    // Get the users we want to notify, and the user that updated the page
+    $usersToNotify = User::query()
+        ->whereExists(function($query) use ($roleIds) {
+             $query->select('user_id')
+                 ->from('role_user')
+                 ->whereColumn('users.id', '=', 'role_user.user_id')
+                 ->whereIn('role_id', $roleIds);
+        })
+        ->where('id', '!=', $page->updated_by)
+        ->get();
+    $updater = User::query()->findOrFail($page->updated_by);
+
+    // Send a notification to each of the users we want to notify
+    foreach ($usersToNotify as $user) {
+        $user->notify(new PageUpdatedNotification($page, $updater));
+        usleep(100000); // Slight 0.1s delay to help rate limit abuse
+    }
+}
+
+// Listen to page update events and kick-start our notification logic
+Theme::listen(ThemeEvents::ACTIVITY_LOGGED, function(string $type, $detail) {
+    if ($type === ActivityType::PAGE_UPDATE && $detail instanceof Page) {
+        notifyRequiredUsers($detail);
+    }
+});
\ No newline at end of file
diff --git a/content/notify-tagged-page-updates/index.md b/content/notify-tagged-page-updates/index.md
new file mode 100644
index 0000000..b9ccc1d
--- /dev/null
+++ b/content/notify-tagged-page-updates/index.md
@@ -0,0 +1,24 @@
++++
+title = "Notify Page Updates for Tagged Books"
+author = "@ssddanbrown"
+date = 2022-12-01T20:00:00Z
+updated = 2022-12-01T20:00:00Z
+tested = "v22.11"
++++
+
+
+This allows you to configure notifications to be sent to users within roles defined via tags applied to parent books.
+For example, if a tag with name `Notify` and value `Admins, Viewers` is applied to a book, updates to pages within will be notified via email to all users within the "Admins" and "Viewers" roles.
+
+#### Considerations
+
+- The sending of emails may slow down page update actions, and these could be noisy if a user edits a page many times quickly. 
+- You may run into email system rate-limits with the amount of emails being sent.
+
+#### Options
+
+- You can customize the email message, if desired, by editing the lines of text within the toMail part at around lines 36-39 of the `functions.php` code.
+
+#### Code
+
+{{<hack file="functions.php" type="logical">}}
diff --git a/content/simple-page-rss-feed/functions.php b/content/simple-page-rss-feed/functions.php
new file mode 100644
index 0000000..2616737
--- /dev/null
+++ b/content/simple-page-rss-feed/functions.php
@@ -0,0 +1,14 @@
+<?php
+
+use BookStack\Entities\Models\Page;
+use Illuminate\Support\Facades\Route;
+
+Route::get('/rss/pages/new', function() {
+    $pages = Page::query()
+        ->visible()
+        ->orderBy('created_at', 'desc')
+        ->take(25)
+        ->get();
+
+    return response()->view('rss', ['pages' => $pages], 200, ['Content-Type' => 'text/xml']);
+});
\ No newline at end of file
diff --git a/content/simple-page-rss-feed/index.md b/content/simple-page-rss-feed/index.md
new file mode 100644
index 0000000..27e9647
--- /dev/null
+++ b/content/simple-page-rss-feed/index.md
@@ -0,0 +1,25 @@
++++
+title = "Simple Latest Pages RSS Feed"
+author = "@ssddanbrown"
+date = 2023-02-12T20:00:00Z
+updated = 2023-02-12T20:00:00Z
+tested = "v22.11.1"
++++
+
+
+This is a hack to add a simple latest-page RSS feed to the BookStack using the logical theme system. A YouTube video covering the build and use of this customization [can be found here](https://www.youtube.com/watch?v=VYyyvaZTs_4).
+
+#### Considerations
+
+This does not take into account access control at all or enforce login, the RSS data endpoint will be publicly accessible. The code will effectively use the permissions of the "Guest" user.
+
+#### Options
+
+- The `25` in `functions.php` controls the count of rss feed items to show.
+- `created_at` in `functions.php` can be changed to `updated_at` to instead reflect the latest updated pages.
+
+#### Code
+
+{{<hack file="functions.php" type="logical">}}
+
+{{<hack file="rss.blade.php" type="visual">}}
diff --git a/content/simple-page-rss-feed/rss.blade.php b/content/simple-page-rss-feed/rss.blade.php
new file mode 100644
index 0000000..5198355
--- /dev/null
+++ b/content/simple-page-rss-feed/rss.blade.php
@@ -0,0 +1,18 @@
+<?xml version="1.0"?>
+<rss version="2.0">
+   <channel>
+      <title>Latest BookStack Pages</title>
+      <link>{{ url('/') }}</link>
+      <description>Latest pages in our BookStack instance</description>
+      <lastBuildDate>{{ date(DATE_RSS) }}</lastBuildDate>
+      @foreach($pages as $page)
+        <item>
+            <title>{{ $page->name }}</title>
+            <link>{{ $page->getUrl() }}</link>
+            <description>{{ $page->getExcerpt() }}</description>
+            <pubDate>{{ $page->created_at->format(DATE_RSS) }}</pubDate>
+            <guid>page#{{ $page->id }}</guid>
+        </item>
+      @endforeach
+   </channel>
+</rss>
\ No newline at end of file
diff --git a/content/username-login/auth/parts/login-form-standard.blade.php b/content/username-login/auth/parts/login-form-standard.blade.php
new file mode 100644
index 0000000..41bac68
--- /dev/null
+++ b/content/username-login/auth/parts/login-form-standard.blade.php
@@ -0,0 +1,37 @@
+<form action="{{ url('/https/source.bookstackapp.com/login') }}" method="POST" id="login-form" class="mt-l">
+    {!! csrf_field() !!}
+
+    <div class="stretch-inputs">
+        <div class="form-group">
+            <label for="email">{{ trans('auth.username') }}</label>
+            @include('form.text', ['name' => 'username', 'autofocus' => true])
+            @if($errors->has('email'))
+                <div class="text-neg text-small">{{ $errors->first('email') }}</div>
+            @endif
+        </div>
+
+        <div class="form-group">
+            <label for="password">{{ trans('auth.password') }}</label>
+            @include('form.password', ['name' => 'password'])
+            <div class="small mt-s">
+                <a href="{{ url('/https/source.bookstackapp.com/password/email') }}">{{ trans('auth.forgot_password') }}</a>
+            </div>
+        </div>
+    </div>
+
+    <div class="grid half collapse-xs gap-xl v-center">
+        <div class="text-left ml-xxs">
+            @include('form.custom-checkbox', [
+                'name' => 'remember',
+                'checked' => false,
+                'value' => 'on',
+                'label' => trans('auth.remember_me'),
+            ])
+        </div>
+
+        <div class="text-right">
+            <button class="button">{{ Str::title(trans('auth.log_in')) }}</button>
+        </div>
+    </div>
+
+</form>
\ No newline at end of file
diff --git a/content/username-login/functions.php b/content/username-login/functions.php
new file mode 100644
index 0000000..0b75935
--- /dev/null
+++ b/content/username-login/functions.php
@@ -0,0 +1,19 @@
+<?php
+
+use BookStack\Facades\Theme;
+use BookStack\Theming\ThemeEvents;
+use Illuminate\Http\Request;
+
+const EMAIL_DOMAIN = 'admin.com';
+
+Theme::listen(ThemeEvents::WEB_MIDDLEWARE_BEFORE, function(Request $request) {
+
+    // Transform a "username" on login request to an email input with pre-determined domain
+    if ($request->path() === 'login' && $request->method() === 'POST') {
+        $username = $request->input('username', '');
+        if ($username) {
+            $request->request->remove('username');
+            $request->request->add(['email' => $username . '@' . EMAIL_DOMAIN]);
+        }
+    }
+});
\ No newline at end of file
diff --git a/content/username-login/index.md b/content/username-login/index.md
new file mode 100644
index 0000000..7c4c3c8
--- /dev/null
+++ b/content/username-login/index.md
@@ -0,0 +1,25 @@
++++
+title = "Username-based Login"
+author = "@ssddanbrown"
+date = 2022-11-25T20:00:00Z
+updated = 2022-11-25T20:00:00Z
+tested = "v22.10"
++++
+
+This is a hack to BookStack, using the theme system, so that login presents itself as a username.
+Upon login attempt, this will match to a user of `<username>@<configured-domain>` within the database.
+
+#### Considerations
+
+- This assumes all users in your BookStack instance shares the same email domain.
+- This overrides a large part of the login form so be extra aware this will be overriding any default changes to BookStack upon updates.
+
+#### Options
+
+- Change the `EMAIL_DOMAIN` variable on line 7 of `functions.php` to be the common email domain used in your BookStack instance.
+
+#### Code
+
+{{<hack file="functions.php" type="logical">}}
+
+{{<hack file="auth/parts/login-form-standard.blade.php" type="visual">}}