@openfin/here-zero

HERE Zero

HERE Zero is a library that creates a zero-install web-based implementation of a HERE platform. It aims to provide an out-of-the-box, low-code solution for building HERE platforms that run in a standard web browser and can be themed and integrated with a customer’s backend to support application directories and search ("HERE Zero platform" for short).

Overview

The HERE Zero packager is a tool that helps configure and build a HERE Zero platform based on the core-web package. Its output is an application that you can host. It handles:

• Loading HERE configuration files
• Managing assets and dependencies
• Injecting necessary scripts into overridden HERE web output
• Customizing logos

Usage

here-zero

Configuration

The HERE Zero packager requires a configuration file as its entry point. The file must be called here.config.js (.ts, and .mjs are also supported) and must exist in the project root directory.

here.config.ts

import { defineConfig } from '@openfin/here-zero';

export default defineConfig({
    overrides: {
        file: './overrides.js'
    },
    outputDir: './dist',
    // Optional: Configure custom logos
    logo: {
        searchCommandBar: 'path/to/your/logo.ico',
        newTab: 'path/to/your/logo.ico'
    },
    // Optional: Configure title for the application
    title: 'Here® Web App',
    // Optional: Configure favicon for the application
    favicon: 'path/to/your/favicon.ico'
});

Configuration Options

• overrides: Specify the path to your overrides file
  • file: Path to your client-side JavaScript overrides file
• outputDir: Directory where built files will be placed
• logo: (Optional) Customize logos in different parts of the application
  • searchCommandBar: (Optional) Logo for the search command bar
  • newTab: (Optional) Logo for new tabs
• title: (Optional) Set the title of your HERE Zero platform
• favicon: (Optional) Set the favicon for your HERE Zero platform

Overrides

You can supply content to the HERE Zero platform, such as featured apps, launcher entries, and search results, allowing the platform to display dynamic or custom content tailored to your environment. To do this, you provide a JavaScript file that defines the content "overrides" that you want to display.

overrides.js The filename must match overrides.file in the configuration definition.

IMPORTANT: The HERE Zero packager does not handle building or bundling the provided overrides file. This file executes in a browser context, so it must contain valid client-side JavaScript.

const { defineOverrides } = require('@openfin/here-zero');

defineOverrides({
    content: {
        fetchFeaturedContent: async () => {
            // Return array of featured content items
            return [
                {
                    title: 'Example App',
                    url: 'https://example.com',
                    iconUrl: 'https://example.com/favicon.ico',
                    type: 'app'
                }
            ];
        },
        fetchLauncherContent: async () => {
            // Return array of launcher content items
            return [
                {
                    title: 'Example App',
                    url: 'https://example.com',
                    iconUrl: 'https://example.com/favicon.ico',
                    type: 'app'
                }
            ];
        },
        getInitialContent: () => {
            // Return initial content for user consumption
            // This can return an InitialContent object directly (synchronous) or a Promise<InitialContent> (asynchronous)
            return {
                content: [
                    {
                        title: 'Welcome',
                        url: 'https://example.com/welcome',
                        iconUrl: 'https://example.com/favicon.ico',
                        type: 'app'
                    }
                ]
            };
        }
    },
    search: {
        handleSearchQuery: async ({ query }) => {
            // Handle search queries and return results
            return {
                items: [
                    {
                        title: 'Search Result',
                        url: 'https://example.com',
                        iconUrl: 'https://example.com/favicon.ico',
                        type: 'app'
                    }
                ],
                totalCount: 1
            };
        }
    }
});

Build

In order to generate a HERE Zero platform, you run the HERE Zero packager. It produces an application in the outputDir specified in the configuration file. You can host and run this application as your HERE Zero platform.

Example package.json scripts section:

...
    "scripts": {
        "serve": "npx http-server dist -p 8080",
        "start": "npm run serve",
        "build": "npm run build:overrides && npm run build:here",
        "build:overrides": "rollup -c",
        "build:here": "here-zero"
    },
...

On a successful build, the packager does the following:

• Creates the outputDir declared in the config if it doesn't exist
• Copies necessary HERE web assets to the output directory
• Copies and injects the provided overrides file into the HERE web entry point
• If configured, injects the logo, title and favicon customizations into the output

Web Interop

The HERE Zero platform includes built-in support for HERE Web Interop APIs via the @openfin/core-web library.

The HERE Zero platform application includes a core-web Web broker, preconfigured with smart defaults. For example: content placed within supertabs is automatically context-bound. We recommend setting the connectionInheritance property to "enabled" on the content contexts in order to connect to the preconfigured broker.

core-web Recommended resources

• Core Web Starter Example
• Porting HERE Core Container Content to Core Web
• Core Web versions and Release Notes