1 | [![Build Status](https://travis-ci.org/Pearson-Higher-Ed/drawer.svg?branch=master)](https://travis-ci.org/Pearson-Higher-Ed/drawer)
|
2 |
|
3 | ## Drawer
|
4 |
|
5 | The drawer component offers a convenient method for presenting secondary information which doesn't need to be immediately visible.
|
6 |
|
7 | UX Framework Design Page:
|
8 | [http://uxframework.pearson.com/c/drawer/](http://uxframework.pearson.com/c/drawer/)
|
9 |
|
10 | Demo Page:
|
11 | [http://pearson-higher-ed.github.io/drawer/](http://pearson-higher-ed.github.io/elements-sdk)
|
12 |
|
13 | ## Getting Started
|
14 |
|
15 | Initial Machine Setup
|
16 | Install Git.
|
17 | Install Node 6.0.0 or greater - Need to run multiple versions of Node? Use nvm.
|
18 | On a Mac? You're all set. If you're on Windows, complete the steps for your OS below.
|
19 | On Windows:
|
20 |
|
21 | Install Ruby as the runtime engine for SCSS.
|
22 | Install Python 2.7. Some node modules may rely on node-gyp, which requires Python on Windows.
|
23 | On Chrome browser:
|
24 |
|
25 | Optionally, install React developer tools.
|
26 |
|
27 | installing the component:
|
28 | ```javascript
|
29 | npm install @pearson-components/drawer --save
|
30 |
|
31 | yarn add @pearson-components/drawer
|
32 | ```
|
33 | ### Quick Start
|
34 | ```javascript
|
35 | git clone https://github.com/Pearson-Higher-Ed/drawer.git
|
36 | cd drawer
|
37 | npm install
|
38 | npm start
|
39 | ```
|
40 | Navigate to http://localhost:8081/drawer/, where the spawned Node server hosts a webpack-generated SPA using React Router for defining how to render the components.
|
41 |
|
42 | As you save changes to the source, the changes are automatically reloaded in the browser.
|
43 |
|
44 | ### Usage
|
45 |
|
46 | To use the Drawer in a React.js page:
|
47 |
|
48 | import the drawer and it's child views:
|
49 | ```javascript
|
50 | import { Drawer, BasicView, DetailView } from "@pearson-components/drawer";
|
51 | ```
|
52 | then configure the drawer and it's views:
|
53 |
|
54 | ```javascript
|
55 | this.state = {
|
56 | drawerTop : "61px",
|
57 | drawerIsOpen : false,
|
58 | position : "right",
|
59 | text : {
|
60 | headerTitle : "Basic Title",
|
61 | closeButtonSRText : "Close",
|
62 | backButtonText : "Back"
|
63 | }
|
64 | };
|
65 | ```
|
66 |
|
67 | ```javascript
|
68 | <Drawer
|
69 | drawerTop = {this.state.drawerTop}
|
70 | drawerOpen = {this.state.drawerIsOpen}
|
71 | position = {this.state.position}
|
72 | text = {this.state.text}
|
73 | drawerHandler = {this.drawerHandler}>
|
74 | <div>
|
75 | <BasicView mapToDetail='detailView1' myKind="BasicView">
|
76 | <h2>BasicView1</h2>
|
77 | <ul>
|
78 | <li>hi</li>
|
79 | <li>there</li>
|
80 | </ul>
|
81 | </BasicView>
|
82 | <BasicView myKind="BasicView">
|
83 | <h2>BasicView2</h2>
|
84 | <button>hithere</button>
|
85 | </BasicView>
|
86 | <BasicView mapToDetail='detailView3' myKind="BasicView">
|
87 | <h2>BasicView3</h2>
|
88 | </BasicView>
|
89 | <DetailView id='detailView1' myKind="DetailView">
|
90 | <h3>DetailView1</h3>
|
91 | </DetailView>
|
92 | <DetailView id='detailView3' myKind="DetailView">
|
93 | <details>
|
94 | <summary>Copyright 1999-2014.</summary>
|
95 | <p> - by Data. All Rights Reserved.</p>
|
96 | <p>All content and graphics on this web site are the property of the company Data.</p>
|
97 | </details>
|
98 | </DetailView>
|
99 | </div>
|
100 | </Drawer>
|
101 | ```
|
102 |
|
103 | sample handler:
|
104 | ```javascript
|
105 | _drawerHandler = () => {
|
106 | this.setState({drawerIsOpen:!this.state.drawerIsOpen});
|
107 | }
|
108 | ```
|
109 |
|
110 | BasicViews and DetailViews must be wrapped in a div.
|
111 |
|
112 | BasicView and DetailView must both specify the prop myKind.
|
113 |
|
114 | BasicView may specify a mapToDetail prop. This prop corresponds to a DetailView with the matching id. Clicking on the BasicView will start an animated transition to the DetailView with the corresponding id.
|
115 |
|
116 | example:
|
117 | ```javascript
|
118 | <BasicView mapToDetail='detailView1' myKind="BasicView">
|
119 | <h2>BasicView1</h2>
|
120 | <ul>
|
121 | <li>hi</li>
|
122 | <li>there</li>
|
123 | </ul>
|
124 | </BasicView>
|
125 | <DetailView id='detailView1' myKind="DetailView">
|
126 | <h3>DetailView1</h3>
|
127 | </DetailView>
|
128 | ```
|
129 | props for Drawer:
|
130 | ```javascript
|
131 | position : String - one of:"left","right" default "right"
|
132 | drawerTop : String - adjust drawer top property default "61px"
|
133 | drawerOpen : Boolean - (required) default false default false
|
134 | drawerHandler : Function - (required) sets state of drawerOpen to true or false
|
135 | text : Object - (required) text to be passed in.
|
136 | default {
|
137 | headerTitle : "Basic Title",
|
138 | closeButtonSRText : "Close",
|
139 | backButtonText : "Back"
|
140 | }
|
141 | ```
|
142 |
|
143 | props for BasicView:
|
144 | ```javascript
|
145 | mapToDetail : String - DetailView to be shown, maps to DetailView id.
|
146 | myKind : String - (required) one of:"BasicView","DetailView";
|
147 | ```
|
148 |
|
149 | props for DetailView:
|
150 |
|
151 | ```javascript
|
152 | id : String - (required) BasicView that produces DetailView on click id maps to mapToDetail.
|
153 | myKind : String - (required) one of:"BasicView","DetailView";
|
154 | ```
|
155 |
|
156 | ## Test
|
157 | The project is wired to unit test with [Jest](https://facebook.github.io/jest/).
|
158 |
|
159 | ```javascript
|
160 | npm test
|
161 | ```
|
162 | After running npm test && npm start, you may view the code coverage site at: http://localhost:8081/coverage/lcov-report
|
163 |
|
164 | ## Event Instantiation
|
165 | Non React Apps may use the event harness by pulling in the eventInterface from the build directory. To instantiate a component use this format:
|
166 |
|
167 | ```javascript
|
168 | document.body.dispatchEvent(new CustomEvent('o.InitComponent', {
|
169 | detail: {
|
170 | elementId: 'drawer',
|
171 | props: {
|
172 | text: {
|
173 | headerTitle : "Basic Title",
|
174 | closeButtonSRText : "Close",
|
175 | backButtonText : "Back"
|
176 | },
|
177 | drawerOpen: true,
|
178 | position:"right",
|
179 | drawerTop:"61px",
|
180 | drawerHandler: () => {},
|
181 | children: React.createElement('div', {},
|
182 | React.createElement(BasicView,{mapToDetail:'detailView1',myKind:'BasicView'},
|
183 | React.createElement('p',{},'hi')
|
184 | ),
|
185 | React.createElement(DetailView,{id:'detailView1',myKind:'DetailView'},
|
186 | React.createElement('p',{},'there')
|
187 | )
|
188 | )
|
189 | }
|
190 | }
|
191 | }
|
192 | ));
|
193 | ```
|
194 |
|
195 |
|
196 | ## External Dependencies
|
197 | React and ReactDOM (v0.14 or v15) are external dependencies required to use this component. They are npm-installable or available from a third-party CDN.
|
198 |
|
199 | This component targets the styling in the Pearson Elements SDK.
|
200 |
|
201 | ### Polyfills
|
202 | React components with internationalisation use React-Intl which relies on the ECMAScript Internationalisation API. This was not supported in Safari until version 10. If you are supporting Safari older than 10, there is a polyfill from Andy Earnshaw (see below).
|
203 |
|
204 | CustomEvent support in IE is also polyfilled. Because many teams are supporting both IE 11 and Safari 9, we've combined the polyfills into a single script. The example below polyfills for CustomEvent and localisation for English and French:
|
205 |
|
206 | <script src="https://cdn.polyfill.io/v2/polyfill.js?features=CustomEvent,Intl.~locale.en,Intl.~locale.fr"></script>
|
207 | Be sure to include the above script (a version of it that makes sense for your project and supported browsers) on your HTML page running CompoundsSDK, if you need it.
|
208 |
|
209 | ## CodeCoverage site
|
210 | After running npm test && npm start, you may view the code coverage site at: http://localhost:8081/coverage/lcov-report
|
211 |
|
212 | ## Guidelines
|
213 | All submissions must be via pull request and approved before the pearson-design-accelerator@pearson.com team will merge and allow it to enter the release process. All submissions must pass this project's linting, test with 100% code coverage, and be compatible with the version(s) of React approved for the Pearson User Experience Platform.
|
214 |
|
215 | ## License
|
216 |
|
217 | This software is published by Pearson Education under the [MIT license](LICENSE).
|