Documentation

Developing widgets for the Ask Hoxly search engine is simple and easy if you already know web development. Widgets are just small webpages that get embedded into a sandboxed iframe with access to JavaScript, CSS, and forms (but no other functionality). This webpage is self-hosted so you can use your preferred language on the backend to generate the HTML (Node JS, Python, Ruby, etc.) or even just have a static HTML file with some JavaScript running client side.

Hello, world

Here is some sample code for a very basic Hello world widget. All it does is display the text "Hello, world" followed by the users' query. In the <head> we do three things:

  1. Let other search engine crawlers know that they shouldn't index this page
  2. Load the Hoxly Widget JS library which is used to communicate with the search results page over postMessage. If you don't load this and initialize a AskHoxlyWidget somewhere on the page then the widget will not run in our iframe.
  3. Load the Hoxly Bootstrap 5 theme which is optional but recommended to ensure a consistent look between widgets.

You can put whatever you want in the <body> but make sure at some point you create an AskHoxlyWidget object.

<!DOCTYPE html>
<html>

<head>
    <!-- Don't let other search engines index this because they won't know how to handle it -->
    <meta name="robots" content="noindex, nofollow">

    <!-- Hoxly Widget JS (required) -->
    <script src="https://cdn.hoxly.com/search/widget.js"></script>

    <!-- Bootstrap core CSS (recommended, but optional) -->
    <link href="https://cdn.hoxly.com/search/bootstrap/5/theme.min.css" rel="stylesheet">
</head>

<body>
    <h4 class="text-muted text-break">Hello, world</h4>
    <h3 class="text-break">Your query is "<span id="query"></span>"</h3>

    <script>
        // Options for the AskHoxlyWidget
        const options = {};
        // We need to create a AskHoxlyWidget somewhere on the page or else
        // the widget will not be shown in the search results.
        const widget = new AskHoxlyWidget(options);

        // We get the URL parameters
        const params = new URLSearchParams(window.location.search);
        // Get the "query" parameter
        const query = params.get('query');
        // Set the span with ID query to the query.
        document.getElementById('query').innerText = query;
    </script>
</body>
</html>
            

Here is what the widget would look like on a search results page.

Ask Hoxly hello world widget

Linking to pages

In order for links in your widget to navigate in the top window you must set the target to _top like <a href="https://www.example.com" target="_top"></a>. Otherwise, your links will only navigate to new pages within the frame.

Submitting your widget

Once you've developed your widget you'll need to submit it to our index. Here are the steps to do that:

  1. Test your widget using our widget testing tool to make sure everything works.
  2. Register a developer account here.
  3. Submit your widget using this form.

When you submit the URL to your widget use the template tag {{query}} in place of where the query should go. So, for example, if you use a query parameter called "query" (like in the code above) then your widget URL could be https://www.example.com/widget?query={{query}}.

Getting help

If there is anything we can do to support you as a developer please send us an email at support@hoxly.com.