My Museum Tour

Summary of the project

This React app drives the My Museum Tour builder on the main artic.edu website. It provided an interactive client-side interface for users to create a My Museum Tour.

Features

Uses the API from artic.edu to:
- Search artworks
- POST data to the my-museum-tour endpoint
Cypress component testing and integration testing
- Included as part of the Github Actions workflow

Overview

This is just a React application, it doesn't contain any styles or images of its own.

It's decoupled from artic.edu, but is intended to be used to embed the app into the artic.edu website. In theory this can be used in other contexts, however it assumes the presence of other assets that exist in order to function correctly, specifically:

CSS classnames are referenced here, but are defined in artic.edu
Icons are referenced here, but are defined in artic.edu
Behaviours (e.g. pinboard) are referenced here, but are defined in artic.edu
Events (e.g. page:updated) are referenced here, but are defined in artic.edu

Configuration

The <MyMuseumTourBuilder /> React component can take in two props.

apiSaveEndpoint (optional) - which should be the path to the my-museum-tour save endpoint. If not provided it will default to /api/v1/my-museum-tour
heroImageId (optional) - which should be a string forming part of a IIIF image identifier that will be concatenated into a IIIF URL. If not provided there will be no hero image rendered on the customization screen.

Requirements

Node.js / npm

Important

Although optional, we recommend using nvm to match the version of Node used in this project before running the install command, or the npm scripts described below.

If you encounter problems and aren't using the version of Node shown in the .nvmrc file, you should try aligning your node version to this first. This represents a known compatibility with the code here and our dependencies.

Installing

Install the dependencies in the project root with:

npm ci

Developing locally

If you want to develop new features on this project locally, there's various commands and actions you can perform using the npm scripts as described below.

A full list of thse scripts is available in package.json, or by running npm run.

Note

The index.html file links to CSS, JS and icons which can either be symlinked or updated to point to those files from artic.edu

Compiling and previewing changes

Command	Action
`npm run dev`	Watches files in the `src` directory for changes and serves a preview at https://localhost:43110 with hot module replacement. You can edit the `index.html` file to update the rendering of this preview (e.g. update the props in `MyMuseumTourBuilder`)
`npm run build`	Builds the package for use in production. See "Consuming this package" for how this package can be used

Important

In the current setup you must commit the build files

Running the tests

Command	Action
`npm run test:gui`	Will start the local dev server and run the component tests with the interactive GUI
`npm run test`	Starts the dev server as above, but instead runs the tests without the GUI

Linting the code

Command	Action
`npm run lint`	Will lint (and fix where possible) all problems in the code

Consuming this package

The expectation is that the code generated by this project will live within artic.edu, but technically the same rules apply if another website or application wants to use it.

Requirements

Node.js
React (>=16)
ReactDOM (>=16)

Installation

In your package.json file add a new dependency that points to this repository:

{
  "my-museum-tour-builder": "git+ssh://git@github.com/art-institute-of-chicago/my-museum-tour.git#main",
}

Note

The fragment (i.e. "#main") of the url shown above refers to the branch. There might be some instances (such as developing a new feature) where you'd like to reference a different branch, which can be achieved by updating this to the corresponding branch and running npm i my-museum-tour-builder. You will need to run this command whenever updates are made to the branch shown here, as the package-lock.json stores references to specific commits

Run npm i my-museum-tour-builder
The default export for the primary component of this app can be accessed as you would any other npm package using ESModules:

import MyMuseumTourBuilder from 'my-museum-tour-builder';

Your app is responsible for mounting this component to the DOM using ReactDOM

React 16:

  ReactDOM.render(<MyMuseumTourBuilder/>, container);

React > 16:

ReactDOM.createRoot(container).render(<MyMuseumTourBuilder/>);

Contributing

We encourage your contributions. Please fork this repository and make your changes in a separate branch. To better understand how we organize our code, please review our version control guidelines.

# Clone the repo to your computer
git clone git@github.com:art-institute-of-chicago/my-museum-tour.git

# Enter the folder that was created by the clone
cd my-museum-tour

# Start a feature branch
git checkout -b feature/good-short-description

# ... make some changes, commit your code

# Push your branch to GitHub
git push origin feature/good-short-description

Then on github.com, create a Pull Request to merge your changes into our develop branch.

This project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

We welcome bug reports and questions under GitHub's Issues. For other concerns, you can reach our engineering team at engineering@artic.edu

Acknowledgements

Developed in collaboration with Cogapp and Art Institute of Chicago.

Licensing

This project is licensed under the GNU Affero General Public License Version 3.