Hmmm… I think to myself I need a public space to bemoan my struggles with development…someplace where unprofessional banter won’t serve as a stain on my personal record
DAYS LATER…
WAIT. I’m literally working on a website designed to encourage creative works in a casual register.
Cool. This is my dev journal topic now.
It will not be useful.
THE BUTTON
Note to self: You spent a good 5-10 minutes looking up notation for the new bbcode you installed. Maybe you should make some documentation for that?
I know very little about development. Well…I know more than I did a couple of months ago, but my level of knowledge hasn’t really graduated beyond: bang things together until something works.
I have told many students that “frustration is when you’re learning the fastest”. Citation needed, but hot dang my learning must be on hyperdrive when it comes to web development. Don’t tell me otherwise, I need the placating comfort of “well I probably learned something” after days of no progress on a problem.
…the button is that problem…
…the button is also every problem…
Let’s talk about the button.
Discourse is a massive sprawling open source forum project, it has an active developer community and, in theory, has a lot of customization ability. And I don’t mean “customization” like the sliders in a character creator. “Oh wow! I have 15 ways to tweak this character’s schnoz.” It’s more like “I want to delete the schnoz entirely, now lets replace that with a new organ that looks like dragonfly wings and it helps organize your thoughts, but is only visible to the first person who walks into a room.”
The schnoz is a metaphor…it is also the button.
[I spent 30 minutes trying to get stable diffusion to construct my visual instead of trying to come up with a better metaphor…Stable diffusion really likes putting noses on faces.]
Anyway, this level customization is only actually available if you are dev enough to ride. It is better than needing to build everything up from scratch, but I’m not sure by how much.
Which is great, because default discourse formatting is trash for collaborative storytelling and Forum Adventures.
Why is it trash? Well, mainly because a typical long-form forum adventure involves a few, highly detailed author posts, followed by several, less consequential reader posts. For the structure of the adventure, individual author posts are more important than posts made by readers, but discourse treats the first post as the most important, and everything else is subject to the infinite scroll. This is not ideal for readers or authors. Updates can get lost in the scroll. Sidebars and chat windows can distract from the story being told. If the reader to author post ratio gets particularly skewed, then it could be impossible to find a particular post or update on a re-reading or reviewing of the adventure.
What many authors have figured out is that the ideal adventure format is that of the blog. A dedicated webpage where authors control the theming around their story, and reader input is relegated to a comments section (if any).
Why authors shouldn’t just all go to a full blog format is a different topic, involving community and embracing the collaborative nature of storytelling. For now though, it’s evident enough that bringing in elements from the blog structure can go a long way to making discourse a more forum adventure friendly place.
So let’s make a button.
This button will do something very simple. The button will show up at the end of every update post made by the author of an adventure and link to the next post by the author.
Now discourse has a few layers of modifications you can use to make things like this happen. The first are css plugins. You can add some css instructions to change the website formatting and remove elements that you don’t want.
See how the sidebar doesn’t have a list of all the possible tags you could search? And how that looks, way cleaner than if half of it was full of cluttered random tag terms? That’s a simple css display: none statement. One line of code, plugin complete.
You can also add javascript and html to the site in various locations…This becomes a little more complicated because there’s a lot of html and javascript running this website. How do you know what the code you write will have access to? When will it run? Why do people keep telling me to read through basic tutorials when I ask these questions? It’s a mystery.
Now you can use this javascript to access the [trumpet] Discourse Plugin API [/trumpet]. This allows you to write select code that will be fed into Discourse (when? how? who knows?) and then produce the desired result!
Swell! Turns out there is a handy function called “AddPostMenuButton” which adds a button to the set of buttons that live just after each post. WOW! How convenient, that is exactly what I want to do!, I think to myself, over a week ago.
So the documentation for the plugin api is in the discourse code. And the documentation for this particular method says:
/**
* Add a new button below a post with your plugin.
*
* The `callback` function will be called whenever the post menu is rendered,
* and if you return an object with the button details it will be rendered.
*
* Example:
*
* ```
* api.addPostMenuButton('coffee', () => {
* return {
* action: 'drinkCoffee',
* icon: 'coffee',
* className: 'hot-coffee',
* title: 'coffee.title',
* position: 'first' // can be `first`, `last` or `second-last-hidden`
* };
* });
* ```
**/
addPostMenuButton(name, callback) {
apiExtraButtons[name] = callback;
addButton(name, callback);
}
Nods yes yes. Now…Which of these things is the button?
…
Hours of reading code and guess and check later I can summarize.
action: is the function called whenever the button is pushed - More on this later.
icon: is the image shown on the menu. How does it know what image it is? Well there is a secret discourse style guide that is only accessible by going to beagle-time.com/styleguide AFTER enabling an option in the massive settings menu. (you can go check it out yourself - I have left it accessible to whoever is interested.)
className: For longer that I’d like to admit, I thought this was some kind of file javascript “class” that contained the object of the button. Turns out it’s just the flavor text for the css/html to let me identify it.
title: I still do not know how this is different than the class option.
position: this one is where it lives in the bar. I think that these are not the only three options…I could be wrong.
So good news! I can now make a button appear! Problem solved!
… The button does nothing, also it appears on every post in the entire forum.
That’s fine. I am fine with this, problem solving is all about expanding on incremental gains.
So how do I make the button do a thing? That is where “action” comes in.
Maybe there is a better way to visualize this, but my mental model tells me that calling addPostMenuButton puts a button…object (it’s not really a full object but lets treat it like one for now) in the same scope as the “Post-Menu” (the thing what holds all those buttons). This means that in order for it to perform an “action” the action has to be visible, somehow to the Post-Menu.
Scrawling through documentation gives us another api function: attachWidgetAction.
So the Post-Menu (and apparently most things in Discourse) are called “Widgets” or small chunks of loaded javascript that can update and operate separately from the rest of the site to improve load times. So by calling attachWidgetAction, I can send a new function/action to the PostMenu that my new button can use.
What grand thing to I want my button to do? Maybe update a link? send me to the next post? No. Because at this point I have spent hours/days combing and cobbling through code to get some basic functionality. I want my button to just tell me that it exists: console.log(this);
the button code loads, it displays, I press it, and in the developer console I see…
“Undefined”
And that…that is a victory. It did a thing. In doing a thing, did told me that it had no idea what it was, but it was able to do that, as opposed to nothing. Which is maybe also a metaphor for myself. I am the button.
I won’t go into the following days project of trying to get the button to know where or what it is, other than the ending discovery where a 4 comment long discourse topic from 2016 where someone asked about the api and was told to not use “FAT ARROW” notation. Apparently, I only knew Fat Arrow notation. I didn’t know other notations existed. I didn’t know it was called fat arrow.
My button does not use fat arrow anymore, and my button can now see EVERYTHING…maybe…it sees a lot of stuff.
So currently, I have a button, it is showing up on the right places, and maybe it will eventually do what I want it to. Maybe, after I have made the button, I too will be able to see a lot of stuff, and making newer better buttons will not be such an arduous slog. I will get better at making buttons, and perhaps all the things around them.
And then we can all get back to whatever it is we want to do here.
Oh also
