This guest post was written by Laura Charles Johnson, MadCap Flare Advanced Developer and Trainer, and a MadCap Flare user since version 1. Ms. Johnson’s favorite responsibility is to turn new Flare users into power Flare users.
Tools used:
- MadCap Flare 2024r2
- Sublime
- Chrome Developer Tools
- Microsoft Copilot
- HTML5 output
I have a confession to make. I’ve used Flare since The Beginning. So, I know a lot about it... not everything… but a lot. Throughout my Flare journey, I’ve enjoyed learning HTML and the absolute magic of CSS. CSS is my jam, my happy place.
What I know about JavaScript:
- It’s not nearly as neat and tidy as CSS or HTML
- It can add tags and CSS that don’t exist in the topic’s code in Flare
- Plays well with Flare
And this is super important. I know enough about JavaScript to know what it does and that I need it. I don’t know the same about Python, for example. Because of that, I don’t know how it could help me with Flare. My point here is that I know enough about JavaScript to know how to ask the right-ish question, implement it in Flare, and test it until it works.
And here’s the confession: I don’t know JavaScript. We aren’t friends… we’re barely civil to each other. The Universe knows, I’ve tried. Years and years of trying… and I feel like I’ve made no forward progress. It’s like this unknowable thing that mocks me when I try to understand it. I know that there are special terms like ‘prepend’ and ‘append’ - I mean, any word nerd worth their salt can appreciate a code base that uses ‘prepend.’
So, this leaves me at a disadvantage when it comes to JavaScript. If I were in an office, I could bribe pay a software engineer with baked goods and I’d have a script in a couple of hours. But I’m not - so I either have to find someone on Fiverr who can write the script for me (and I’ve done that) or I beg someone who is unlucky enough to reply to a text from me.
The other day, I was working on a large FrameMaker to Flare migration project with hundreds of topics… and I needed to create a 2-column table with n number of rows out of a set of p tags with alternating classes that looked like this:
And I wanted it to look like this, minus the purple and green. I added that in CodePen to make sure I was working on the correct tags.
It is important to note that the list was always immediately after <h2>Parameters</h2>.
I simply cannot go through 305 topics (Find All FTW) and build tables and move everything into the tables. Uh, no.
The good news here? I had the CSS all ready to go.
And it worked.
I had previously used display:flex to create a series of columns - and I had code for that, and it worked but just barely. Display:grid would work much better and is CSS specifically designed to do what I wanted. One problem, unlike display:flex, display:grid content must be inside a container, a div tag. Again, I was not interested in going through and adding opening and closing div tags to each of the 305 instances.
That’s when I realized I needed some JavaScript to wrap each instance in a div tag. UGH.
In a moment of brilliance, I realized I may not have to find someone to help. Maybe I could help myself with some AI. I’m on a Windows machine and it comes with Copilot, MS’s AI helper. Let’s see what it can do.
I opened Copilot and asked the following. (I’m showing my exact wording so you can see the query refinement over several iterations.)
And got this answer:
Um, wow! Could it really be this easy?!
Short answer: NO.
For those Flare folks out there that don’t use JavaScript at all, there are a few steps you must take to enable the code in Flare.
- Create a Scripts folder in Content/Resources.
- Use Sublime or other code editor to create a new .js file and put the ai-generated code in there. I called my file parameter-div.js.
- Put the .js file in the Scripts folder.
- Make a call to the .js file from the masterpage. See screenshot below.
- Build the project.
- Check the results.
I completed those steps and guess what? It did not work as planned. Did it do anything? Yes, it did. It put the content in a div and moved it to the end of the topic. See the highlighted content next to the blurred content.
Technically, it did what I asked. I just didn’t ask the right question. It’s about here that I realized that the specificity of the query is crucial to its success.
I asked Copilot about the ‘appendChild’ part specifically because I know that ‘append’ means ‘add as an attachment’ but in JavaScript, it’s even more narrowly defined. (Highlighting below is mine.)
The newly created div was created and appended to the end of the body tag. I suppose in the absence of guidance; JavaScript appends the new div to the end.
In addition to having the div in the wrong place, I realized I hadn’t asked Copilot to give the new div tag a class. I would need to apply properties to this div so a class was a requirement. I reworded the query to this:
The response:
Luckily, Copilot interpreted ‘make the name of the div’ as ‘assign the div the class of.’ I got what I wanted - but the whole div.parameters is still being appended to the end of the body tag. So I tried this query:
The response:
This is closer - but the vagueness of the location instruction, “in the original location in the file,” bothered me. I reworded to be more specific.
I got this. I’m a genius…here we go:
The results are underwhelming. This isn’t going as planned.
When I look in Chrome’s developer tools closer, there’s an error.
Here’s a thing about JavaScript, debugging it is a bear. Instead of spending a lot of time trying to figure this out (and failing), I asked Copilot what the error meant.
I thought the last part was quite telling. Why would Copilot put a non-standard and unsupported CSS selector in the code? I’ve learned a thing: don’t believe everything AI tells you. I liken it to my Dad: it will answer you, even if it doesn’t know the answer, and make it sound good. So good, you’ll believe it for years.
To deal with this: Test, test, test. Don’t take anything Copilot or ChatGPT or other AI tell you as truth, especially when it comes to code. I tested the code after every new iteration of the answer. This just follows my Flare Rule: change just one variable at a time when you’re troubleshooting.
But here’s the second part of the response:
I’m going to query Copilot again with as much specificity as I can based on everything I’ve learned from this conversation.
Notice how I changed the query to “...under the <h2> that contains the text “Parameters.”” This is similar but slightly more descriptive than just “...under <h2>Parameters</h2>.”
The response:
If you notice the last line of code, Copilot added an error message that will appear if no Parameters heading is found. That’s really a nice touch but I’m wondering if it will create chaos elsewhere. Let’s hope not.
Let’s take a look at the resulting build, the code the .js file added, and the CSS.
Did the error message Copilot added at the end cause problems? Thankfully, no.
Did AI work for me? Yes - but I realized that I knew enough about JavaScript to eventually get to the right answer. AND I knew how to implement it in Flare. Not sure if I could leverage AI with a language I know absolutely nothing about, like Python.
To see what I get, I queried Copilot about Python and Flare:
And the result:
To me, this answer is helpful - but I need to know that Python is the way to solve a problem statement. And I’m not anywhere close with Python. I also don’t know if Copilot is just making up an answer. Is that script correctly written? I have no idea.
I decided to ask Copilot what other code languages I should know that would allow me to extend my use of Flare. Here’s its response:
In the end, I used Copilot to get the JavaScript code I wanted with some lessons learned:
- You have to be somewhat familiar with the code you want help with or be willing to learn on the fly.
- Be as specific as you can, even if it sounds more than necessary
- Tools like Copilot or ChatGPT can really help but be skeptical of responses
- Test, test, test
If you try out ChatGPT or another AI tool to help you extend Flare, I’d love to hear about it.
