Plain ol' pop-ups

This forum is for all Flare issues related to the HTML5, WebHelp, WebHelp Plus, and Adobe Air Targets
Post Reply
chuck_agari
Sr. Propeller Head
Posts: 225
Joined: Wed May 30, 2018 2:40 pm

Plain ol' pop-ups

Post by chuck_agari »

I'm trying to figure out if this can be done in Flare. I've found some positively ancient walkthroughs on the MadCap site (from 2102!) that show how this is done, but it shows pop-ups without all the extra Flare machinations, but still all the browser chrome. I want less, like this:
pop-up_help.png
This has a bare-bones border (with a tiny arrow showing what it's connected to), and it disappears when you click on the page anywhere outside the pop-up.

I'm asking because our developers have created some pretty massive pop-ups. While informative and useful, I don't want to duplicate the content in the documentation, and summarizing it in the docs doesn't make sense either. We're pushing for a "one source of truth" content repository, and getting this content out of the code and into Flare means that it can be re-used.

I looked through the brand-spankin'-new "micro content" functionality (which seems to be not much more than reworked snippets, and which I guess was more important than fixing broken existing functionality), but it does not seem to do what I want here. So, is it possible to do exactly this in Flare?
You do not have the required permissions to view the files attached to this post.
Psider
Propellus Maximus
Posts: 811
Joined: Wed Jul 06, 2011 1:32 am

Re: Plain ol' pop-ups

Post by Psider »

I think that how tooltips display in the application are the responsibility of the developer. That is, how they define the webview or whatever tool displays the tooltip inside the application . I know back in the dim, distant past, my devs coded the IE window that popped up when pressing f1 to display without toolbar, address bar, status bar, etc. That wasn't anything the technical writers were responsible for, and I admit I don't understand the technicalities behind it.

If I understand the microcontent correctly (I haven't played with it), it allows you to manage the content in flare, but output the text without the Flare skinning, which makes it easier for the developers to incorporate into the application. They'd obviously need some sort of help function to process it and slurp it where ever it needs to go. Again, I'm not too familiar with the technicalities, but that's the gist I've garnered.

Oh and there did used to be a thing called What's This Help, which might be what the walkthroughs you found are. I think it was specific to chm files? It might have been ported to webhelp as well, but wasn't a standard part of development environments/applications and had to be built specifically to work with whatever help tool was being used. I think. It's been a long time since I've even looked at it, because most people where I've worked decided it was all just too difficult. :)

Edit: and I've been reading about the microcontent with interest, thinking it would be very useful to manage tooltips and error messages, if I can ever get buy-in from management. :D
NorthEast
Master Propellus Maximus
Posts: 6359
Joined: Mon Mar 05, 2007 8:33 am

Re: Plain ol' pop-ups

Post by NorthEast »

Getting content from the Flare output to appear inside a popup window is certainly possible (we do it). Flare's output is in HTML format, so it shouldn't be difficult to handle for the developers.

How you style the popup depends on your type of application. Is it a desktop application, or a web-based application?
If it's a web-based application, you can style that using CSS. If you're not sure how, just use your browser tools (f12) to inspect the styles used for Flare's top nav menu or glossary popups.
chuck_agari
Sr. Propeller Head
Posts: 225
Joined: Wed May 30, 2018 2:40 pm

Re: Plain ol' pop-ups

Post by chuck_agari »

Well, I know that we're doing this with a JavaScript library. Thing is, it means that the content is living in the code, and that's exactly what I don't want. Heck, I've been pushing for months to get resources to merely implement online help in our web apps--and not even CSH either, just a basic link in the header to the help home page--and no team is willing to commit the resources, even when I've laid out how simple the process is and how little development work is actually necessary because the real functionality is all done by the libraries provided by MadCap. So any additional programmer workload is off the table, as far as I'm concerned.

I'll dig more into the micro content docs to see if what I want can be done. I don't recall seeing it in the webinar, nor in a skim through the docs though, so I'm not optimistic. We'll see........
doc_guy
Propellus Maximus
Posts: 1979
Joined: Tue Nov 28, 2006 11:18 am
Location: Crossroads of the West
Contact:

Re: Plain ol' pop-ups

Post by doc_guy »

We are trying to do something similar in one of our applications where the developer will just reference a specific micro content file in the micro content output folder and display its contents in the web application. It is tricky at the moment, because the name of the micro content file is the first phrase you created for the micro content, and that might change over time, which would break the link to the application.

We submitted a couple of feature requests related to micro content to MadCap. Feel free to re-submit these same feature requests, if you think they'd be useful to you, because the more people who request a solution, the more likely it is to be fixed/implemented. (Squeaky wheel getting grease, and all that.)
  • Allow us to name the micro content file something other than the phrase
  • Allow us to set up something like CSH calls to micro content where they can have an ID, and you can make an external call to a specific ID and have that micro content file returned
  • Provide the option to choose which phrase is the phrase that is rendered in the <title> of the resulting micro content file
  • Add a new "Micro content" folder in the target editor, and allow us to choose which micro content file(s) to include in a particular target
  • Add conditions to individual phrases/content items within a micro content file.
There may be more, but those were the ones that were most important to us.

As it is implemented in Flare 2019, micro content is most useful for enhancing search results so you can display a snippet of text/image/video at the top of a search result, potentially giving customers the answer to their specific question without having to even open a help topic from the search results. It allows you to bubble-up important information making it easier to find specific answers to specific questions.

Flare 2019 doesn't seem to have been designed with the idea that you might use micro content for field-level help in an application. I had a nice conversation on the phone with Jen Morse at MadCap, showing her what we want to accomplish with micro content in our project, and it was a very productive conversation. I don't know what they will do with my requests, but they did listen, and seemed open to ideas on how to improve micro content in the future.

I think micro content has the potential of being a very powerful tool for single sourcing content and bringing help content out of the code and into the help system where it can be maintained by the technical writing team, and updated without developer intervention. It's just not quite there yet. But I think it will be in a future release.
Paul Pehrson
My Blog

Image
chuck_agari
Sr. Propeller Head
Posts: 225
Joined: Wed May 30, 2018 2:40 pm

Re: Plain ol' pop-ups

Post by chuck_agari »

Well, here's the thing: field-level help has been part of what we develop pretty much ever since we've documented software that has fields. And the Flare micro content guide makes mention of field-level help, but with nothing more than an asterisk saying it will require additional developer resources. That's worse than useless.

I'm also not terribly optimistic about MadCap taking suggestions from real-world practitioners and turning them into product features and fixes. For example, I've filed numerous bugs against Flare 2018, some that MadCap replied as "known issues" (such as the poor rendering of PDFs with changes in some PDF viewers), some pretty serious, and what did we get for 2019? An incomplete "micro content" feature that's basically an extension of snippets, integration with ZenDesk, CSS variables (which have been part of the CSS spec for some time now), and a new splash screen. That's why MadCap saw as important.

Looking at their website, they even say (and illustrate):

"Add call-outs for field-level help

"Use micro content to create field-level descriptions for applications. Developers can programmatically add this content to applications to assist users and improve user experience."

Do they document anywhere how that's done? No, no they don't. (And really, the "programmatically add" should be little different than coding context sensitive help, where programmers do nothing more that add a function call with defined parameters; if more work than that is required of already overloaded programming teams, then MadCap didn't design the feature well enough.)

Basically, MadCap is touting the availability of a feature's use case and giving us no information how to implement it. Does that not concern us?
doc_guy
Propellus Maximus
Posts: 1979
Joined: Tue Nov 28, 2006 11:18 am
Location: Crossroads of the West
Contact:

Re: Plain ol' pop-ups

Post by doc_guy »

Yeah. They didn't provide a way to implement it in part because it will depend on how you develop your micro content, and how you're developing your product. The documentation on how to do this is definitely lacking, but it is possible to do---we're doing it in one of our products. But you're right, it's not as simple as CSH where you can just provide a URL. The developer needs to decide how they are going to consume the information that is in the micro content file. Will it display the <title> attribute? Will it only display the <p> tag(s)? There are so many options it would be difficult to pin down specifics, however generalized guidance would certainly have been helpful.
Paul Pehrson
My Blog

Image
DavidSkoglund
Propeller Head
Posts: 12
Joined: Wed Feb 13, 2019 10:05 am

Re: Plain ol' pop-ups

Post by DavidSkoglund »

I've been looking for information on this very topic. The micro content webinar didn't go into it beyond the generic bullet point that it can be done. Same with the Flare documentation. MadCap hasn't responded to me queries yet, and based on this thread I guess I'm not too surprised. I

I've been playing around with it a bit on my own to see how it works and figure out how to use it as field level pop-up help. The implementation as mentioned seems easy, have developers link to that micro content html file.

I'm thinking of some cases in our product where I'd want the micro content that shows in the search result to contain more information than a field level help pop-up would. In that case, I'd want two variations of the micro content. The problem becomes the fact that they would both be eligible for the search results, unless you can exclude the field help pop=up from the search results.

I figured out that if you use something like FieldHelp-Location as the phrase then that bit of micro content is excluded from the search results. Well, unless you search for that exact string. But, if someone actually does that then they've obviously got other issues. :)
chuck_agari
Sr. Propeller Head
Posts: 225
Joined: Wed May 30, 2018 2:40 pm

Re: Plain ol' pop-ups

Post by chuck_agari »

doc_guy wrote:Yeah. They didn't provide a way to implement it in part because it will depend on how you develop your micro content, and how you're developing your product. The documentation on how to do this is definitely lacking, but it is possible to do---we're doing it in one of our products. But you're right, it's not as simple as CSH where you can just provide a URL. The developer needs to decide how they are going to consume the information that is in the micro content file. Will it display the <title> attribute? Will it only display the <p> tag(s)? There are so many options it would be difficult to pin down specifics, however generalized guidance would certainly have been helpful.
But CSH--at least the way I'll be implementing it--isn't via a URL. It's using a JavaScript function, like this one I wrote for a demo:

Code: Select all

<input type="button" value="Open Agari Help to the Home Page" onclick="MadCap.OpenHelp(1000, null, null, null );" />
A function call such as "OpenTooltip() seems like it would leverage the OpenHelp() code that already exists. (I just did something similar last night in my JavaScript final exam, where I took some code from my project of a blackjack game and modified a couple of the functions to deal hands of cards of varying lengths.) And it seems that MadCap might want to develop a couple of rudimentary skins specifically for the display of field-level help, but they didn't do that either.

What dies it say about a company that produces a tool for developing documentation that does not itself have complete documentation? (I mean, it's not as bad as Corilla, which for years had "We'll get to this soon" as the content of most of their help topics, but now their docs are 404, which inspires even less confidence.)
DavidSkoglund
Propeller Head
Posts: 12
Joined: Wed Feb 13, 2019 10:05 am

Re: Plain ol' pop-ups

Post by DavidSkoglund »

I don't know if it is by design or not, but I was able to put a micro content tag inside another one in the XML editor view. I had to add the micro content manually in the MC window, but they both generated ok. That would solve my use case where I want a larger snippet for the search result and a smaller chunk of content as field help.
clpha6
Propeller Head
Posts: 20
Joined: Thu May 11, 2017 10:43 am

Re: Plain ol' pop-ups

Post by clpha6 »

doc_guy wrote:I think micro content has the potential of being a very powerful tool for single sourcing content and bringing help content out of the code and into the help system where it can be maintained by the technical writing team, and updated without developer intervention. It's just not quite there yet. But I think it will be in a future release.
This would be EXTREMELY USEFUL. Our UI is developed by a third party, so there are more steps involved if the tooltips need correction or rewriting.
Post Reply