Autocomplete sources

There are 4 ways to extend the available autocomplete source that can be used in projects.

• External sources
• Sources defined in code
• Configured sources
• Madoc API sources

External sources

The first way to have an externally hosted API that can serve up JSON in the format expected by the autocomplete component.

Example autocomplete JSON.

{
  "completions": [
    {
      "uri": "http://example.org/1",
      "label": "Example 1",
      "description": "This is an example",
      "resource_class": "author",
      "score": 123,
      "language": "en"
    },
    {
      "uri": "http://example.org/2",
      "label": "Example 2",
      "description": "This is an example",
      "resource_class": "author",
      "score": 123,
      "language": "en"
    }
  ]
}

If you create an endpoint that returns this JSON, you can then use it as a data source in your capture models. You must ensure that the server you create has the correct CORS headers to allow the request to be made from your Madoc.

Sources defined in code

You can also define autocomplete sources in code. This is useful if you want to create a custom autocomplete source that could be used by others in the community, or one that requires some custom logic to map.

We currently have 2 sources defined in code.

• WikiData
• Worldcat FAST

A custom completion can be added by implementing the CompletionSource interface.

const mySource: CompletionSource = {
  async doCompletion(options, context) {
     options.query; // Query string on the request. (options.page, options.language)
     context.api; // Access to the Madoc API if needed.
 
    // Make a fetch call?
    const resp = await fetch('http://example.org/my-source');
 
    return { completions: [] }; // Completions should be returned.
  }
}

Once created you can register your source in the completions/extension.ts (opens in a new tab) file.

Configured sources

You can configure autocomplete sources in the admin panel. This is useful if you want to add a new source without having to deploy a new version of Madoc.

Once created the pattern for the url is:

/s/:slug/madoc/api/term-proxy/:id

And for the model you will need:

?q=%

on the end of the URL. The slug is whatever the madoc site is (e.g. /s/default) and the id should be available from the URL on the admin: For example, the Admin url for this example:

https://madoc.example.org/s/default/admin/configure/site/terms/0cb2575d-30f8-4aad-8e60-7d4e21ed154b

Would be:

https://madoc.example.org/s/default/madoc/api/term-proxy/0cb2575d-30f8-4aad-8e60-7d4e21ed154b?q=%

Which you can add to the capture model autocomplete data source field

Madoc API sources

There is also a way to configure an autocomplete to use the Madoc API to fetch completions. This is not recommended for use in project capture models, but can be useful for configuration that also a shorthand model.

For example, the following URL configured in a model:

madoc-api://iiif/manifests/:manifest/projects-autocomplete?all=true

Will fetch all projects that a manifest is a part of. This allows for authenticated autocomplete sources to be configured. However the endpoints need to be in the completion source format.