Best practices using javascript & local help pages

This forum is for all Flare issues related to the HTML5, WebHelp, WebHelp Plus, and Adobe Air Targets
Post Reply
Curlyshell
Propeller Head
Posts: 65
Joined: Fri Mar 01, 2019 9:14 am

Best practices using javascript & local help pages

Post by Curlyshell »

My company's software lets the customer define certain field labels for their UI. Call that MyTerms. Some MyTerms can be as different as apples and rainclouds—example: "worklist" for one customer and "patient" for another. In our user help, I hope to eventually add JavaScript to grab the customer-defined MyTerm from an API to populate their help pages with appropriate language. To ensure access, the user help will live on each customer's database server.

But the JavaScript component has to wait a few months. For now I was planning to create several targets based on Flare variable sets. (I know the range of possible MyTerm definitions, so I can create a few generic variable sets that will do.)

Would you say variable sets are the right place to start, as opposed to conditions or something else?

Would you say HTML5 is the right target, as opposed to Eclipse or something else?

Anything else I need to know NOW to prevent unnecessary effort later?

Thanks for any advice you can offer!
"I'm a technical writer, not a developer," she said...
devjoe
Sr. Propeller Head
Posts: 337
Joined: Thu Jan 23, 2014 1:43 pm

Re: Best practices using javascript & local help pages

Post by devjoe »

For what you are doing, variables are the way to go. They're going to provide the same basic functionality as your ultimate solution, except without the dynamic nature. You'll need one target for each set of MyTerms that you want to deliver (which may or may not be a separate one for each customer, depending on how many customers and how many terms and different combinations of terms you have). In each target's Variables tab you can define the value used for each variable in that target.

I will point out that if your terms are used in ways where you may have an article with each one, plurals, etc. that you may need multiple variables to cover all cases. For instance:
Fruit: apple, banana, peach
A_Fruit: an apple, a banana, a peach
Fruits: apples, bananas, peaches
Cap_Fruit: Apple, Banana, Peach
This is going to be the same issue in the javascript version. If you're only going to get a single value they enter for each term in the API, the best solution is to try to write your help so that you don't need these variations.
Curlyshell
Propeller Head
Posts: 65
Joined: Fri Mar 01, 2019 9:14 am

Re: Best practices using javascript & local help pages

Post by Curlyshell »

Thanks, @devjoe—I appreciate the confirmation!
I will point out that if your terms are used in ways where you may have an article with each one, plurals, etc. that you may need multiple variables to cover all cases.
Yes, I've anticipated that and will alter the text to make it as smooth as possible: no plurals, no a/an, etc.

SO grateful for MadCap Software Forums! I don't know where I'd be without you folks.
"I'm a technical writer, not a developer," she said...
NorthEast
Master Propellus Maximus
Posts: 6359
Joined: Mon Mar 05, 2007 8:33 am

Re: Best practices using javascript & local help pages

Post by NorthEast »

You could use variables, BUT that would mean you would have to build and supply a custom version of your help for each individual customer.

The customer will not be able to change these variables/terms themselves in the built output - you can only change the variables BEFORE you build the target output.

So it depends how you distribute your help. It'll only work if you supply help individually for each customer.
Curlyshell
Propeller Head
Posts: 65
Joined: Fri Mar 01, 2019 9:14 am

Re: Best practices using javascript & local help pages

Post by Curlyshell »

The customer will not be able to change these variables/terms themselves in the built output - you can only change the variables BEFORE you build the target output.
Thanks @DavidLee, in this stage of the development, I will produce just a few different targets using these variables to change key terms.

Later, my hope is to substitute the variables for a bit of JavaScript that calls those terms from an API, which will contain the customer's particular set of MyTerms.

Disclaimer: I don't know JavaScript but my development team has plenty of expertise. They think this can be done but have no experience with Flare.

Gratefully,

Shelley
"I'm a technical writer, not a developer," she said...
Post Reply