Site Simple Search Box Configuration

March 24, 2022 16:17

Tier: Basic, Professional, Enterprise

Overview

You can add Search Boxes to your websites through an embeddable iframe that provides additional access points to your social care platform that is powered by findhelp. These Search Boxes can be customized to match the look and feel of the sites they are embedded on. Simple Search Boxes can be configured to be zip code only, or add an optional free text search.

Sample Search Box

Below is an example of a sample iframe with minimal customizations.

<iframe src="https://www.findhelp.com/widget/v2/demo?ref=www.findhelp.com" width="100%" scrolling="no" frameborder="0"></iframe>

Creating a Search Box

Search boxes are created by building a URL. Each Simple Search Box must have the following foundation:

Template: https://www.findhelp.com/widget/v2/[subdomain]?ref=[page URL]

Example url: https://www.findhelp.com/widget/v2/communitydemo?ref=community.fh.com

Required Steps

Subdomain

The subdomain for where the Search Box should direct must be included after v2/. This is so that the Search Box knows where to take the user.

The "Ref" Parameter

The ref parameters refers to “referring location”. The ref parameter is necessary to provide accurate reporting on which web pages the Search Boxes are being used from. Why? Because Search Boxes are served on findhelp's website and hosted via iframe on other sites, all Search Box traffic, by default, originates from findhelp.org.

Parameter

Valid values

Notes

ref

Any string that identifies the referring location. Most commonly a url-encoded url, but could also be a domain name, or even a unique id.

Example: ref=YourURL

This value should be coordinated with findhelp to ensure validity and uniqueness. All following Search Box examples in this guide will use the same ref=enterprise.ab.com so that they work properly. In your own Search Box, you will always use your own unique ref value.

Combining Multiple Parameters

We have a list of supported parameters. Any additional parameters below may be added to the Search Box url to enable the associated features. You can combine any number of parameters from the above list in a single url. The syntax is that the first parameter after the base url must start with a “?” and every additional parameter must start with a “&”.

Example URL: https://www.findhelp.com/widget/v2/communitydemo?ref=community.fh.com&btn_color=FF0000

When adding a parameter, there must be a “&” between the value of the previous parameter, and the new parameter.

Example URL:

https://www.findhelp.com/widget/v2/communitydemo?ref=community.fh.com& btn_color=FF0000&btn_text=find+stuff&form_desc=This+is+fun&postal_placeholder=ZIP+please%21

Supported Parameters

Any of the following url parameters may be added to the Search Box url to enable the associated features. All additional parameters are optional. When adding a parameter, there must be a “&” between the value of the previous parameter, and the new parameter:

Example url: https://www.findhelp.com/widget/v2/communitydemo?ref=community.fh.com&btn_color=FF0000

Note: Any text parameter values that contain non-letter characters (spaces, punctuation, etc.) should be url-encoded. This means converting those characters into special replacements that are safe to include in urls without breaking the url format. For example, the most common encoding is replacing a space (“ “) with a “+”. Luckily there are tools for this. For example, if you start with a value like “some text!” a url encoder will output “some+text%21” which is the value you should use in the Search Box url.

Look & Feel

Parameter	Valid Values	Notes
ref (required)	A string that identifies the referring location. For the findhelp widget, please use your organization’s URL. ex. ref=www.berthaclic.com	This value should be reviewed with your findhelp Customer Success Manager to ensure validity and uniqueness. Widgets on partner sites should use the partner’s URL.
btn_color	A valid 3- or 6-digit hex color code ex. btn_color=FF0000	Make sure you do NOT include a leading # (e.g. “#FF0000”). This will result in an invalid URL.
btn_text	A short string to use as the search button text ex. btn_text=find+it	The case of the text is ignored and automatically converted to all caps in the UI (e.g. “SEARCH”).
btn_text_color	A valid 3- or 6-digit hex color code ex. btn_text_color=FFF000	Make sure you do NOT include a leading # (e.g. “#FF0000”). This will result in an invalid URL.
btn_font_size	Any valid text size ex. btn_font_size=24	Make sure you do NOT include text following the font size number (e.g. “20px”). This will result in no change.
field_font_size	The size of the text within the search placeholder ex. field_font_size=24	Default size is 16 Make sure you do NOT include text following the font size number (e.g. “20px”). This will result in no change of the font size.
form_desc	A string to display above the search form ex. form_desc=Find+Resources+Here	Make sure this text is URL-encoded, as in the example.
lang	A valid ISO-639-1 language code, as supported by Google Translate ex. lang=es	This setting has no effect on the widget itself. It’s passed along to the search page and used to translate the search results.
org	The URL-encoded name of the organization hosting the widget, if different from the default widget customer name ex. org=Bertha+Partner	Widgets on partner sites can use this parameter to override the organization name shown on the widget by default.
postal_placeholder	A string to display as the ghost text in the postal (zip) code field ex. postal_placeholder=Your+Zip+Code	Make sure this text is URL-encoded, as in the example.
search_placeholder	A string to display as the ghost text in the text search field ex. search_placeholder=Housing+Help	Make sure this text is URL-encoded, as in the example. This parameter only applies when the text_search is enabled.
show_branding	Set this to “true” to show your organization’s brand logo under the search button ex. show_branding=true	If there is no logo configured the parameter will be ignored.
text_search	Set this to “true” to show the text search box in addition to the zip code box ex. text_search=true	This specifies whether or not to include a text search field in addition to the default postal code.
top_level + service_tag	Any valid Open Eligibility Human Services domain and service tag combination ex. top_level=goods&service_tag=books	These settings are passed through the search box to pre-filter results down to the tag combination. These two parameters must be used together. If either one is omitted this setting will be ignored.
website	If your organization uses a custom URL, use this attribute to mask the findhelp.com subdomain. ex. website=https://www.helphub.org	Be sure to include https:// in your text for this parameter.
zip	Any valid zip code to use as the default in the postal (zip) code field. ex. zip=78750	This zip code will override any text configured in postal_placeholder.

