1 | # Squidex Client Manager [![npm version](https://badge.fury.io/js/squidex-client-manager.svg)](https://badge.fury.io/js/squidex-client-manager) [![CircleCI](https://circleci.com/gh/scanf/squidex-client-manager.svg?style=svg)](https://circleci.com/gh/scanf/squidex-client-manager)
|
2 |
|
3 | [![Powered by Squidex](./GitHub/power-by.png)](https://squidex.io)
|
4 |
|
5 | This is a wrapper around the swagger [API][a] provided by Squidex.
|
6 |
|
7 | > The project is still a in early phase so the featureset is limited.
|
8 |
|
9 | Please note all examples below use `cloud.squidex.io` in the examples but you
|
10 | can easily change out the `https://cloud.squidex.io/api` portion with the
|
11 | following format `https://<my-server-url>/api/` for self-hosted version.
|
12 |
|
13 | ## What is Squidex?
|
14 |
|
15 | [Squidex][s] is a open source headless CMS. To learn more about it checkout the
|
16 | following links:
|
17 |
|
18 | - [Docker containers](https://github.com/squidex/squidex-dockers)
|
19 | - [Source code](https://github.com/squidex/squidex)
|
20 | - [Documentation](https://docs.squidex.io)
|
21 | - [Hosted][s]
|
22 |
|
23 | ## Usage
|
24 |
|
25 | You need to setup the client before using it. The minimal requirement is the
|
26 | URL for the OpenAPI specification and valid client credentials.
|
27 |
|
28 | 1. To find the API spec URL visit `https://cloud.squidex.io/api/content/<my-app>/docs`
|
29 | 2. For getting values for the client see `https://cloud.squidex.io/app/<my-app>/settings/clients`
|
30 |
|
31 | When you have those values you can setup the client. Note that all examples
|
32 | below assume you are running in an `async` function.
|
33 |
|
34 | ### Setting up the client
|
35 |
|
36 | ```javascript
|
37 | const { SquidexClientManager } = require('squidex-client-manager');
|
38 |
|
39 | const client = new SquidexClientManager(
|
40 | url: 'https://cloud.squidex.io/identity-server/connect/token',
|
41 | clientId: 'my-blog-squidex:developer',
|
42 | clientSecret: 'my-secret',
|
43 | // cacheFile is not required but useful for debugging
|
44 | cacheFile: '/tmp/optional-field-for-debug-cache-file.json'
|
45 | );
|
46 |
|
47 | try {
|
48 | let specUrl = 'https://cloud.squidex.io/api/content/<my-app>/swagger/v1/swagger.json'
|
49 | await client.ConfigureAsync(specUrl);
|
50 | } catch (error) {
|
51 | console.log('Failed to setup the CMS. Please check token is setup!');
|
52 | console.error(error);
|
53 | }
|
54 |
|
55 | ```
|
56 |
|
57 | ### Retrieving records
|
58 |
|
59 | By default only `20` records are returned, the max is `200` but setting it to
|
60 | `0` will return all of them.
|
61 |
|
62 | ```javascript
|
63 | const records = await client.RecordsAsync('Articles', { top: 0 })
|
64 | console.log(JSON.stringify(records, null, 2))
|
65 | /* Output:
|
66 | [squidex-client-manager][debug]: Records(Articles, [object Object])
|
67 | [squidex-client-manager][debug]: GetModelByName(Articles)
|
68 | {
|
69 | "total": 1,
|
70 | "items": [
|
71 | {
|
72 | "id": "ffcbecb0-07a0-45f5-9b8e-bf53059fe25d",
|
73 | "createdBy": "subject:5ce8610ec020db00018051c7",
|
74 | "lastModifiedBy": "subject:5ce8610ec020db00018051c7",
|
75 | "data": {
|
76 | "title": {
|
77 | "iv": "Hello Squidex"
|
78 | },
|
79 | "text": {
|
80 | "iv": "## Testing markdown support"
|
81 | }
|
82 | },
|
83 | "isPending": false,
|
84 | "created": "2019-06-12T17:24:38Z",
|
85 | "lastModified": "2019-06-12T17:24:38Z",
|
86 | "status": "Published",
|
87 | "version": 1
|
88 | }
|
89 | ]
|
90 | }
|
91 | */
|
92 | ```
|
93 |
|
94 | ### Retrieving a record
|
95 |
|
96 | ```javascript
|
97 | const records = await client.RecordAsync('Articles', {
|
98 | id: '4bb3a7bb-962d-4183-9ca6-35d170c34f3b'
|
99 | })
|
100 | console.log(JSON.stringify(records, null, 2))
|
101 | /* Output:
|
102 | [squidex-client-manager][debug]: Record(Articles, [object Object])
|
103 | [squidex-client-manager][debug]: GetModelByName(Articles)
|
104 | {
|
105 | "title": {
|
106 | "iv": "Testo-Wed Jun 12 2019 20:11:19 GMT+0200 (Central European Summer Time)"
|
107 | }
|
108 | } */
|
109 | ```
|
110 |
|
111 | ### Creating a record
|
112 |
|
113 | ```javascript
|
114 | const title = 'My post'
|
115 | const body = `
|
116 | ## topic 1
|
117 |
|
118 | Lorem ipsum dolor sit amet, quo ne malis saperet fierent, has ut vivendo
|
119 | imperdiet disputando, no cum oratio abhorreant. Agam accusata prodesset cu
|
120 | pri, qui iudico constituto constituam an. Ne mel liber libris expetendis, per
|
121 | eu imperdiet dignissim. Pro ridens fabulas evertitur ut.
|
122 | `
|
123 | const expected = {
|
124 | data: { title: { iv: title }, text: { iv: body } },
|
125 | publish: true
|
126 | }
|
127 | const article = await client.CreateAsync('Articles', expected)
|
128 | console.log(JSON.stringify(article, null, 2))
|
129 | /* Output:
|
130 | [squidex-client-manager][debug]: Create(Articles, [object Object])
|
131 | [squidex-client-manager][debug]: GetModelByName(Articles)
|
132 | {
|
133 | "id": "cdbcb9f7-f6f6-4a6a-81d9-0c6f9cf385f8",
|
134 | "createdBy": "client:my-blog-squidex:developer",
|
135 | "lastModifiedBy": "client:my-blog-squidex:developer",
|
136 | "data": {
|
137 | "title": {
|
138 | "iv": "My post"
|
139 | },
|
140 | "text": {
|
141 | "iv": "\n ## topic 1\n \n Lorem ipsum dolor sit amet, quo ne malis saperet fierent, has ut vivendo\n imperdiet disputando, no cum oratio abhorreant. Agam accusata prodesset cu\n pri, qui iudico constituto constituam an. Ne mel liber libris expetendis, per\n eu imperdiet dignissim. Pro ridens fabulas evertitur ut.\n "
|
142 | }
|
143 | },
|
144 | "isPending": false,
|
145 | "created": "2019-06-12T18:22:51Z",
|
146 | "lastModified": "2019-06-12T18:22:51Z",
|
147 | "status": "Published",
|
148 | "version": 1
|
149 | }
|
150 | */
|
151 | ```
|
152 |
|
153 | ### Deleting a record
|
154 |
|
155 | ```javascript
|
156 | const deleted = await client.DeleteAsync('Articles', {
|
157 | id: 'cdbcb9f7-f6f6-4a6a-81d9-0c6f9cf385f8'
|
158 | })
|
159 | console.log(JSON.stringify(deleted, null, 2))
|
160 | /* Output:
|
161 | [squidex-client-manager][debug]: Delete(Articles, [object Object])
|
162 | [squidex-client-manager][debug]: GetModelByName(Articles)
|
163 | {
|
164 | "ok": true,
|
165 | "url": "https://cloud.squidex.io/api/content/my-blog-squidex/articles/cdbcb9f7-f6f6-4a6a-81d9-0c6f9cf385f8/",
|
166 | "status": 204,
|
167 | "statusText": "No Content",
|
168 | "headers": {
|
169 | "date": "Wed, 12 Jun 2019 18:26:10 GMT",
|
170 | "connection": "close",
|
171 | "set-cookie": "__cfduid=d8ef8efcbcf5e2fb0d137c4ad4f26edf41560363970; expires=Thu, 11-Jun-20 18:26:10 GMT; path=/; domain=.squidex.io; HttpOnly; Secure",
|
172 | "etag": "W/2",
|
173 | "expect-ct": "max-age=604800, report-uri=\"https://report-uri.cloudflare.com/cdn-cgi/beacon/expect-ct\"",
|
174 | "server": "cloudflare",
|
175 | "cf-ray": "4e5ddf1eaef0cae4-ARN"
|
176 | },
|
177 | "text": {
|
178 | "type": "Buffer",
|
179 | "data": []
|
180 | },
|
181 | "data": {
|
182 | "type": "Buffer",
|
183 | "data": []
|
184 | }
|
185 | }
|
186 | */
|
187 | ```
|
188 |
|
189 | ### Updating a record
|
190 |
|
191 | ```javascript
|
192 | const update = await client.UpdateAsync('Articles', {
|
193 | id: '4bb3a7bb-962d-4183-9ca6-35d170c34f3b',
|
194 | data: {
|
195 | title: { iv: 'the title is updated' },
|
196 | text: { iv: `the article text` }
|
197 | }
|
198 | })
|
199 | console.log(JSON.stringify(update, null, 2))
|
200 | /* Output:
|
201 | [squidex-client-manager][debug]: Update(Articles, [object Object])
|
202 | [squidex-client-manager][debug]: GetModelByName(Articles)
|
203 | {
|
204 | "title": {
|
205 | "iv": "the title is updated"
|
206 | },
|
207 | "text": {
|
208 | "iv": "the article text"
|
209 | }
|
210 | }
|
211 | */
|
212 | ```
|
213 |
|
214 | ### Create or update a record
|
215 |
|
216 | ```javascript
|
217 | const createOrUpdate = await client.CreateOrUpdateAsync(
|
218 | 'Articles',
|
219 | {
|
220 | id: '4bb3a7bb-962d-4183-9ca6-35d170c34f3b',
|
221 | data: {
|
222 | title: { iv: 'title here is used as unique value for comparison' },
|
223 | text: { iv: 'y' }
|
224 | }
|
225 | },
|
226 | 'title'
|
227 | )
|
228 | console.log(JSON.stringify(createOrUpdate, null, 2))
|
229 | /* Output:
|
230 | [squidex-client-manager][debug]: CreateOrUpdate(Articles, [object Object], title)
|
231 | [squidex-client-manager][debug]: filter Articles where title eq title here is used as unique value for comparison
|
232 | [squidex-client-manager][debug]: Records(Articles, [object Object])
|
233 | [squidex-client-manager][debug]: GetModelByName(Articles)
|
234 | [squidex-client-manager][debug]: Create(Articles, [object Object])
|
235 | [squidex-client-manager][debug]: GetModelByName(Articles)
|
236 | {
|
237 | "id": "3b6c5b1c-51bd-45a2-8c07-736286c71b67",
|
238 | "createdBy": "client:my-blog-squidex:developer",
|
239 | "lastModifiedBy": "client:my-blog-squidex:developer",
|
240 | "data": {
|
241 | "title": {
|
242 | "iv": "title here is used as unique value for comparison"
|
243 | },
|
244 | "text": {
|
245 | "iv": "y"
|
246 | }
|
247 | },
|
248 | "isPending": false,
|
249 | "created": "2019-06-12T18:44:00Z",
|
250 | "lastModified": "2019-06-12T18:44:00Z",
|
251 | "status": "Draft",
|
252 | "version": 0
|
253 | }
|
254 | */
|
255 | ```
|
256 |
|
257 | ### Filtering
|
258 |
|
259 | The current implementation of filtering only supports comparisons i.e only
|
260 | `eq`. If you have use case that requests the full support of [OData
|
261 | Conventions][oc], please reach out by creating a [issue][i].
|
262 |
|
263 | If you only want to use `eq` then the following example should suffice
|
264 |
|
265 | ```javascript
|
266 | const input = { data: { title: { iv: 'Hello Squidex' } }, publish: true }
|
267 | const filter = await client.FilterRecordsAsync('Articles', input, 'title')
|
268 | console.log(JSON.stringify(filter, null, 2))
|
269 | /* Output:
|
270 | [squidex-client-manager][debug]: filter Articles where title eq Hello Squidex
|
271 | [squidex-client-manager][debug]: Records(Articles, [object Object])
|
272 | [squidex-client-manager][debug]: GetModelByName(Articles)
|
273 | [
|
274 | {
|
275 | "id": "ffcbecb0-07a0-45f5-9b8e-bf53059fe25d",
|
276 | "createdBy": "subject:5ce8610ec020db00018051c7",
|
277 | "lastModifiedBy": "subject:5ce8610ec020db00018051c7",
|
278 | "data": {
|
279 | "title": {
|
280 | "iv": "Hello Squidex"
|
281 | },
|
282 | "text": {
|
283 | "iv": "## Testing markdown support"
|
284 | }
|
285 | },
|
286 | "isPending": false,
|
287 | "created": "2019-06-12T17:24:38Z",
|
288 | "lastModified": "2019-06-12T17:24:38Z",
|
289 | "status": "Published",
|
290 | "version": 1
|
291 | }
|
292 | ]
|
293 | */
|
294 | ```
|
295 |
|
296 | #### Find open
|
297 |
|
298 | ```javascript
|
299 | const record = await client.FindOne('Articles', 'title', 'Hello Squidex')
|
300 | console.log(JSON.stringify(record, null, 2))
|
301 | /* Output:
|
302 | [squidex-client-manager][debug]: Records(Articles, [object Object])
|
303 | [squidex-client-manager][debug]: GetModelByName(Articles)
|
304 | {
|
305 | "id": "ffcbecb0-07a0-45f5-9b8e-bf53059fe25d",
|
306 | "createdBy": "subject:5ce8610ec020db00018051c7",
|
307 | "lastModifiedBy": "subject:5ce8610ec020db00018051c7",
|
308 | "data": {
|
309 | "title": {
|
310 | "iv": "Hello Squidex"
|
311 | },
|
312 | "text": {
|
313 | "iv": "## Testing markdown support"
|
314 | }
|
315 | },
|
316 | "isPending": false,
|
317 | "created": "2019-06-12T17:24:38Z",
|
318 | "lastModified": "2019-06-12T17:24:38Z",
|
319 | "status": "Published",
|
320 | "version": 1
|
321 | }
|
322 | */
|
323 | ```
|
324 |
|
325 | ## Disclaimer
|
326 |
|
327 | This project is not affiliated with [Squidex][0] and is an unofficial client.
|
328 | The project is developed and maintained by [Alexander Alemayhu][twitter] for [Fortress][f].
|
329 |
|
330 | ## Troubleshooting
|
331 |
|
332 | 0. Make sure your client has enough permissions (recommended role for testing is `Developer`).
|
333 | 1. Make sure the model name you are querying is the same in the Squidex schema.
|
334 | 2. Check your token is valid.
|
335 |
|
336 | [a]: https://docs.squidex.io/guides/02-api
|
337 | [0]: https://squidex.io/
|
338 | [twitter]: https://twitter.com/aalemayhu
|
339 | [oc]: https://docs.squidex.io/guides/02-api#odata-conventions
|
340 | [i]: https://github.com/scanf/squidex-client-manager/issues/new
|
341 | [s]: https://squidex.io
|
342 | [f]: https://fortress.no/
|