1 | # react-vk
|
2 |
|
3 | [VK API](https://vk.com/dev/widgets_for_sites)
|
4 | bindings for React
|
5 |
|
6 | ## Migrate v1 to v2
|
7 |
|
8 | VK now is imported as default!
|
9 |
|
10 | ### Before(v1):
|
11 |
|
12 | ```js
|
13 | import { VK, ... } from 'react-vk';
|
14 |
|
15 | ...
|
16 | ```
|
17 |
|
18 | ### After(v2):
|
19 |
|
20 | ```js
|
21 | import VK, { ... } from 'react-vk';
|
22 |
|
23 | ...
|
24 | ```
|
25 |
|
26 | ## Install
|
27 |
|
28 | Depending on your `react` you need different virsion of package:
|
29 | `react-vk@1.1.5` for `react < 16`
|
30 | `react-vk@1.1.6` for `react > 16.2`
|
31 | `react-vk` for `react > 16.3`
|
32 |
|
33 | ```shell
|
34 | npm install --save react-vk
|
35 | yarn add react-vk
|
36 | ```
|
37 |
|
38 | ## Important note!
|
39 |
|
40 | For local projects run your server on port 80 (This is VK API requirement for local projects)
|
41 | For example using create-react-app in your package.json:
|
42 |
|
43 | ```js
|
44 | "start": "PORT=80 react-scripts start"
|
45 | ```
|
46 |
|
47 | Then:
|
48 |
|
49 | ```shell
|
50 | sudo npm run start
|
51 | ```
|
52 |
|
53 | You need run this command as administrator!
|
54 |
|
55 | ## Components
|
56 |
|
57 | ### Basic components
|
58 |
|
59 | - `<VK apiId={123456} />` - provides child components with vk. apiId - requires
|
60 | - `<AllowMessagesFromCommunity />` - AllowMessagesFromCommunity Widget instance
|
61 | - `<Application />` - App Widget instance
|
62 | - `<Auth />` - Auth Widget instance
|
63 | - `<Comments />` - Comments Widget instance
|
64 | - `<CommentsBrowse />` - CommentsBrowse Widget instance
|
65 | - `<CommunityMessages />` - CommunityMessages Widget instance
|
66 | - `<ContactUs />` - ContactUs Widget instance
|
67 | - `<Group />` - Group Widget instance
|
68 | - `<Like />` - Like Widget instance
|
69 | - `<Playlist />` - Playlist Widget instance
|
70 | - `<Poll />` - Poll Widget instance
|
71 | - `<Post />` - Post Widget instance
|
72 | - `<Recommended />` - Recommended Widget instance
|
73 | - `<Subscribe />` - Subscribe Widget instance
|
74 |
|
75 | #### Information about components
|
76 |
|
77 | Every component has options object, which contains parameters (You can find available fields on VK API for selected widget)
|
78 |
|
79 | - `<VK apiId={number} onApiAvailable={function}/>`
|
80 | requires apiId for init VK. More information on [VK API](https://vk.com/dev/openapi)
|
81 | onApiAvailable - function that provide you access to VK api instance
|
82 |
|
83 | - `<AllowMessagesFromCommunity elementId={string} options={object} groupId={number} onAllow={function} onDeny={function} />`
|
84 | requires groupId for correct work.
|
85 | You can set options by object,
|
86 | elementId - ID of the container element for the module,
|
87 | use functions: onAllow(When "Allow messages" button is pressed),
|
88 | onDeny(If the user denies messages)
|
89 | More information on [VK API](https://vk.com/dev/widget_allow_messages_from_community)
|
90 |
|
91 | - `<Application elementId={string} appId={number} options={object}/>`
|
92 | requires appId for correct work.
|
93 | You can set options by object,
|
94 | elementId - ID of the container element for the module,
|
95 | More information on [VK API](https://vk.com/dev/widget_app)
|
96 |
|
97 | - `<Auth elementId={string} options={object} onAuth={function}/>`
|
98 | You can set options by object,
|
99 | elementId - ID of the container element for the module,
|
100 | use onAuth function(which can use a result of authorization(object with following fields: uid, first_name, last_name, photo, photo_rec, hash)
|
101 | More information on [VK API](https://vk.com/dev/widget_auth)
|
102 |
|
103 | - `<Comments elementId={string} options={object} pageId={string} onNewComment={function} onDeleteComment={function} />`
|
104 | You can set options by object,
|
105 | pageId - ID of the page on your site,
|
106 | elementId - ID of the container element for the module.
|
107 | When a comment is posted or deleted 4 parameters are passed to the handler functions(onNewComment, onDeleteComment):
|
108 | num, last_comment, date, sign
|
109 | More information on [VK API](https://vk.com/dev/widget_comments)
|
110 |
|
111 | - `<CommentsBrowse elementId={string} options={object} />`
|
112 | You can set options by object,
|
113 | pageId - ID of the page on your site,
|
114 | elementId - ID of the container element for the module.
|
115 | More information on [VK API](https://vk.com/dev/widget_comments)
|
116 |
|
117 | - `<CommunityMessages elementId={string} options={object} groupId={number} onMount={function} />`
|
118 | requires groupId for correct work.
|
119 | You can set options by object,
|
120 | elementId - ID of the container element for the module,
|
121 | onMount = function that get mounted widget and elementId for extra actions:
|
122 | destroy — deletes the widget(requires elementId);
|
123 | expand — expands widget frame, may take welcomeScreen parameter (1 to show the welcome screen);
|
124 | stopTitleAnimation — disables title animation when new message received;
|
125 | minimize — minimizes widget frame.
|
126 | More information on [VK API](https://vk.com/dev/widget_community_messages)
|
127 |
|
128 | - `<ContactUs elementId={string} options={object} ownerId={number} />`
|
129 | requires ownerId for correct work.
|
130 | You can set options by object,
|
131 | elementId - ID of the container element for the module
|
132 | More information on [VK API](https://vk.com/dev/widget_contact_us)
|
133 |
|
134 | - `<Group elementId={string} groupId={number} options={object} onJoin={function} onLeave={function} />`
|
135 | requires groupId for correct work.
|
136 | You can set options by object,
|
137 | elementId - ID of the container element for the module,
|
138 | When the 'Follow on VK' button is clicked your can use onJoin and onLeave functions
|
139 | More information on [VK API](https://vk.com/dev/widget_community)
|
140 |
|
141 | - `<Like elementId={string} options={object} pageId={string} onLike={function} onUnlike={function} onShare={function} onUnshare={function} />`
|
142 | You can set options by object,
|
143 | elementId - ID of the container element for the module,
|
144 | pageId - ID of the page on your site,
|
145 | When Like button is clicked you can use onLike and onUnlike functions. You can use number of Likes for the current page as a parameter.
|
146 | Similar when Share With Friends is selected
|
147 |
|
148 | ### Important note!
|
149 |
|
150 | According to documentation VK Like component require page_id if we need two or more independent likes on single page. So if you are using SPA - pageId attribute is required!
|
151 |
|
152 | More information on [VK API](https://vk.com/dev/widget_like)
|
153 |
|
154 | - `<Playlist elementId={string} ownerId={number} playlistId={number} hash={string} options={object} />`
|
155 | For correct works requires ownerId, playlistId, hash(service parameter. hash can be obtained in the constructor only.)
|
156 | You can set options by object,
|
157 | elementId - ID of the container element for the module
|
158 | More information on [VK API](https://vk.com/dev/widget_playlist)
|
159 |
|
160 | - `<Poll elementId={string} options={object} pollId={string} />`
|
161 | requires pollId for correct work(You can get it using the form on https://vk.com/dev/Poll or with a button "Get code" in the existing poll)
|
162 | You can set options by object,
|
163 | elementId - ID of the container element for the module
|
164 | More information on [VK API](https://vk.com/dev/widget_poll)
|
165 |
|
166 | - `<Post elementId={string} options={object} ownerId={number} postId={number} hash={string} />`
|
167 | For correct works requires ownerId, postId, hash(You can get hash in widget's constructor or "Export" window only.)
|
168 | You can set options by object,
|
169 | elementId - ID of the container element for the module
|
170 | More information on [VK API](https://vk.com/dev/widget_post)
|
171 |
|
172 | - `<Recommended elementId={string} options={object} />`
|
173 | You can set options by object,
|
174 | elementId - ID of the container element for the module
|
175 | More information on [VK API](https://vk.com/dev/widget_recommended)
|
176 |
|
177 | - `<Subscribe elementId={string} options={object} ownerId={number} onSubscribe={function} onUnsubscribe={function} />`
|
178 | requires ownerId for correct work.
|
179 | You can set options by object,
|
180 | elementId - ID of the container element for the module,
|
181 | when user subscribes, you can use onSubscribe function; when user unsubscribes — onUnsubscribe.
|
182 | More information on [VK API](https://vk.com/dev/widget_recommended)
|
183 | https://vk.com/dev/widget_subscribe
|
184 |
|
185 | ## Basic usage
|
186 |
|
187 | ### Setup
|
188 |
|
189 | #### With VK API
|
190 |
|
191 | ```js
|
192 | window.onload = function() {
|
193 | VK.init({ apiId: 123456 });
|
194 | };
|
195 | ```
|
196 |
|
197 | #### With react-vk
|
198 |
|
199 | ```js
|
200 | import { VK } from "react-vk";
|
201 |
|
202 | const App = () => {
|
203 | return <VK apiId={123456} />;
|
204 | };
|
205 | ```
|
206 |
|
207 | ### Components
|
208 |
|
209 | #### With VK API
|
210 |
|
211 | ```js
|
212 | window.onload = function() {
|
213 | VK.init({ apiId: 123456 });
|
214 | VK.Widgets.Auth("vk_auth", {});
|
215 | };
|
216 | ```
|
217 |
|
218 | ### With react-vk
|
219 |
|
220 | ```js
|
221 | import { VK, Auth } from "react-vk";
|
222 |
|
223 | const App = () => {
|
224 | return (
|
225 | <VK apiId={123456}>
|
226 | <Auth />
|
227 | </VK>
|
228 | );
|
229 | };
|
230 | ```
|
231 |
|
232 | ### Functions
|
233 |
|
234 | #### With VK API
|
235 |
|
236 | ```js
|
237 | <script type="text/javascript" src="//vk.com/js/api/openapi.js?122"></script>
|
238 |
|
239 | <script type="text/javascript">
|
240 | VK.init({apiId: 123456});
|
241 | </script>
|
242 | <div id="vk_like"></div>
|
243 | <script type="text/javascript">
|
244 | VK.Widgets.Like("vk_like", {type: "button"});
|
245 | VK.Observer.subscribe("widgets.subscribed", function f() {
|
246 | alert ("Thank you!");
|
247 | });
|
248 | </script>
|
249 | ```
|
250 |
|
251 | ### With react-vk
|
252 |
|
253 | ```js
|
254 | import { VK, Subscribe } from "react-vk";
|
255 |
|
256 | const App = () => {
|
257 | return (
|
258 | <VK apiId={123456}>
|
259 | <Subscribe
|
260 | ownerId={17437657}
|
261 | onSubscribe={() => {
|
262 | alert("Thank you!");
|
263 | }}
|
264 | />
|
265 | </VK>
|
266 | );
|
267 | };
|
268 | ```
|
269 |
|
270 | ### Using CommunityMessages
|
271 |
|
272 | #### With VK API
|
273 |
|
274 | ```js
|
275 | <div id="vk_community_messages"></div>
|
276 | <script type="text/javascript">
|
277 | var widget = VK.Widgets.CommunityMessages("vk_community_messages", 20003922);
|
278 | widget.stopTitleAnimation();
|
279 | widget.expand({
|
280 | welcomeScreen: 1,
|
281 | });
|
282 | </script>
|
283 | ```
|
284 |
|
285 | ### With react-vk
|
286 |
|
287 | ```js
|
288 | import React, { Component } from 'react';
|
289 | import { VK, CommunityMessages } from 'react-vk';
|
290 |
|
291 | class App extends Component {
|
292 | state = {
|
293 | widget: null,
|
294 | id: null,
|
295 | };
|
296 |
|
297 | handleClick = () => {
|
298 | this.state.widget.destroy(this.state.id);
|
299 | };
|
300 |
|
301 | render() {
|
302 | return (
|
303 | <div>
|
304 | <button onClick={this.handleClick}>Delete CommunityMessages</button>
|
305 | <VK apiId={123456}>
|
306 | <CommunityMessages
|
307 | groupId={127607773}
|
308 | onMount={(widget, id) => {
|
309 | this.setState({ widget, id });
|
310 | }}
|
311 | />
|
312 | </VK>
|
313 | </div>
|
314 | );
|
315 | ```
|
316 |
|
317 | ## More details and examples
|
318 |
|
319 | You can clone this repository and check more examples
|
320 |
|
321 | ```shell
|
322 | git clone https://github.com/mmarkelov/react-vk.git
|
323 | cd ./react-vk/examples
|
324 | npm install && npm run dev
|
325 | ```
|
326 |
|
327 | Also you can check them [here](https://mmarkelov.github.io/react-vk/)
|
328 |
|
329 | ## TODO
|
330 |
|
331 | - [ ] Add more tests
|
332 |
|
333 | ## Acknowledgements
|
334 |
|
335 | - Thanks to [@gribnoysup](https://github.com/gribnoysup/) and his [react-yandex-maps](https://github.com/gribnoysup/react-yandex-maps) for inspiration and motivation.
|
336 | - Thanks to [@seeden](https://github.com/seeden/) and his [react-facebook](https://github.com/seeden/react-facebook) for inspiration and motivation.
|
337 | - Lots of features were founded in these perfect packages.
|