This blog post was written by Mattias Sander, a Flare consultant recognized for his expertise in MadCap Flare, specializing in the migration of various content types like Word, Markdown, InDesign, and PDFs into Flare. He is the developer behind the popular Mad Quality Plugin, focusing on quality automation in technical documentation, and the free Kaizen Plugin, enhancing workflow efficiency in Flare projects.
As technical communicators one of our objectives is to streamline the user experience. The integration of an easy-to-use search dropdown in MadCap Flare represents a significant step in this direction. This feature improves the standard search process by offering immediate, predictive suggestions. This blog post aims to detail the advantages of this functionality and provide a guide for its implementation to help you level up your documentation user experience.
The Advantages of an Advanced Search Dropdown
Efficient Navigation: The introduction of this dropdown reduces the time users spend in search. By providing suggestions as users type, it facilitates quicker access to needed information, especially valuable in extensive documentation systems.
User-Friendly Experience: This feature changes the search process, transitioning from a standard, manual entry to a more intuitive, assisted approach. It’s particularly beneficial for users who might not be familiar with the specific terminologies used in your documentation, guiding them to appropriate results with minimal effort.
Uncovering Hidden Information: The predictive nature of the dropdown aids in revealing pertinent information that users might not initially seek. This discovery aspect is crucial in situations where users are unaware of the full breadth of available content, thus increasing engagement and knowledge.
Professional Appeal: Implementing a dynamic and responsive search feature demonstrates a commitment to high-quality documentation. It reflects an understanding of user needs and a dedication to meeting them efficiently, enhancing the overall perception of your documentation as modern and user-centric.
Putting in this dropdown for searching in your MadCap Flare guides makes it easier for people to find what they need. It also lets them know that you're paying attention to what helps them the most.
Setting It Up in Flare
Step 1: Adding the JavaScript
This JavaScript is the core of the dropdown functionality. Save it as dynamic-search.js in your Flare project.
class
SearchManager {
constructor() {
this.debounce = this.debounce.bind(this);
this.handleSearch = this.handleSearch.bind(this);
this.displayResults = this.displayResults.bind(this);
this.clearResults = this.clearResults.bind(this);
this.showFullResults = this.showFullResults.bind(this);
this.hideDropDown = this.hideDropDown.bind(this);
this.showDropDown = this.showDropDown.bind(this);
// Add this line
this.init();
}
debounce(func, delay) {
let debounceTimer;
return
function () {
const context = this;
const args = arguments;
clearTimeout(debounceTimer);
debounceTimer = setTimeout(() => func.apply(context, args), delay);
};
}
handleSearch() {
let searchQuery = document.querySelector('.main-section.search - bar >
input ').value.trim();
const invalidPattern = /(\"|\($|\b(AND|OR|NOT|NEAR)\b)$/i;
const openParenthesesCount = (searchQuery.match(/\(/g) || [])
.length;
const closeParenthesesCount = (searchQuery.match(/\)/g) || [])
.length;
if (invalidPattern.test(searchQuery) || openParenthesesCount !== closeParenthesesCount) {
console.warn("Invalid
search query.Please ensure proper use of operators and matching parentheses.
");
return;
}
if (searchQuery.length > 0) {
MadCap.SearchHelper.SearchPane.Search(searchQuery, {
searchContent: true
})
.then(this.displayResults)
.catch(error => {
console.error("Search
failed: ", error);
});
}
else {
this.clearResults();
}
}
displayResults(results) {
const dropdown = document.getElementById('searchResultsDropdown');
dropdown.style.visibility = "visible";
// Ensure the dropdown is visible
dropdown.innerHTML = '';
results.content.slice(0, 5)
.forEach(item => {
const resultItem = document.createElement('li');
const title = document.createElement('div');
title.classList.add('title');
title.textContent = item.Title;
resultItem.appendChild(title);
const preview = document.createElement('div');
preview.classList.add('preview');
preview.textContent = item.AbstractText;
resultItem.appendChild(preview);
resultItem.addEventListener('click', () => {
window.location.href = item.Link;
});
dropdown.appendChild(resultItem);
});
if (results.content.length > 5) {
const showAll = document.createElement('li');
showAll.textContent = 'Showing 5 results. For all results, press ENTER';
showAll.addEventListener('click', this.showFullResults);
// Append this first so it's at the top:
dropdown.insertBefore(showAll, dropdown.firstChild);
}
}
clearResults() {
const dropdown = document.getElementById('searchResultsDropdown');
dropdown.innerHTML = '';
}
showFullResults() {
// Implementation for showing full results
}
displayAllResults(results) {
const dropdown = document.getElementById('searchResultsDropdown');
dropdown.innerHTML = '';
results.content.forEach(item => {
const resultItem = document.createElement('li');
const title = document.createElement('div');
title.classList.add('title');
title.textContent = item.Title;
resultItem.appendChild(title);
const preview = document.createElement('div');
preview.classList.add('preview');
preview.textContent = item.AbstractText;
resultItem.appendChild(preview);
resultItem.addEventListener('click', () => {
window.location.href = item.Link;
});
dropdown.appendChild(resultItem);
});
}
hideDropDown(event) {
const searchResultsDropdown = document.getElementById('searchResultsDropdown');
if (!event.target.closest(".search-field")) {
searchResultsDropdown.style.visibility = "hidden";
}
}
showDropDown() {
// Add this method
const searchResultsDropdown = document.getElementById('searchResultsDropdown');
searchResultsDropdown.style.visibility = "visible";
}
init() {
$(document)
.ready(() => {
const searchInput = document.querySelector('.main-section.search -
bar > input ');
searchInput.addEventListener('input', this.debounce(this.handleSearch, 300)); searchInput.addEventListener('focus', this.showDropDown);
// Add this line
const dropdown = document.createElement('ul'); dropdown.id = 'searchResultsDropdown'; document.querySelector('.main-section.search -
bar ').appendChild(dropdown);
});
document.addEventListener("click", this.hideDropDown);
}
}
new
SearchManager();Step 2: Styling with CSS
This CSS file, named search-dropdown.css, will give the dropdown its aesthetic appeal.
#searchResultsDropdown {
position:absolute;
z-index:1000;
background-color:white;
border:1px solid #ddd;
list-style-type:none;
padding:0;
margin:0;
width:100%;
box-sizing:border-box;
}
#searchResultsDropdown li {
padding:10px;
cursor:pointer;
border-bottom:1px solid #eee;
}
#searchResultsDropdown li:hover {
background-color:#b9bec1;
}
#searchResultsDropdown li div.title {
color:blue;
font-size:1em;
}
#searchResultsDropdown li div.preview {
color:grey;
font-size:0.8em;
}
Final Steps in Flare
Include both the JavaScript and CSS files in your Flare project, linking them in the appropriate template pages.
In Conclusion
Implementing a dynamic search dropdown in MadCap Flare is more than just a technical upgrade; it’s a commitment to an improved user experience. By guiding users efficiently to the information they seek, this feature elevates the functionality and professionalism of your documentation.
