Brew Themes

[calculuschild]

Swappable brew themes will allow users to change documents from PHB style to MM, DMG, non-WOTC styles, and eventually custom and shared styles from other users.

Built-in Themes

We already have the capability to live-swap style sheets (we do this to change between Legacy and V3), and we could get away with simply adding more styles to that list and swap them in a similar way. However, as the list of Theme grow, there are more special cases such as unique snippets, fonts, image resources, etc. that we may also need to consider part of the Theme. Hence, I propose that Themes consist of a set of multiple files linked together:

Theme 1 (i.e. DMG)/
 ├─ Settings.json	 : V3 or Legacy, Creator credit, Base Theme
 │                         (i.e. DMG is built on PHB, so default to Base Theme behavior where not defined)
 ├─ Styles.less		 : Relevant CSS
 ├─ Snippets.json        : List of snippets specific to this Theme. May overwrite snippets of Base Style
 └─ Widgets.json         : List of editor widgets, as proposed in #1870 
                           (i.e., "if this line has '{{monster', show checkbox to add/remove 'frame' class")
Theme 2/

Theme 3/

Fonts/
 ├─ Font1.woff2
 └─ Font2.woff2

Assets/
 ├─ Inkstain1.woff2
 └─ Inkstain2.woff2

The widgets.json might have a structure similar to the following. Clicking on a line that matches the prefix would signal to CodeMirror to pop up some widget (a color picker, checkboxes, number entry boxes, etc.):

{
  name         : 'monster',
  prefix       : '{{monster',
  widgets :  [
    {
      name : 'frame',
      type : checkBox,
      text : 'frame'
    },
    {
      name : backgroundColor,
      type : colorPicker,
      text : background-color:
    },
    {
      name : positionX,
      type : slider,
      text : left:
    }
  ]
}

However, getting Widgets doesn't necessarily need to come in the first release of this. That's a bonus feature that will be filled out afterward via #1870. It's just important to see how it will fit into the file structure.

Themes would be selected via a dropdown menu in the Metadata tab of the Current Brew that the user is currently editing, preferably with some sort of image preview while hovering over options, including perhaps a "blank" theme with no CSS applied at all except for page sizes and basic column behavior for those who want to fully build a theme from scratch in their Style tab. Any styles a user has in their "style" tab will be applied over the top of the selected theme as normal.

Custom Themes

The next step would be to include an additional item in the dropdown menu of "Custom". This would reveal a textbox where the user can paste in the share link to another brew (referred to as the "Theme Brew" below), which will then use that brew's Style tab as the base Theme. Styling would be layered with priority as follows (later items override previous items):

1. "Blank" theme which defines universal basic features like default page size, column breaks, wide, italics and bold, etc.
2. Base Theme (if any) defined in the settings.json of the theme selected in the Theme Brew (e.g., PHB)
3. Any changes applied over the Base Theme in styles.less of the Selected Theme (e.g., DMG)
4. Additional styles specified in the Theme Brew's style tab.
5. Additional styles defined in the Current Brew's style tab.

Note that we might need to prevent or limit how many layers deep Theme Brews can go depending on performance.

Future work might add an additional menu to the editor for custom snippets. This may be in the form of a simple fillable form with a button name and the example text to produce. Likely should not allow custom JS here as that opens up potential for malicious code being shared. As with the CSS, snippets in this format would override/merge with snippets of lower Themes.

Minimal Viable Product

I think as a first release, the minimal viable product can simply be:

