@mongodb-js/mongodb-ui-components
Version:
A collection of frequently used functional UI components found on mongodb.com
102 lines (62 loc) • 5.45 kB
Markdown
# mongodb-ui-components
### Prerequisites
You must have [node.js](https://nodejs.org/en/) 5.x.x. Were using 5.9 and would recommend installing the latest.
### Getting started
1. Run `npm install`
2. To run development mode: `npm run dev`
3. To build standalone version: `npm run build`
4. To install to a commonjs environment: `npm i @mongodb-js/mongodb-ui-components`
### Coding Style / Guidelines
[](http://standardjs.com/)
This repo follows [standardjs](http://standardjs.com) guidelines.
### Versioning
Since this nav is going to be used across at least 3 sites, we've come to the hard-earned conclusion that versioning is probably a little important. Versioning will be declared in `package.json`. Be sure to check for new versions periodically and test them against your environment.
### Development and Environments
Setting up a dev environment involves simply running `npm run dev` and accessing `localhost:5000` in your favorite browser, such as netscape navigator. Watchers are set up for JS and CSS
This nav displays different content depending on the environment given to its props.
```javascript
ReactDOM.render(
React.createElement(Nav, {
environment: 'docs', // Tells the nav which sections to display
isOpaque: true // Tells the nav if it should have a blackish background on load.
}),
document.getElementById('react-nav-container') // container html element
)
```
The content it decides to display is set in the `/components/nav/jsx/environments/` directory.
Each environment exports an object containing two properties: sections and subsections.
Sections is an array of objects; subsections is an array of [jsx](https://facebook.github.io/react/docs/jsx-in-depth.html) trees.
Sections are displayed right underneath the top white nav. Subsections are the in-detailed subnavs that are toggled by selecting sections.
The order of each section in the array must correspond with each subsection. If a specific section is merely a link and isn't meant to toggle a subsection, just give its corresponding subsection an empty `<div></div>`.
An example for structuring sections and subsections can be found in `/components/nav/jsx/environments/com.jsx`
## How should I incorporate this into my website?
### The Best Way
The "best way" makes a few key assumptions:
1. You are using React in your project.
2. You are using a commonjs environment with node_modules
***Disclaimer***: this is also the most technically challenging method, despite having the largest payoff in terms of performance and development agility.
The absolutely hands-down best way to integrate this nav is via an isomorphic javascript architecture. In this case, this means rendering the Nav Component server side using react's `ReactDOMServer.renderToString()` method, and then hooking up the component client side by calling `ReactDOM.render()` on the Nav's parent with its initial server-side props.
We understand that this may not be possible for every team's architecture, which is why we have the "good way".
### The Good Way
The "good way" makes a few key assumptions:
1. You aren't using React in your project.
2. You aren't using a commonjs environment.
If only and exactly one of these conditions is *true* for you, then please contact Micheal Parks and he'll get working on a "better way" to hastily shove between the "good way" and the "best way" (there will be no negatives here).
First, simply build the nav using `npm run build`.
From this point on, the public folder is your friend. It contains an `index.css` and `index.js` script which will be used for including your very own shiny new MongoDB Navigation Bar©. `test.html` gives a good example for how to assimilate said nav, and we'll quickly walk you through it: specifically what's going on with our `<script>`.
```html
<script
async
id='mongodb-nav-data'
data-props='{"environment":"com","isOpaque":true}'
data-container='#react-nav-root'
src="index.js"></script>
````
Every tag attribute here is pretty mandatory. Two are of importance to your environment.
`data-props` feeds in the initial state of the Nav. Its value is a stringified object with two properties: `environment` and `isOpaque`.
`environment` can have three possible values (so far!) which are `com`, `docs`, and `university`. Set yours appropriately.
`isOpaque` decides if the Nav will sport an opaque black background on page load. Use with your own discretion.
Finally, `data-container` should be given a selector that matches a container that you have set up in your page to house the Nav.
### Search Engine Optimization
We need this nav to be available to search engines and thus it needs to be available in the HTML before client-side JS is run. If you're using the isomorphic method mentioned above, you don't need to worry about anything, this is already handled for you and you probably already know that!
There isn't a pretty way to do this if you're not using the "best way". You'll have to generate the nav in a test environment on your site, peek into dev tools, copy all html within your `<div id='#react-nav-root'></div>` container, and then paste it into your html that's sent from the server as a placeholder until the client-side JS runs. We're working on writing a simple generator that'll make prettier html for you on command, so stay tuned!