Messaging

Search Boxes have limited options for how fonts are displayed. As a best practice, Customers may want to add messaging to their website itself, rather than the search box.

Parameter

Valid values

Notes

form_desc

A string to display above the search form. In partner Search Boxes this will replace the default “Need help? …” text

Example: form_desc=Enter+a+zip+code+to+find+great+programs%21

(prints “Enter a zip code to find great programs!”)

Make sure this text is url-encoded, as in the example.

Parameter	Valid values	Notes
lang	A valid ISO-639-1 language code, as supported by Google translate. Example: lang=es	This setting has no effect on the Search Boxes itself, but is passed along to the findhelp search page where it is picked up by the Google Translate component and used to dynamically translate the search results page.
text_search	The only valid value is “true”. Technically “false” is also supported, although in that case the parameter should simply be omitted. Example: text_search=true	This specifies whether or not to display an alternate version of the search form that also includes a text search field, allowing the user to search for specific programs by name, in addition to the default postal code.
top_level + service_tag	Any valid findhelp top-level category plus service tag combination. Example: top_level=food&service_tag=food+pantry	These settings have no effect on the Search Boxes itself, but are passed along in the search url to pre-filter the search results to match that tag combination. Note that these two parameters MUST be used together. If either one is omitted this setting will be ignored.
website	If you have a custom URL, use this attribute to mask the findhelp.com subdomain. Example: website=https://customurl.org	Be sure to include https:// in the website
zip	Any valid zip code to use as the default in the postal (zip) code field (default = “Enter your zip code”). Example: zip=78750	This is not placeholder text. Instead, it fills in a zip code where the user can simply click “search” and a search will be performed based on that zip code.

Embedding a Search Box

Search boxes can be embedded in any site via an iframe with the “src” attribute set to the Search Box url as configured above. Here are some starting iframe code templates.

Iframe template: <iframe src="[search box URL]" width="100%" scrolling="no" frameborder="0"></iframe>

Iframe search box example: <iframe src="https://www.findhelp.com/widget/v2/communitydemo?ref=YourURL" width="100%" scrolling="no" frameborder="0"></iframe>

In the example above, the configured Search Box URL should be placed in between the quotes after src=.

Iframe Configuration Options

The "width" attribute is not required to be 100% although that’s a good default. It can be adjusted to a fixed width as needed to fit into a page layout (e.g. width=”500px”). The recommendation is to keep the iframe at 100% width and wrap it in a containing div that maintains the proper container width, or has responsive CSS rules tied to it.
The layout of the search form will adjust responsively based on the iframe size (another reason to keep it at 100% width), so if the form is narrow (e.g. on mobile) the field and button will stack vertically
A “height” attribute may be optionally specified on the iframe as needed to work within the page layout. It may not be required, but if the search form is getting visually cut off (especially at narrower mobile screen widths) try adding something like height=”200px” to the above code, or to any code that is directly containing the iframe within the page layout. The actual numeric value will depend on the layout, and will also depend on things like which Search Box style you’re using, whether or not the “search_desc” parameter is being used, etc.
The search field contains logic to validate the zip code value, and can show an error message beneath the form if an invalid zip code is submitted. You may need to take this increase in overall height into account as well when choosing a “height” value.
Iframes support an optional attribute called “sandbox” to limit what the iframed content is able to access. This attribute is not necessary (and not recommended), but if you choose to include it it is critical that the following options are included for the Search Box to function properly:
sandbox="allow-forms allow-scripts allow-popups allow-popups-to-escape-sandbox"