• Have two more themes
  • One built from the existing PHB (DMG? created by /u/AeronDrake on reddit) (See New Template: DM Guild style guide #1339) (c
  • One totally new (@Gazook89 's "journal" style?) (See Reddit)
• Themes are organized into folders with
  • style.less
  • settings.json with at minimum the renderer and Base Theme defined.
  • snippets.js so each theme can have its own snippets (unless they are identical to the Base Theme, then not needed)
• Interface to select theme
  • Dropdown menu in the brew Metadata panel
  • Greyed out when Renderer is Legacy.
  • Themes selection is saved into the brew metadata
  • Preview images when hovering over a theme

Thoughts?

[Gazook89]

Just for reference, here is the Journal theme that is mentioned. And I have no problem with it being included, nothing needed beyond the 'creator credit' in that settings.json file (and even that I don't really care about, but I guess if it's there I'll take it especially if it can be used as an example for future theme files).

[G-Ambatte]

This might be more appropriate as a general snippet, or included as a theme-specific snippet, but the recently released Dragon of Icespire Peak free preview has double-sided half page NPC cards on pages 11 through 16, which I personally think look great. I'm not sure if similar NPC cards have appeared in any other supplements or resources.

I have included images of one here to demonstrate exactly what I'm talking about:

Front:

Back:

This does seem like something that could be replicated in Homebrewery without too much difficulty.

[calculuschild]

Alright, so snippets.json probably needs to be snippets.js so it can contain generator functions for more complicated snippets similar to the current snippets files. ....although that does complicate things for users defining their own snippets eventually as part of a Theme Brew; I'm not keen on allowing user-made themes to have access to executable javascript.

Perhaps.... our built-in themes use a .js file for our convenience, but (eventual) user-generated Theme Brews still are limited to JSON, or even some kind of entry form that is stored as JSON?

[calculuschild]

We also need to handle #1437 before allowing custom styles.

[G-Ambatte]

We also need to handle #1437 before allowing custom styles.

I've pushed a PR with a fix for #1437 now.

[G-Ambatte]

Some further investigation has found that while this stops <script> and </script> tags from appearing in the content, these tags break React when they are passed as props. Saving </script> in a brew's Style text prevents that brew from ever being opened successfully in EditPage or SharePage; saving </script> to a brew's Content text breaks UserPage as well.

Adding a prop sanitization function to template.js stops all of this from breaking, at the cost of changing any <script or </script> tags in the props. However, as I don't believe that there is a genuine reason for any user to have these tags in their brews, this is not a great loss.

[Gazook89]

Just noticed that the Old Journal theme has a box-shadow on the pages, which shows a little goofy since the pages do not have straight edges. Additionally, pages have filter:drop-shadow() which I think looks nice, but that flattens the page into a single image, making text unselectable in the PDF print, right?

I'm not sure what is the best compromise on this. I could edit the original asset to include a bit of drop-shadow so it's baked into the image.

I have this fuzzy idea that the .page should just have a background image that is a portion of the total journal page, with straight edges. And the "ragged edge" is some element outside of the page. When the brew is sent to print/PDF, the ragged edge is dropped and only the inner portion of the page is sent. So the ragged edges are only seen when viewing the brew online. But I haven't spent a second actually thinking about this.

[5e-Cleric]

I see this project lacks the task 'Preview images when hovering over a theme', is this still the case? If so, i have the time to build some simple previews.

[calculuschild]

Yeah that would be nice if you are up for it. I'm thinking just like a single page that shows most of the components (titles, tables, various boxes, etc. as if it were a normal page in a book. Then we just show it popping up at like 1/4 size when you hover over the button.

[5e-Cleric]

With all tasks completed, now the matter is keeping track of all the different themes that we might add:

D&D related themes

• PHB
• DMG
• MM
• XGtE
• TCE
• VGM (Volo's guide to monsters)
• MOoT (Mythic Odisseys of Theros)
• ERftLW (Eberron: Rising from the Last War)
• TWBTW (The Wild Beyond The Witch Light)
• CoS (Curse of Strahd)
• ID:RotF (Icewind Dale: Rime of the Frostmaiden)

• 3.5e Theme
• 4e Theme
• AD&D 2e Monstrous Compendium Reddit post

Other themes (Gazook's Themes really)

• Journal
• Pathfinder
• Cards
• 13th Age Reddit post
• Savage Worlds Reddit post

[dbolack-ab]

A couple of thoughts on Custom Themes. These aren't first-release critical, but something to be considered for ongoing work.

There needs to be a capacity for fonts, art assets, and a license to be attached to user-based custom themes. Possibly snippets as well. This supports the notion of the publisher's official themes without tying them to the Homebrewery license.

[G-Ambatte]

An extension to Themes might be Theme versioning, to lock brews to a specific version of the styling.

I imagine that this would work by a dropdown in the Metadata Editor, which lists all available versions of the currently selected theme. The style data itself could consist of a list of completed CSS files that are created during the build process from the LESS + diff files; using diffs should allow the changes between versions to be more easily identified.

---

This is relatively simple in scope, but complicated to implement. Ideally, Themes will be more mature before we start adding features like this to it.

[5e-Cleric]

#3227 will track Pathfinder 2e theme

[5e-Cleric]

With custom themes already here, the lacking functionality is to use other people's brews for it.

Talk on Gitter chat is about using a favourites system for this.

[TheYellowArchitect]

With this implemented, Homebrewery is ideal for any tabletop game and system.
That said, as an end-user using Homebrewery for yet another TRPG, I would like to request a guide on how to make new themes, e.g. #2804

[dbolack-ab]

With this implemented, Homebrewery is ideal for any tabletop game and system. That said, as an end-user using Homebrewery for yet another TRPG, I would like to request a guide on how to make new themes, e.g. #2804

I have the start of a guide here https://homebrewery.naturalcrit.com/share/36qyHG4Skvq2

The guide presently excludes CSS advice, which I suspect is more what you may be looking for at this stage?

[5e-Cleric]

I believe Kaiburr is working on a guide as well, not sure about the overlap potential.

[TheYellowArchitect]

With this implemented, Homebrewery is ideal for any tabletop game and system. That said, as an end-user using Homebrewery for yet another TRPG, I would like to request a guide on how to make new themes, e.g. #2804

I have the start of a guide here https://homebrewery.naturalcrit.com/share/36qyHG4Skvq2

The guide presently excludes CSS advice, which I suspect is more what you may be looking for at this stage?

The abovementioned guide covers the usage of existing themes (except the last header which isn't detailed)
My request is making a guide on how to make a brand new theme, like, which files need to change, how to link the theme to images, json details etc
I ask this because this feature is very powerful - a game changer if you will - but there isn't any documentation how to make one (aside of cloning #2804 and trying to understand how it works in the code)

[ericscheid]

There are two ways themes can be deployed...

1. they get added to THB code base, via github. Just like [NEW THEME]: Tasha's Cauldron for Everything (TCE) #2804.
2. an author styles up a THB brew document, with all the necessary styles and font linkings in the brew's style editor. The share link for this brew would then be selected as the theme to apply to an author's own brew.

The former assumes the work for the latter has also been done, and does possibly allow for additional snippets to be installed when the theme is selected. We anticipate most user contributed themes will be via the second method.

[dbolack-ab]

I've done a little updating on https://homebrewery.naturalcrit.com/share/36qyHG4Skvq2, but I'm a little to close to the subject to spot omissions.