Iconify Icon Finder Core

This tutorial is part of Iconify Icon Finder packages tutorial.

Icon Finder Core is doing all the heavy stuff. It takes route object, retrieves data from API, filters data and returns simple objects that can be displayed by UI without any additional steps.

By default, everything is asynchronous. Icon Finder Core uses events to react to requests and sends events on the next tick of process.

Code is written in TypeScript to provide types for all data, so editors such as VSCode will give you types and object keys for data provided by core.

Requirements

This documentation is very technical. To understand this tutorial you need:

  • Good JavaScript knowledge, including browser and Node.js.
  • Good TypeScript knowledge. Core is entirely written in TypeScript.
  • Understanding of asynchronous development.

Installation

You can install Icon Finder Core by adding @iconify/search-core package to your project.

Source code

Source code is available in Icon Finder Core GitHub repository.

To build it, install dependencies and run npm run build.

To run unit tests, run npm run test.

How does it work

All you need to do is create IconFinderCore instance and provide the callback among other parameters.

All communication from IconFinderCore to UI is done via callback. When new set of data is ready to be rendered, Core will prepare that data for rendering and call the callback. If there is an error or a loading screen (caused by API delay or internet connection problems), core will call the callback.

In the callback you should render data provided as callback parameter. See render event callback.

To change something, for example, a page, you can do one of two things:

  1. Apply action using action function. Icon Finder Core will apply that change to the current route, retrieve data (if needed), filter data and call your callback with updated data.
  2. Change route by writing to partialRoute property of the router. You can access Router instance using router property.
// Change page
core.action('pagination', 1); // Second page. First page is 0.
// Change route to MDI
core.router.partialRoute = {
   // Collection route, prefix is set in params object.
   type: 'collection',
   params: {
       prefix: 'mdi',
   },
   // Collections list as the parent route.
   // If not set, UI will not have link to return to collections list.
   parent: {
       type: 'collections',
   },
};

IconFinderCore and Registry

There are two ways to work with Icon Finder Core: using IconFinderCore class and using Registry.

IconFinderCore class is accessed by importing IconFinderCore from package's main file:

const { IconFinderCore } = require('@iconify/search-core');

const core = new IconFinderCore({
   // Parameters here
   // ...
   callback: (data, core) => {
       // Main callback where all stuff happens
   },
});

Registry class gives full access to all internal stuff. You can also access it from IconFinderCore instance by accessing registry property.

To create a Registry instance, import Registry class from lib/registry and create new instance:

const { Registry } = require('@iconify/search-core/lib/registry');

// Create registry, get router and events
const registry = new Registry();
const router = registry.router;
const events = registry.events;

// Subscribe to render event, same as using callback in IconFinderCore example above
events.subscribe('render', (data) => {
   // Same as callback in example above.
});

// Navigate to home
router.home();

For more examples of code, see IconFinderCore class or Registry class.

Routes

Every request and response has a route associated with it. PartialRoute is a simple object describing the current view.

For description of routes see routes documentation.

Views

View is script's internal presentation of the route. For each route type, there is a view type.

View does all heavy lifting:

  • It takes route
  • Sends API request
  • Parses API response
  • Applies filters
  • Renders blocks
  • Handles all actions

Views are not supposed to be used by external scripts. They are mentioned here to make it easier to understand how Icon Finder Core works.

Blocks

When your callback is called, it includes a list of blocks that UI should display.

Each block represents one set of data.

For description of all available blocks see blocks documentation.

Actions

When a user clicks something in UI, UI should send action to Icon Finder Core.

For list of actions see actions documentation.

Types

Icon Finder Core is written in TypeScript. This has several major advantages:

  • You can easily look up properties for objects, parameters for callbacks.
  • When using a library written in TypeScript, editors such as VSCode will give you hints and autofill properties, making it much easier to use the library.
  • Easier to avoid bugs. While core does have unit tests, TypeScript provides an additional layer of code checking, reducing chances of bugs.

For description of types that are relevant to implementing UI, see types documentation.