View on GitHub

suit

Attivio Search UI Toolkit (SUIT) is a library for creating search clients for searching the Attivio platform.

SUIT

npmjs

The Search User Interface Toolkit, or SUIT, is a library for creating search applications on top of the index in an Attivio, Elasticsearch or Solr installation. For more information on Attivio and the Attivio Platform, please visit our website at http://www.attivio.com.

Working with the SUIT Library

To build an application using the SUIT library, we strongly recommend that you start from the companion repository, searchui, in our GitHub. The Search UI project imports the SUIT library and builds a search application that uses the React components and other classes in SUIT. Further documentation on the Search UI layer can be found in its repository.

The SUIT Library’s Contents

SUIT consists of three main types of classes:

SUIT’s Components

The UI components in the SUIT library are built on top of the React library. There are many resources on the web for learning more about React, but a good starting point is the React library’s own website.

The documentation of individual components, as well as some more basic examples of their use can be seen in the SUIT style guide. In addition, since most of the components are used in various ways by the Search UI application’s code, you can look there to see examples of how they are combined in “real life.”

The style guide is particularly useful because you can not only see examples of the components but modify their configuration in real time, right in your browser. (We actually use it while developing new components to see how the changes we make will look.) The documentation presented by the style guide comes directly from the comments in the individual components’ source files, so it’s never out of date.

To build the SUIT style guide and serve it dynamically, run the command yarn start (after having run yarn install) and then point a browser to http://localhost:6060 to see the resulting interactive website. (Alternatively, you can run yarn run styleguide to build a static copy to the styleguide directory and then just load the index.html file it contains.)

SUIT’s API Layer

The API layer includes both classes that implement the methods used to talk to the Attivio platform and others that model the objects used by the APIs. In general, there are components (see above) which encapsulate all of the functionality of the API classes. However, you can see documentation for each of them in its source file. The class you’ll likely find the most interesting is Search, which performs all queries to the back end, but others will be useful, such as AuthUtils, which is where the configuration of SUIT occurs.

Documentation for the API classes can be found here. Many of these classes mirror the classes and methods provided by the Attivio REST API, so looking at the REST API documentation can be helpful as well for those classes.

SUIT’s Utility Classes

Like the API classes, the utility classes are mostly used by the component classes and you will probably only access them indirectly; however, you might want to use some of their functionality in other ways. For details about the methods in each one, however, feel free to check out the documentation, here.

Building the SUIT Library

In general, as a user of the SUIT library, you shouldn’t need to make any changes to it or build it yourself. However, if you may need to do so if, for example, you are interested in submitting a pull request that fixes a bug or adds a new feature. For this, see further information in the file CONTRIBUTING.md.

If you are a developer in the SUIT project who needs to build a new version of the library, you use the command yarn updateversion to bump the version of SUIT to the next patch release (or use yarn updateversion minor or yarn updateversion major to update the minor or major version). Then you can use the command yarn publishlib to perform a clean, full build including all the available validation steps, and publish the resulting files to the NPM repository. You must be logged into npmjs.com (via npm login) to do this.

Contributing to the SUIT Library

Details about how you can contribute to the SUIT library, including criteria for doing so, can be found here.

All NPM Scripts

The full list of scripts that you can run on the SUIT library is listed here: In this case, you can use the following commands:

Command Description
yarn install Installs the project’s dependencies into the node_modules directory (note, don’t use npm install to do this).
yarn build Performs a build of the library.
yarn flow Run the Flow type checker on the library and report any errors.
yarn lint Run the ES Lint style checker on the library and report any errors.
yarn doclint Run the documentation.js checker to look for errors in the JSDoc comments in the api and util subdirectories.
yarn validatecomponents Performs validation that all of the components in the library meet certain standards.
yarn fullbuild Performs a full build of the project from scratch (removing the node_modules direcotory as well as any other build products and performs all validation steps before actually building the contents of the SUIT library and its documentation.
yarn updateversion Updates the project’s version before publishing it to the NPM repository.
yarn publishlib Does a full build and then publishes the resulting new version to the NPM repository.
yarn styleguide Builds the style guide and serves it on your local machine’s port 6060. This continues watching for changes and re-compiles and updates the style guide if any are found.
yarn styleguide:build Builds the style guide statically into the styleguide directory for the components directory.
yarn doc Run the documentation.js builder to publish documentation for the classes in the api and util subdirectories.
yarn watch Builds the library and watches for changes, rebuilding as they are found.
yarn test Runs the suite of tests for the library.
yarn test:coverage Generates a report of test coverage for the library.
yarn test:watch Continuously runs the suite of tests for the library, watching for changes and re-running as they are found.