HTML5 search highlighter

[scott]

Hi everyone,
I've written a script that adds search highlighting to HTML5 targets. Feel free to use it in your projects.

The following link includes a sample project, sample HTML5 output, instructions, and the files you will need:

http://www.clickstart.net/highlighter

To open the flprjzip file, you can double-click it or open Flare and select File > Open.

If you have trouble downloading the js file in the "instructions, sample icon, and script" link, you can copy it from the sample project. It's in the MasterPages folder.

Limitations, tips, and features are included in the instructions document.


hope you enjoy the script,
.scott

[LTinker68]

Haven't gone through your steps yet, Scott, but I'm really excited. I wasn't going to go back to HTML5 output until highlighting was implemented, but now I don't have to wait for that. Thanks!

[ThomasH]

Wow, that's great news!
I've been struggling implementing something similar myself, so I'm thrilled to take a look at your script!

Thanks for your effort to improve working with Flare!

By the way: I've just noticed that your script appears to fail when using Google Chrome. Don't worry - it's just an issue when browsing the WebHelp locally.
http://techcommdood.com/techcommdood/latest-chrome-update-breaks-locally-viewed-webhelp/
When you upload your output to any webserver it works fine in Chrome. (Just tested Opera, IE and Firefox too - everything is fine)
Thanks again!

*Edit* Sorry - just read in your instructions, that you allready pointed out the fact that there might be some problems when browsind locally
I should have read the whole thing

[LTinker68]

One little unintended result of implementing Scott's code... I have a "how to use this guide" topic for my HTML5 output that tells users about the various features in the help, like the index, glossary, search, etc. The problem is, when you go to that topic, the "Search" heading in the topic is highlighted because the Search field in the output is pre-populated with the word "Search". I don't know an easy away around that except to make the search field blank to start with, which I think will require hacking the page post-build.

EDIT: This is a problem in IE -- FF doesn't seem to highlight the word until the Search function is run.

[scott]

Hi Lisa,
It's an unusual case that you wouldn't want to highlight, so I didn't worry about it. It's more likely that this "extra" feature would be useful.

You could add something to make it not a match.
Example: <h1>Searc<span></span>h</h1>

That would not match "Search."

Or, you could change the Search input's placeholder text in your skin.

Another option is to click the remove highlight button. Probably a little annoying, but not too bad.

[LTinker68]

Actually, it turned out to be a pretty easy workaround. After generating the output, open the Default.htm file in the output folder. Look for placeholder="Search". Add a space after the word Search so it's placeholder="Search ". That's enough of a difference that it won't highlight the word "Search" in topics when they first load and before you actually search.

Downside is you have to copy that modified Default.htm file into the output folder every time you build and before publishing, but I have to do that anyway for another workaround I did in that file. Although this particular modification I probably wouldn't mind making in the Flare program folder so it filters out to all projects.

[scott]

I'd add the space in the skin (as I mentioned):
> Or, you could change the Search input's placeholder text in your skin.

Sure, you can also change it after publishing if you want to do it every time.


I like the idea of changing Flare's default value if you have a lot of projects.

[LTinker68]

Oh, I missed what you said about the skin. I'm still not used to that UI Text tab and rarely think of going into it. I'll give that a shot. Thanks!

[johnnygreen]

HI,

I just can't get Scott's script to work (although I am generating the output onto a network rather than onto a bona fide Web Server). I'll try it on a Web Server when I get home, but, if I just copy the output to the Web Server via FTP to see if it works then, is there anywhere else I need to add the 'highlighter.js' script (at the moment it's just in the 'MasterPages' folder)? Or do I have to set up Flare to generate directly to the Web Server?

I am also not sure how to view Scott's sample file 'highlighter_sample_project.flprjzip' - it looks empty when you open it in Flare 8.

Thanks, but I'm new to this game and I'm astonished that I have to jump through these hoops to get some basic search highlighting.

Regards.

John Green

[scott]

Hi John,
As it says on the script's web page, you are welcome to email me if you have a question about the script. My email address is scott@clickstart.net.

I've re-uploaded the flprjzip file just in case. To download it, right-click the link and select Save.

