Visualization components developed for American Panorama, from the Digital Scholarship Lab at the University of Richmond. View Examples
The toolkit is designed for use in the creation of historical maps such as those in the American Panorama Atlas. The components within can be installed via npm and integrated into any web-facing project. American Panorama also includes a template that can be used as a starting point for maps in the American Panorama Atlas, and for other projects that aim to use Panorama components. All of the components within that are "views" (meaning they appear in the DOM) are React components.
For a higher-level overview of the architecture of the American Panorama atlas, see: ARCHITECTURE
For various server-side database queries that are outside the scope of the toolkit, but which are useful for preparing data for your visualizations, see: USEFUL QUERIES
You might consider starting with the American Panorama template. Whether or not you do, please follow these instructions to bring the American Panorama components into your project.
Ensure that your Node version matches that present in .nvmrc.
nvm is the easiest way to do this,
especially when using projects that require multiple versions of Node (see the
nvm repo for installation instructions):
$ nvm install
Found '/Users/foo/src/americanpanorama/panorama-template/.nvmrc' with version <0.12.7>
######################################################################## 100.0%
Now using node v0.12.7 (npm v2.11.3)NOTE: you'll need to run nvm install (or nvm use) in each shell instance.
Ensure your npm version is > 2.7.0 (required for support of npm scoped packages):
npm --version
If <= 2.7.0, update npm:
sudo npm install npm -g
Then, install the toolkit:
npm install @panorama/toolkit
The Panorama toolkit comprises a number of components that can be used individually, or wired together with the Panorama Template as a starting point. Below is a list of the components available in the toolkit. Component examples are available here.
Developing new components and modifying existing components requires intermediate knowledge of JavaScript and React, as well as basic familiarity with npm. To get started, clone this repo, cd into the root directory, and install all necessary modules via npm install.
All components are in the src/ folder; examples of components are in the examples/components/ folder. Note that American Panorama components are written in ES6 and use Babel to transpile to ES5 JavaScript. Luke Hoban offers clear examples of features new in ES6; Mozilla Developer Network provides a solid reference.
To create a new component, add a folder to src/ with the name of the component, e.g. MyComponent/. Within, create two files:
MyComponent.jsx: The React componentstyle.scss: Any required styles for the component (optional)
Ensure that MyComponent.jsx imports the style sheet toward the top of the file, like so:
import './style.scss';
Note: if your component is not a view component, it does not need to use React; just create a vanilla JavaScript (.js) file instead. See HashManager.js for an example.
When you are ready to test your component, expose its module to the toolkit bundler by adding it to src/main.js. import the module at the top of the file, and add the module name to the export default block below.
As a general rule, React components should be stateless, and should derive their state from this.props. This article describes the pattern in more detail. Be sure to specify a static propTypes block at the top of the class that both documents and enforces the public API of your component. As much as possible, avoid using state (either React's this.state or property instances, e.g. this.someVar). This ensures maximum flexibility and reusability of your component, and minimizes state-related bugs; state will always flow into the component from the component's parent (usually the root App.jsx file).
Try to avoid adding any but the most basic styles to your component's style.scss file. Consumers of your component should be able to customize appearance as desired, so avoid being overly-specific with your CSS rules, and add classes to any elements that might be styled by an end user so that they can be selected in CSS.
Add an example for your component to examples/. Create a React component in examples/components/ that will load and display your new component. Pass any required and optional props into your new component from this file. Then, import your example component into examples/app.js.
Add documentation for your component as a README.md within your component's folder (src/MyComponent/).
To test your component on the examples page, fire up a local development server by running npm start from the root directory. The server runs on http://localhost:8888/; open a browser to that page to see the examples page.
There are a few ways to make your component available to other projects.
You can point a project's package.json to a GitHub repository in order to pull down and use the HEAD of that repo as the dependency. To do this with the American Panorama toolkit, you would add this to the package.json of your project (not to the toolkit itself!):
"dependencies": {
"@panorama/toolkit": "americanpanorama/panorama",
...
}
Since the toolkit's package.json specifies dist/components.js as the entry point for any application using the toolkit via npm, we need to ensure that our new component is built into dist/components.js and pushed to GitHub. To build your new component, run npm run build:dist from the root directory. (Note: This will lint all the source as well -- watch for and fix any build or lint errors before proceeding!).
Then, git commit the build and git push it to the toolkit repo.
Finally, switch over to your application that is using @panorama/toolkit and uninstall and reinstall the toolkit with these commands:
npm uninstall @panorama/toolkit
npm install @panorama/toolkit
Now, your new component will be available to your project.
You can also link one local project directly to another via npm link. The procedure is explained here; basically this involves setting up a system-wide pointer to your local install of @panorama/toolkit and then symlinking to that install from your application using the toolkit.
This process is less foolproof than pushing builds to GitHub because npm link also symlinks dependencies from @panorama/toolkit's node_modules folder, and this can cause conflicts between / multiple copies of dependencies in the toolkit and in your application. That said, if you get it working it allows you to develop your new component and consume it in your application simultaneously, without the build/push steps above.
Once you're satisfied with the state of your new component, and you have a working example in place, it's time to make it available to the npm-using public! The toolkit has scripts (run from the root directory) set up to ease this process. Here's a quick overview of the process automated by those scripts.
Be certain you know what you're doing and are sure the toolkit is in working order before you run this script! Publishing broken code can break other people's projects if they run npm install, and then you will get angry emails. We don't want angry emails.
Before running this script, you'll have to be logged into npm with username: panorama / email: [email protected]. Contact a @panorama/toolkit administrator for the password. You can either login via npm login or via npm's website.
This script will automatically bump the toolkit version and publish the repo in its current state to npm. It runs .bin/publish-dist.sh, which does these things:
- rebuild the components
- patch the version (
M.m.p->M.m.(p+1)) - commit and push those changes to GitHub
- publish to npm
The script is fairly robust, but if you see any errors, you may need to run these steps manually. They're all visible in the script.
This script updates the examples page. It runs .bin/publish-examples.sh, which simply builds and deploys the examples. There's not much to it, and it's much less risky than npm run publish:dist.
American Panorama is created by the Digital Scholarship Lab at the University of Richmond. Stamen Design designed and developed the initial maps and this toolkit. The Andrew W. Mellon Foundation and the University of Richmond have generously provided funding for American Panorama.