1 | # egjs-persist [![npm version](https://badge.fury.io/js/%40egjs%2Fpersist.svg)](https://badge.fury.io/js/%40egjs%2Fpersist) [![Build Status](https://travis-ci.org/naver/egjs-persist.svg?branch=master)](https://travis-ci.org/naver/egjs-persist) [![Coverage Status](https://coveralls.io/repos/github/naver/egjs-persist/badge.svg?branch=master)](https://coveralls.io/github/naver/egjs-persist?branch=master)
|
2 |
|
3 | Provide cache interface to handle persisted data among history navigation.
|
4 |
|
5 | ## Documents
|
6 | - [Get Started and Demos](https://naver.github.io/egjs-persist/)
|
7 | - [API documentation](https://naver.github.io/egjs-persist/release/latest/doc/)
|
8 |
|
9 | ## Download and Installation
|
10 |
|
11 | Download dist files from repo directly or install it via npm.
|
12 |
|
13 | ### For development (Uncompressed)
|
14 |
|
15 | You can download the uncompressed files for development
|
16 |
|
17 | - Latest : https://naver.github.io/egjs-persist/release/latest/dist/persist.js
|
18 | - Specific version : https://naver.github.io/egjs-persist/release/[VERSION]/dist/persist.js
|
19 |
|
20 | ### For production (Compressed)
|
21 |
|
22 | You can download the compressed files for production
|
23 |
|
24 | - Latest : https://naver.github.io/egjs-persist/release/latest/dist/persist.min.js
|
25 | - Specific version : https://naver.github.io/egjs-persist/release/[VERSION]/dist/persist.min.js
|
26 |
|
27 |
|
28 | ### Installation with npm
|
29 |
|
30 | The following command shows how to install egjs-persist using npm.
|
31 |
|
32 | ```bash
|
33 | $ npm install @egjs/persist
|
34 | ```
|
35 |
|
36 | ## How to use
|
37 | ```js
|
38 | import Persist from "@egjs/persist";
|
39 |
|
40 | const persist = new Persist(key);
|
41 |
|
42 | // Get information about that page.
|
43 | const aInfo = persist.get("a");
|
44 |
|
45 | // Set information about that page.
|
46 | persist.set("a", "aa");
|
47 |
|
48 | // Remove information about that page.
|
49 | persist.remove("a");
|
50 | ```
|
51 |
|
52 | ### Used in SPA
|
53 |
|
54 | We cannot detect changes in history. The entity using the SPA must respond to changes.
|
55 |
|
56 | #### Vanilla
|
57 | ```js
|
58 | import { updateDepth } from "@egjs/persist";
|
59 |
|
60 | const orgPushState = history.pushState;
|
61 |
|
62 | // change pushState function
|
63 | Object.defineProperty(history, "pushState", {
|
64 | configurable: true,
|
65 | value: (...args) => {
|
66 | orgPushState.call(history, ...args);
|
67 | updateDepth();
|
68 | },
|
69 | });
|
70 |
|
71 | // or
|
72 | history.pushState("/aa", "title", {});
|
73 | updateDepth();
|
74 | ```
|
75 |
|
76 | #### React
|
77 | ```jsx
|
78 | import React, { useEffect } from "react";
|
79 | import { Router } from "react-router-dom";
|
80 | import { createBrowserHistory } from "history";
|
81 | import { updateDepth } from "@egjs/persist";
|
82 |
|
83 | const customHistory = createBrowserHistory();
|
84 |
|
85 | export default function App() {
|
86 | useEffect(() => customHistory.listen(() => {
|
87 | updateDepth();
|
88 | }), []);
|
89 | return (
|
90 | <Router history={customHistory}>
|
91 | ...
|
92 | </Router>
|
93 | );
|
94 | }
|
95 | ```
|
96 |
|
97 | #### Vue
|
98 | ```js
|
99 | import VueRouter from "vue-router";
|
100 | import { updateDepth } from "@egjs/persist";
|
101 |
|
102 | const router = new VueRouter();
|
103 |
|
104 | router.afterEach(() => {
|
105 | updateDepth();
|
106 | });
|
107 | ```
|
108 |
|
109 | ## Supported Browsers
|
110 | The following are the supported browsers.
|
111 |
|
112 | |Internet Explorer|Chrome|Firefox|Safari|iOS|Android|
|
113 | |---|---|---|---|---|---|
|
114 | |9+|latest|latest|latest|7+|2.3+ (except 3.x)|
|
115 |
|
116 |
|
117 |
|
118 | ## How to start developing egjs-persist?
|
119 |
|
120 | For anyone interested to develop egjs-persist, follow the instructions below.
|
121 |
|
122 | ### Development Environment
|
123 |
|
124 | #### 1. Clone the repository
|
125 |
|
126 | Clone the egjs-persist repository and install the dependency modules.
|
127 |
|
128 | ```bash
|
129 | # Clone the repository.
|
130 | $ git clone https://github.com/naver/egjs-persist.git
|
131 | ```
|
132 |
|
133 | #### 2. Install dependencies
|
134 | `npm` is supported.
|
135 |
|
136 | ```
|
137 | # Install the dependency modules.
|
138 | $ npm install
|
139 | ```
|
140 |
|
141 | #### 3. Build
|
142 |
|
143 | Use npm script to build eg.Persist
|
144 |
|
145 | ```bash
|
146 | # Run webpack-dev-server for development
|
147 | $ npm start
|
148 |
|
149 | # Build
|
150 | $ npm run build
|
151 |
|
152 | # Generate jsdoc
|
153 | $ npm run jsdoc
|
154 | ```
|
155 |
|
156 | Two folders will be created after complete build is completed.
|
157 |
|
158 | - **dist** folder: Includes the **persist.js** and **persist.min.js** files.
|
159 | - **doc** folder: Includes API documentation. The home page for the documentation is **doc/index.html**.
|
160 |
|
161 | ### Linting
|
162 |
|
163 | To keep the same code style, we adopted [ESLint](http://eslint.org/) to maintain our code quality. The [rules](https://github.com/naver/eslint-config-naver/tree/master/rules) are modified version based on [Airbnb JavaScript Style Guide](https://github.com/airbnb/javascript).
|
164 | Setup your editor for check or run below command for linting.
|
165 |
|
166 | ```bash
|
167 | $ npm run lint
|
168 | ```
|
169 |
|
170 | ### Test
|
171 |
|
172 | Once you created a branch and done with development, you must perform a test running `npm run test` command before you push code to a remote repository.
|
173 |
|
174 | ```bash
|
175 | $ npm run test
|
176 | ```
|
177 | Running a `npm run test` command will start [Mocha](https://mochajs.org/) tests via [Karma-runner](https://karma-runner.github.io/).
|
178 |
|
179 |
|
180 | ## Bug Report
|
181 |
|
182 | If you find a bug, please report it to us using the [Issues](https://github.com/naver/egjs-persist/issues) page on GitHub.
|
183 |
|
184 |
|
185 | ## License
|
186 | egjs-persist is released under the [MIT license](http://naver.github.io/egjs/license.txt).
|
187 |
|
188 |
|
189 | ```
|
190 | Copyright (c) 2015 NAVER Corp.
|
191 |
|
192 | Permission is hereby granted, free of charge, to any person obtaining a copy
|
193 | of this software and associated documentation files (the "Software"), to deal
|
194 | in the Software without restriction, including without limitation the rights
|
195 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
196 | copies of the Software, and to permit persons to whom the Software is
|
197 | furnished to do so, subject to the following conditions:
|
198 |
|
199 | The above copyright notice and this permission notice shall be included in
|
200 | all copies or substantial portions of the Software.
|
201 |
|
202 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
203 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
204 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
205 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
206 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
207 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
|
208 | THE SOFTWARE.
|
209 | ```
|