Feature/enhanced columns

[binarystargames]

Added a "ratio" feature to columns shortcode. Code sample/execution:

{{< flexcolumns ratio="3:7" >}}
**Sunrod**<br/>
*Bomb, At-Will, Standard*<br/>
*Spend 1 Reagent*
<--->
<br/>
Make an attack vs PD on 1d3+1 nearby targets.

*Hit:* The target takes radiant damage equal to your level and is Dazed (11+ save ends).

*Miss:* The target is Dazed until the start of your next turn.

*Special:* You may partially activate this as a free action (including outside of combat) to create light twice as bright as a torch for about an hour. While still lit, you may throw it to use the Bomb ability as above (it flares up and then stops working on contact).

{{< /flexcolumns >}}

This code becomes: https://binarystar.games/docs/36th-way/classes/list-of-classes/alchemist/#1st-level

---

I've also got a CSS rule locally to flatten columns to vertical when hugo-book gets rid of the side TOC/menu because the default hugo-book ones look not great at low width. I left it out for now but it's an option.

[michaeltlombardi]

Looking over this, I wonder if this isn't worth contributing back upstream to hugo-book directly as it's explicitly an enhancement of their shortcode. If we file an issue with them to enhance the columns shortcode with the ratio parameter, I think that will be strictly better for everyone.

If they reject the feature request / implementation, I think we can instead incorporate this as {{ flex-columns }} or something; I think the changeset for this is (without refactoring) too large to feasibly keep patched if the upstream implementation changes. That being said, this file does not seem to update often; 3 patches since implementation, only one since 2020.

[binarystargames]

Makes sense. I'll see if I have the energy to look into their requested process sometime this week.

[michaeltlombardi]

If you want, I'm happy to go ahead and file the issue and link to your prototype here - I really do think this is a great improvement over the upstream shortcode and hugely useful for folks!

[binarystargames]

That would be very appreciated!

[michaeltlombardi]

@binarystargames I think the upstream maintainer is unlikely to merge your contribution to the upstream. Instead of having to maintain our own implementation on top of theirs, can this be reworked to be a new shortcode called flexcolumns? And then we can document it and just have it be an extension here instead.

[binarystargames]

Yep, I can do that.

[binarystargames]

Added a commit that does just that, updated the overview example. I implemented it locally on my site, so that example link is current - that's using the new {{< flexcolumns ratio="3:7" >}} situation.

[binarystargames]

Secondary question: while I'm working on columns, how do you feel about adding a parameter to flatten them whenever the sidebar disappears? We can certainly leave it to CSS to handle too, which is what I'm currently doing for my site. Not sure how you feel about one implementation vs. the other.

[michaeltlombardi]

Secondary question: while I'm working on columns, how do you feel about adding a parameter to flatten them whenever the sidebar disappears? We can certainly leave it to CSS to handle too, which is what I'm currently doing for my site. Not sure how you feel about one implementation vs. the other.

I think having a shortcode parameter like "flattenInMobileView" would be very useful - if people want more control over the presentation, they can ignore that parameter flag and implement their own CSS, but I don't think that's the majority of our target audience.

[binarystargames]

Done.

To accomplish this, I also added platen.scss injected via inject/head.html (because I suspect to do at least a few of the things on that issues tracker we'll want somewhere to put this kind of stuff). Let me know if you'd rather I separate that out to another PR or something.

By default it uses default columns behavior, but including flattenInMobileView="true" adds the flattening. (I added it to Sunrod and Tanglefoot Bag from the initial demo link and nothing else so you can see the difference: https://binarystar.games/docs/36th-way/classes/list-of-classes/alchemist/#1st-level )

[michaeltlombardi]

Overall, this looks great! One minor note unrelated to the code, for this project if we can use rebase to update the working branch instead of merging upstream/main into it, that would be preferable - it helps keep the git history a little neater to follow.

It might also be possible to rebase and combine the first four commits into one - I think this work is really comprised of two chunks: Adding the new shortcode and extending the head injection.

Otherwise the implementation looks great and I'm stoked about this!

[binarystargames]

Made a few changes as prescribed:

• Moved the inject out of head to baseof because we're already altering that from hugo-book.
• Refactored flexcolumns,html for improved readability/to use better tools as demonstrated

Definitely happy to rebase rather than merge in directly whenever this looks good.

[michaeltlombardi]

Commenting here to remind myself:

I have come across this pattern a couple of times now, and I think it's probably worth defining a partial for ourselves so we can reference an SCSS style link injection via something like

{{ partial "platen/GetScssLink" "platen.scss" }}

I've been using some utils partials over in toroidal - it turns out partials can be used to return values instead of writing text into a file, so that might be useful.

[binarystargames]

Yeah, we used a similar value return with a partial with platen/getCssClass for class injection in baseof.

[michaeltlombardi]

Some thoughts, suggestions, and questions. Also worth considering: if there are error conditions, can we handle those explicitly with the errorf function to give our users (who may not be technical at all) more helpful information than hugo's default when a template breaks?

[michaeltlombardi]

Okay, this looks great! I think the only dangling (non-blocking) questions are:

• is if there's any sensible error handling we can use here - maybe to check the ratio string specified, make sure that it's numbers separated by colons?
• can the flattenInMobileView parameter be a direct boolean instead of a string?

[binarystargames]

sensible error handling

It's hard to believe, but this is actually pretty robust in that regard. The reason for this is how poorly formed CSS works: flex-grow:(not a number/empty) just doesn't get processed and falls back to flex-grow:1.

At that same Alchemist link, you can see examples of:

• Needleburst: ratio="3::7"
• Immunity Shot: ratio="3:"
• Vitalizing Draught: ratio=":7
• Leadbody: ratio="3:a"
• Sliptongue: ratio="a:3"
• Incendiary Paste: ratio="3"
• Snake Venom: ratio="a"

The last two broke without a check for ":" so I've included a colon check. In all of the other cases, it just fell back to 1.

can the flattenInMobileView parameter be a direct boolean instead of a string?

Sure can! The following now work:

• {{< flexcolumns ratio="3:7" flattenInMobileView=true >}}
• {{< flexcolumns "3:7" true >}}

[michaeltlombardi]

Okay! That all makes sense and this looks great! Two minor fixes to the docs and my last (🤞🏻) question: With the way flex-grow works, I'm wondering if we should warn when people submit an invalid ratio - probably just a single warning message like "Hey this ratio is invalid, we're going to fall back on an even ratio" and maybe include an option to treat the warning as an error.

I couldn't quickly find the docs on turning warnings into errors, but I did find how folks can suppress an error. Not blocking for this PR, I'll merge tonight or tomorrow either way.