Skip to content

Commit 96213ca

Browse files
authored
Client Readme: query builder pattern (dotCMS#32555)
### Proposed Changes Added table with query builder syntax methods, plus one more large example including all of them. ### Checklist - [ ] Please review to ensure it is up to date - I don't know if the QueryBuilder object is still in direct use, as it was when I wrote it. E.g.: ``` let queryBuilder = new QueryBuilder(); const myQuery = queryBuilder .field('contentType') .equals('Blog') ... ```
1 parent 240ed26 commit 96213ca

File tree

1 file changed

+43
-3
lines changed

1 file changed

+43
-3
lines changed

core-web/libs/sdk/client/README.md

Lines changed: 43 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -372,6 +372,46 @@ const filtered = await client.content
372372
.sortBy([{ field: 'publishDate', direction: 'desc' }]);
373373
```
374374

375+
The table below outlines the builder pattern's methods:
376+
377+
| QueryBuilder Method | Type | Result | Explanation |
378+
|------------------------|-------------|--------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
379+
| `.field('foo')` | Field | `foo:{bar}` | Defines a [field name](https://dev.dotcms.com/docs/field-properties#VariableNames) to query, awaiting a value to be supplied via the `.equals()` method. Multiple such assignments can be made if joined together via operator methods such as `or()`. |
380+
| `.excludeField('foo')` | Field | `-foo:{bar}` | Defines a field name to exclude from the query, awaiting a value to be supplied via the `.equals()` method, or several combined through operators. |
381+
| `.equals('bar')` | Assignment | `{foo:}bar` | Supplies a value to a preceding field method. Multiple `.equals()` calls may be joined through operator methods. |
382+
| `.raw('foo')` | Raw | `foo` | Adds raw input as output to the query; requires use of Lucene syntax directly. |
383+
| `.and()` | Operator | ` AND ` | Joins two query clauses — whether assignments or field/assignment pairs — such that results will be returned when both halves apply. |
384+
| `.or()` | Operator | ` OR ` | Joins two query clauses such that results will be returned when at least one half applies. |
385+
| `.not()` | Operator | ` NOT ` | Unary operator; query will return only results where the subsequent clause does not apply. |
386+
| `.build()` | Constructor | *n/a* | Outputs query string. |
387+
388+
The following example displays all of the builder class's methods, generating a complex Lucene query:
389+
390+
```js
391+
let queryBuilder = new QueryBuilder();
392+
const myQuery = queryBuilder
393+
.field('contentType')
394+
.equals('Blog')
395+
.or()
396+
.equals('Activity')
397+
.excludeField('conhost')
398+
.equals('my-super-cool-site')
399+
.field('languageId')
400+
.equals('2') // spanish
401+
.and()
402+
.field('deleted')
403+
.equals('false')
404+
.raw('+summary:Snowboard')
405+
.not()
406+
.equals('Swiss Alps')
407+
.build();
408+
```
409+
410+
The above `myQuery` variable will have the following value:
411+
> +contentType:Blog OR Activity -conhost:my-super-cool-site +languageId:2 AND +deleted:false +summary:Snowboard NOT "Swiss Alps"
412+
413+
For additional examples, see the [specification page](src/lib/client/content/builders/query/query.spec.ts), or the examples below.
414+
375415
#### Search and Paginate Product Results by Title and Price
376416

377417
```ts
@@ -561,7 +601,7 @@ By default, the `@dotcms/client` SDK is **read-only**. It's designed to fetch co
561601

562602
To make your pages editable using the dotCMS **Universal Visual Editor (UVE)**, you'll need to pair this SDK with one of our supported front-end integrations.
563603

564-
### Use an Official SDK:
604+
### Use an Official SDK:
565605

566606
If you're using a modern JavaScript framework like React or Angular, we strongly recommend starting with one of our official UVE integrations. These pair the `@dotcms/client` SDK with framework-specific tooling for the Universal Visual Editor:
567607

@@ -585,9 +625,9 @@ These integrations come pre-wired with everything you need to:
585625
If you’re building with a framework we don’t yet support, you can build your own UVE integration using the low-level [`@dotcms/uve`](https://github.com/dotCMS/core/tree/main/core-web/libs/sdk/uve) package.
586626

587627
> **This is not a recommended path.**
588-
>
628+
>
589629
> Custom UVE implementations are complex, require a deep understanding of dotCMS internals, and are not actively supported.
590-
>
630+
>
591631
> This route is intended only for advanced use cases, such as wiring up layout rendering, editable regions, and UVE behavior manually.
592632
593633
That said, if you’re experienced and want to explore it, you can [review the `@dotcms/uve` source and docs here](https://github.com/dotCMS/core/tree/main/core-web/libs/sdk/uve).

0 commit comments

Comments
 (0)