BookStack Code Mirror - hacks/blob - content/applying.md

   1 +++
   2 title = "Applying Hacks"
   3 +++
   4
   5
   6 The hacks provided on this part of the site generally fall into one of three types:
   7
   8 - [Head HTML](#head-html)
   9 - [Visual Theme System](#visual-theme-system)
  10 - [Logical Theme System](#logical-theme-system)
  11
  12 Some hacks may use a combination of these types.
  13 The type of hack required will be shown alongside any example code blocks.
  14 Detailed below are the steps required to use each type of hack.
  15
  16 ---
  17
  18 ### Head HTML
  19
  20 Head HTML can simply be placed into the "Custom HTML Head Content" customization
  21 setting that's found within the BookStack interface.
  22 Just copy and paste the code into that setting box then press the save button below.
  23 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.
  24
  25 If there's already code in the "Custom HTML Head Content" customization
  26 setting box, you can usually create a new line and add your code below.
  27
  28 ---
  29
  30 ### Visual Theme System
  31
  32 The visual theme system is used to override and add templates, text and icons within BookStack.
  33 Use of the visual theme system requires access to the BookStack host system to edit and create files.
  34 Ideally you'd have some PHP & HTML knowledge to be able to maintain and customize your hacks as required.
  35
  36 - [Getting Started Video](https://www.youtube.com/watch?v=gLy_2GBse48)
  37 - [Developer Info](https://github.com/BookStackApp/BookStack/blob/development/dev/docs/visual-theme-system.md)
  38
  39 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.
  40
  41 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.
  42
  43 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.
  44
  45 ---
  46
  47 ### Logical Theme System
  48
  49 The logical theme system is used to extend BookStack system functionality.
  50 Use of the logical theme system requires access to the BookStack host system to edit and create files.
  51 Ideally you'd have some PHP knowledge to be able to maintain and customize your hacks as required.
  52
  53 - [Getting Started Video](https://www.youtube.com/watch?v=YVbpm_35crQ)
  54 - [Developer Info](https://github.com/BookStackApp/BookStack/blob/development/dev/docs/logical-theme-system.md)
  55
  56 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.
  57
  58 Most logical theme hacks will make use of a `functions.php` file.
  59 This simple represents a `functions.php` that needs to exist directly within
  60 your theme folder.
  61
  62 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.
  63
  64 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.
  65
  66 ---
  67
  68 ### Theme Folder Setup
  69
  70 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`.
  71
  72 And that's it set-up! You now have a theme folder ready to be used.