There are only three "hoops" to add the highlighter:
* Paste the code into your master page
* Copy the highlighter.js script to your masterpage folder
* Add a "highlight" style class to your stylesheet

These steps are described in much more detail in the "notes" document.

There might be something weird going on in your project, or maybe it's a browser issue. Double-check the instructions and take a look at the sample project. If you still have problems, just email me.

A lot of people ask me why the HTML5 search doesn't highlight by default. The HTML5 search is designed to look and function like Google's search. Google's search doesn't highlight your search term when you open a web page. I personally think the highlighting is useful, so I wrote the script. If you moved to HTML5 from WebHelp, your users probably expect highlighting and it might seem odd that it's not a feature in Flare. If your users are more familiar with Google's search, the highlighting might seem odd. It just depends on their expectations.

have a good one.

[johnnygreen]

Thanks to Scott for helping this MadCap 'rookie' get search highlighting to function in his project. It works well in my HTML5 output now, even locally.

John

[mgray]

Hi Scott -- This is an awesome feature. Thanks for providing it.

I do have one issue that I wonder if there is a workaround for: I like for each search result I click on to open up in a new window (by holding cntrl down while clicking). The highlight will not work if I do this. Any ideas?

[Ineffable]

This is a great hack. I love it.

One question: Has anyone figured out how to make the highlight display when the found term is part of a link?

[scott]

Hi everyone,
Both of these requests:

* highlight search term if the user opens a search results link in a new window/tab
* highlight inside links

are much more difficult that they should be because of (request 1) JS security issues and (request 2) the current regex approach and browser limitations.

They're both good ideas, and I'll work on them. However, they could take a while or may end up being impossible or not practical.

[tomjohnson1492]

Scott, thanks for creating this workaround for the search highlight. I followed your instructions and it works great.

If I could add a request ... it would be great if the search results would automatically open a drop-down hotspot when the search term is hidden inside it. Do you know how to do that?

Tom

[straygoat]

Thanks Scott. I've used your script on a project and it worked perfectly, first time. Excellent! MadCap support told me that they are looking into providing this feature, so hopefully they will take a look at what you have done.

[ThomasH]

We are using this script for quite a while now and we really are satisfied with the results. Thanks for your work Scott.

However there is one small issue: we often have syntax or code snippets starting with < in our documentation and whenever you search for something which is found in that code the highlight span somehow "destroys" our text.

Let me give you an example: I'm searching for "Ldap" and in my topic there is a snippet that says:
<setting name="AuthByLDAP" serializeAs="String">
when the search highlights Ldap i only get back:
LDAP" serializeAs="String">
furthermore the Ldap in this particular line is not highlighted...

so my guess is the tag < messes with the script when inserting the <span> elements.
in my topic i already used entities - so i'm not using <, instead I wrote &lt; which should have done the trick - at least thats what I thought.
Unfortunatley it doesn't!

Do you have any idea what I'm trying to say? And do you maybe even have an idea what I can do to solve my problem?
Thanks in advance!

[Saurbaum]

I'm trying to make use of this script but I've managed to crash IE using it.

Load Help page
Search for something
pick the top result
Press the search button again
Press the remove highlight button

I get a brief pause and then IE crashes hard

function removeSearch() {
window.parent.document.getElementById('search-field').value = "";
$("span").toggleClass("hi",false);
}

This seems to return but immediately after it all goes wrong. Anyone got any suggestions as to what I might be doing wrong?

[gus1980_99]

I'd add the space in the skin (as I mentioned):
> Or, you could change the Search input's placeholder text in your skin.

Sure, you can also change it after publishing if you want to do it every time.


I like the idea of changing Flare's default value if you have a lot of projects.

As far as preventing that minor IE issue by changing the Search input's placeholder text in your skin: I couldn't get that to work by adding a space after "Search", but adding a space before it (so the placeholder equals = " Search") worked great. Just another simple approach to try if the first one isn't working out.

Thanks again for the great highlighter.

[scott]

Hi everyone,
Just wanted to mention that MadCap listened to our requests and added search highlighting to Flare V9. You can still use this script with Flare V8, but you won't need it for V9.