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 about 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 application can be found in its repository.
The SUIT Library’s Contents
SUIT consists of three main types of code:
- React components used to render the user interface,
- API classes which include code that makes calls to the Attivio server’s REST API to perform tasks such as querying your index, and
- Utility classes used by the library which can also be used by application-level code.
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 SUIT Style Guide
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 code, you can look there to see examples of how they can be combined in “real-life” applications.
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 our changes without needing to include them in an application layer.) The documentation presented by the style guide comes directly from the comments in the individual components’ source files, so it should always be up to date.
To build the SUIT style guide (which is built using
React Styleguidist) and serve it dynamically,
run the command
yarn start (after having run
yarn install) and then point your browser to
http://localhost:6060 to see the resulting interactive website. (Alternatively,
you can run
yarn styleguide:build to build a static copy to the
styleguide directory and then just load
index.html file it contains.)
SUIT’s API Layer
The API layer includes classes that implement the methods used to communicate with to the Attivio platform and others that model the objects used by the APIs. In general, SUIT’s components (see above) encapsulate all of the necessary calls to API classes but you may want/need to use some of the APIs directly. One class in particular you may need to use is Search, which performs all queries to the back end.
Documentation for the API classes can be found here. As with the components, this documentation is taken directly from comments in the source code so should always be up to date. Many of the API classes mirror the classes and methods provided by the Attivio REST API, so looking at the REST API documentation can be helpful as well.
SUIT’s Utility Classes
Like the API classes, the utility classes are mostly used by the component classes and you may only access them
indirectly; however, you might want to use some of their functionality in other ways. Some of the classes you
might want to look at include AuthUtils (which handles configuration of SUIT as well as keeping track of the
current user’s details), FetchUtils (which provides a wrapper around the built-in
fetch() API that handles
authentication-related issues), and StringUtils (which provides some string manipulation functions).
For details about the methods in these classes, please check out their 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, 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.
Publishing New Versions
If you are a contributor to the SUIT project who needs to create a new version of the library, you should use the
yarn updateversion to bump the version of SUIT to the next patch release (use
yarn updateversion minor
yarn updateversion major to update the minor or major version instead). 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. You will
also want to commit the changes in your source tree to GitHub since they will contain the updated documentation
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 Yarn Scripts
The full list of yarn scripts that you can run on the SUIT library is listed here:
||Installs the project’s dependencies into the
||Performs a build of the library.|
||Run the Flow type checker on the library and report any errors.|
||Run the ES Lint style checker on the library and report any errors.|
||Run the documentation.js checker to look for errors in the JSDoc comments in the
||Performs validation that all of the components in the library meet certain standards.|
||Performs a full build of the project from scratch (removing the
||Updates the project’s version before publishing it to the NPM repository.|
||Does a full build and then publishes the resulting new version to the NPM repository.|
||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.|
||Builds the style guide statically into the
||Run the documentation.js builder to publish documentation for the classes in the
||Builds the library and watches for changes, rebuilding as they are found.|
||Runs the suite of tests for the library.|
||Generates a report of test coverage for the library.|
||Continuously runs the suite of tests for the library, watching for changes and re-running as they are found.|