Docs Developer Site
Explorer - Search and you shall findGetting started

Getting Started

Contents

Hands-on introduction to get familiar with Enonic Explorer

Introduction

During this tutorial you will:

  • Sign up for a free Enonic account

  • Set up a new solution with Explorer pre-installed

  • Create a new collection and fill it with sample content

  • Learn about Documents and Document types

  • Setting up an interface to search your content

  • Access and query the API directly

Sign up

Developers may also try out Explorer by installing the Enonic SDK.

  1. Start by signing up for get a free account on https://cloud.enonic.com

  2. Once you have signed up and verified your account, create a new Solution. From the Solutions page, click the Create button at the top right.

    Choose the Explorer template, give your solution a name, go with the default values.

    The template ensures that Explorer and all relevant dependencies pre-installed.

Explorer admin

Once the environment has booted. From the new solution page, click Enonic XP Admin → Launch.

+ This will take you to the environment’s dashboard. The Explorer admin can be opened from the top right XP menu → Explorer.

Only users with the role "system.admin", or "com.enonic.explorer" (created when explorer was installed) can see and access the Explorer admin.

The initial view should look something like this:

Explorer start page

The Explorer menu is available from the top left. The main panel gives you an optino to search the indexed documents. But you don’t have anything to search, do you? 🤷

Collecting data

To get some data to play with, let’s use the built-in, very basic Web crawler collector to index the contents of Enonic Market.

  1. Create a new Collection from the Solutions page, click the Create button at the bottom right.

    • give your new collection a name, i.e. "market"

    • choose Web crawler from the collector dropdown menu

    • provide the collector with a starting URL: https://market.enonic.com

    • Skip all other options, and click Save at the bottom of the form

  2. Start the collector

    The market collection should now be available in the list of collections.

    Click the Download icon to the left to start the collector. This will trigger a background job that crawls the website and adds each page as a document in Explorer.

    To view the status of the job, visit the Collections → Status page from the Explorer menu.
    CollectorStatus
In addition to collectors (code that runs within Enonic), you may also use the Document API to actively inject data to your collection from the outside.

Documents

Once the collector job has completed, you may click the documents count link which will take you to the Documents page. You can easily get to this page via the menu as well.

Document is the term used for a single item within a collection

From the documents page, you may browse and filter all available documents. You can also configure which fields to show. Clicking the leftmost "JSON" icon will reveal the raw data that was indexed for this document.

Do your first search, but typing explorer in the search box:

Search results for explorer

Document types

In order to optimize your search, you may need to tune how the different fields are indexed. This is managed via Document types.

From the Document types page, you should see a single entry - Web page. This document type was automatically created by the Web crawler collector. This is a so-called "Managed" document type, which means that the collector is responsible for managing and updating the document type - as opposed to a manually registered document type.

If you try editing the document type (using the edit icon on the right hand side), you will be warned that it is managed. Ignore this and go on to see the full document type details:

Webpage document type

A document type may be used across multiple collections, and you may also use multiple document types within a single collection.

Every document also has a set of common fields like id, collection, createdTime and documentType. These cannot be removed or changed.

Interfaces

Interfaces are used when you want to select which collections to be exposed, and to manually tune a search. Tuning includes boosting, stemming, synonyms and stopwords. Interfaces can be created and managed directly from the Explorer admin.

An interface in this context is not an actual user interface, but rather an API. Explorer has a GraphQL API, but the actual end-user search interface must be built on top of this.

  1. Create a new interface by clicking the (+) button in the lower right corner of the Interfaces page.

    • give your interface a name, for instance myinterface

    • add the market collection

    • set a field boosting for the title field.

      It should look something like this:

      Showing the form of the new interface

  2. Save the changes to create the interface.

With the interface created, you are now ready to give it a spin!

API

To try out the API, click the pink graphQL icon to the left.

A list showing a single interface

This will take you to an API browser, where you can easily test various queries against the API:

Query browser

It essentially consists of:

  • query panel (to the left)

  • result panel (to the right)

  • context selector (on top)

Follow these steps to run your first API-powered query:

  1. Make sure the context is set to myinterface

  2. Paste this into the query panel:

    Searchstring "explorer" 
    query{
	interface {
    search(searchString: "explorer"){
      hits{
        _documentType
        ... on DocumentType_Webpage {
          title
          url
        }
      }
    }
  }
}

  3. Click the pink play button.

    You should now get a result looking something like this

    Searchstring "explorer" 
    {
  "data": {
    "interface": {
      "search": {
        "hits": [
          {
            "_documentType": "webpage",
            "title": "Explorer - Enonic Market",
            "url": "https://market.enonic.com/vendors/enonic/explorer"
          },
          {
            "_documentType": "webpage",
            "title": "Extensions and plugins for Enonic XP and Content Studio (CMS)",
            "url": "https://market.enonic.com/"
          },
          {
            "_documentType": "webpage",
            "title": "Enonic - Enonic Market",
            "url": "https://market.enonic.com/vendors/enonic"
          },
          {
            "_documentType": "webpage",
            "title": "Applications - Enonic Market",
            "url": "https://market.enonic.com/applications"
          },
          {
            "_documentType": "webpage",
            "title": "React4xp Lib - Enonic Market",
            "url": "https://market.enonic.com/vendors/enonic/react4xp-lib"
          }
        ]
      }
    }
  }
}

Explorer is also capable of various aggregations as well. Below we perform a term aggregation search over the title and _documentType fields.

Try it out yourself!

Search with aggs 
query{
	interface {
    search(
      	searchString: "explorer"
    		aggregations: [
					{name: "title", terms: {field: "title"}},
					{name: "documentTypes", terms: {field: "_documentType"}}
        ]){
      aggregationsAsJson
		}
	}
}

Back in your Enonic cloud solution, the API enpoint is already exposed publicly via an Ingress. Visit the Ingresses section to find the link.

Visit the API pages to learn more about the interface API.

Next up

With the fundamentals covered, we recommend looking into the following areas to learn more:

Contents