Skip to content

Commit 49bdfff

Browse files
widozwidoz
authored
Add Documentation
Introduce base documentation for developers #17
1 parent 4734a3b commit 49bdfff

File tree

17 files changed

+872
-2
lines changed

17 files changed

+872
-2
lines changed

‎LICENSE

Lines changed: 339 additions & 0 deletions
Large diffs are not rendered by default.

‎README.md

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# WordPress Entities Search
2+
3+
This package is a library exposing reusable Components and Utilities to help you build Entities searching and storage.
4+
5+
At it's core it permits to build components and reuse the WordPress Rest API to search for Posts associated to one or
6+
more Post Types but also, to search for Terms belonging to one or more Taxonomies.
7+
8+
## Table of Content
9+
10+
1. [Installation](./docs/installation.md)
11+
2. [Development](./docs/development.md)
12+
3. [Api](./docs/api.md)
13+
4. [Components](./docs/components.md)
14+
5. [Hooks](./docs/hooks.md)
15+
6. [Logging](./docs/logging.md)
16+
7. [Storage](./docs/storage.md)
17+
18+
## License
19+
20+
This software is released under the ["GNU General Public License v2.0 or later"](./LICENSE) license.

‎docs/api.md

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
# Api
2+
3+
The `api` define a `fetch` function which is there to hide the WordPress Fetch API. The reason behind this decision lies on the fact that we might want to add middlewares to the request in the future or introducing some global data manipulation.
4+
5+
The package provide then the following functions to interact with the WordPress API:
6+
7+
## `searchEntities`
8+
9+
This function is a wrapper for the Search Endpoint of the WordPress API. It will return a `Set` of entities matching the search query.
10+
11+
The possible query arguments are specified by the `EntitiesSearch.QueryArguments` type, an interface you can expand to add more arguments.
12+
13+
This function is not directly consumed by the components, and it is not intended to be used internally. The idea is to follow the Tell don't Ask principle and let the consumer specify how to search the Entities.
14+
15+
Below a possible example of its usage related to a component:
16+
17+
```tsx
18+
// my-component.tsx
19+
type Search = EntitiesSearch.SearchEntitiesFunction<string, string>;
20+
type Props = {
21+
search: Search
22+
}
23+
24+
const MyComponent (props: Props) => {
25+
const [entities, setEntities] = useState<Set>(new Set());
26+
27+
useEffect(() => {
28+
props
29+
.search(
30+
'my search phrase',
31+
'post',
32+
new Set(['page']),
33+
{
34+
per_page: 10,
35+
_fields: ['slug', 'title']
36+
}
37+
)
38+
.then(setEntities);
39+
}, []);
40+
41+
// Do something with the entities
42+
}
43+
44+
// index.tsx
45+
import {searchEntities} from 'wp-entities-search';
46+
47+
root.render(<MyComponent search={searchEntities} />);
48+
```
49+
50+
### Parameters
51+
52+
The function accept four parameters
53+
54+
- `type` - The root type. We have two built-int supported types `post`, `term`.
55+
- `subtype` - The subtype of the entity. For example, if the `type` is `post`, the `subtype` can be `page`, `post`, etc. WordPress exclude automatically the `attachment` subtype.
56+
- `phrase` - The search phrase. This becomes the `s` parameter for the Search Endpoint.
57+
- `queryArguments` - All the supported and extra query arguments. The `EntitiesSearch.QueryArguments` type is an interface you can expand to add more arguments.
58+
59+
### Return
60+
61+
The function return an immutable `Set` of entities.
62+
63+
NOTE: The function does not handle possible request exceptions.
64+
65+
### Aborting Requests
66+
67+
The `searchEntities` will automatically abort the requests with the same parameters if a new request is made before the previous one is completed.
68+

‎docs/components.md

Lines changed: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,201 @@
1+
# Components
2+
3+
The Wp Entities Search provides a set of components you can use to build your search UI.
4+
5+
We have to distinguish between two types of components:
6+
7+
- **Base Components**: These are the basic building blocks of the search UI. They are the smallest components and are
8+
used to build more complex components.
9+
- **Composite Components**: These are more complex components that are built using the base ones.
10+
11+
The _Composite Component_ does not have a direct dependency on the _Base Components_, indeed a composite component
12+
encapsulate the logic
13+
that deal with the state management of the data and pass it down to the base components in form of properties via
14+
the `children` function.
15+
16+
In a nutshell, a _Composite Component_ is configured from the external via props, dialog with the Rest API and pass the
17+
data down to the _Base Components_.
18+
19+
## Base Components
20+
21+
- `PluralSelectControl` - A select control that allows multiple selections.
22+
- `SingleSelectControl` - A select control that allows a single selection.
23+
- `SearchControl` - An input control that allows the user to enter a search query.
24+
- `ToggleControl` - A multi selection control that allows the user to toggle between multiple options.
25+
- `RadioControl` - A single selection control that allows the user to select a single option.
26+
27+
## Composite Components
28+
29+
- `CompositeEntitiesByKind` - A composite component that displays a list of entities by kind. In this context _kind_
30+
is `post` or `term` and _entity_ is the entity type of the content e.g. a `page` or a `category` term.
31+
32+
## Composite Entities by Kind
33+
34+
The `CompositeEntitiesByKind` is a _generic_ component that can be used to display a list of entities by kind. It acts
35+
as a controller that fetches the data from the Rest API using a given function and pass it down to one or more _Base
36+
Components_.
37+
It is up to you how to consume the data given to the children. Note, even if you consume just one part of the given
38+
data,
39+
the component will fetch all the data necessary to render the UI.
40+
41+
This component is intended to fulfill a scenario where the user is looking for some entities belonging to a certain
42+
_kind_,
43+
for instance, selecting the `page` _kind_ will return a list of the available pages and to filter the result further it
44+
is
45+
possible to use a search function in conjunction with a `search` field.
46+
47+
An example of its usage is:
48+
49+
```jsx
50+
import { CompositeEntitiesByKind } from 'wp-entities-search';
51+
52+
export function MyComponent(props) {
53+
return <CompositeEntitiesByKind
54+
searchEntities={
55+
async (phrase, kind, queryArguments) => convertEntitiesToControlOptions(
56+
await searchEntities('post', kind, phrase, queryArguments),
57+
'title',
58+
'id'
59+
)
60+
}
61+
entities={{
62+
value: new Set([13, 24, 55]),
63+
onChange: (value) => {
64+
// Do something with the selected entities
65+
// Notice, here you'll receive the value as a string Set.
66+
}
67+
}}
68+
kind={{
69+
value: new Set(['page']),
70+
options: [
71+
{ label: 'Pages', value: 'page' },
72+
{ label: 'Posts', value: 'post' },
73+
],
74+
onChange={(value) => {
75+
// Do something with the selected kind
76+
}}
77+
}}
78+
>
79+
{({ entities, kind, search }) => (
80+
<>
81+
<ToggleControl
82+
value={kind.value}
83+
options={kind.options}
84+
onChange={kind.onChange}
85+
/>
86+
<SearchControl
87+
onChange={search.onChange}
88+
/>
89+
<ToggleControl
90+
value={entities.value}
91+
onChange={entities.onChange}
92+
/>
93+
</>
94+
)}
95+
</CompositeEntitiesByKind>;
96+
}
97+
```
98+
99+
In the example above we are passing a `searchEntities` function that will be used to fetch the entities from the Rest
100+
API. This function is documented in the [api](./api.md) section.
101+
102+
What's important to know is that the `queryArguments` do not include the `_fields` property because it's not a concern
103+
of the component decide which fields to retrieve, it's up to the consumer to decide which fields to retrieve. Anyhow,
104+
you can still override the given configuration, but you have to be aware this might produce an incorrect result if not
105+
done correctly. The component might pass arguments necessary to guarantee the consistency of the Set of the entities and
106+
the kind.
107+
108+
In the following example we require `title` and `slug` fields to be retrieved from the Rest API.
109+
110+
```typescript
111+
async (phrase, kind, queryArguments) => {
112+
const fields = ['title', 'slug'];
113+
return convertEntitiesToControlOptions(
114+
await searchEntities('post', kind, phrase, {...queryArguments, fields}),
115+
...fields
116+
)
117+
}
118+
```
119+
120+
The `entities` and `kind` properties are the initial configuration, they'll change depending on what happen within the
121+
respective `onChange` functions.
122+
123+
The `children` function will receive the `entities`, `kind` and `search` properties; notice the `search` is a function,
124+
and it's up to the `SearchControl` to maintain the status of the value, the composite does hold the search value
125+
internally, but it does not share it outside.
126+
127+
You're not forced to consume all the properties given to the `children`, you can remove the `SearchControl`
128+
and let the user select only the retrieved entities. Moreover, you can also not have the Kind control at all and just
129+
allow the search for one single kind.
130+
131+
In the example below we only allow to select the entities belonging to the `page` or `landing-page` kind not permitting
132+
the user to switch between them.
133+
134+
```jsx
135+
import { CompositeEntitiesByKind } from 'wp-entities-search';
136+
137+
export function MyComponent(props) {
138+
return <CompositeEntitiesByKind
139+
searchEntities={
140+
async (phrase, kind, queryArguments) => convertEntitiesToControlOptions(
141+
await searchEntities('post', kind, phrase, queryArguments),
142+
'title',
143+
'id'
144+
)
145+
}
146+
entities={{
147+
value: new Set([13, 24, 55]),
148+
onChange: (value) => {
149+
// Do something with the selected entities
150+
}
151+
}}
152+
kind={{
153+
value: new Set(['page', 'landing-page']),
154+
options: Set([]),
155+
onChange={() => {}}
156+
}}
157+
>
158+
{({ entities, _, search }) => (
159+
<>
160+
<SearchControl
161+
onChange={search.onChange}
162+
/>
163+
<ToggleControl
164+
value={entities.value}
165+
onChange={entities.onChange}
166+
/>
167+
</>
168+
)}
169+
</CompositeEntitiesByKind>;
170+
}
171+
```
172+
173+
Obviously depending on what you want to achieve you can use different _Base Components_ or create new ones, as mentioned
174+
above the package comes with a set of _Base Components_ that can be used out of the box.
175+
176+
## About Singular Base Components
177+
178+
The _Composite Component_ always give a collection of Entities and Kind even though you are consuming a Single* _Base Component_.
179+
180+
The Singular Components always get a single value, therefore you have to consider to extract the first element out of the `Set`.
181+
182+
```jsx
183+
import { CompositeEntitiesByKind } from 'wp-entities-search';
184+
185+
export function MyComponent(props) {
186+
return <CompositeEntitiesByKind
187+
/* ... */
188+
>
189+
{({ entities, kind, search }) => (
190+
<>
191+
<RadioControl
192+
value={kind.value.first()}
193+
options={Array.from(kind.options)}
194+
onChange={kind.onChange}
195+
/>
196+
/* ... */
197+
</>
198+
)}
199+
</CompositeEntitiesByKind>;
200+
}
201+
```

‎docs/development.md

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
# Development
2+
3+
The first thing to do is to clone the repository and install the dependencies:
4+
5+
```bash
6+
$ git clone [email protected]:widoz/wp-entities-search.git
7+
$ cd wp-entities-search
8+
$ composer install
9+
$ yarn install
10+
```
11+
12+
After we have installed the dependencies we need to build the assets:
13+
14+
```bash
15+
$ yarn build
16+
```
17+
18+
or alternatively we can run the dev script to compile the assets with source maps:
19+
20+
```bash
21+
$ yarn build:dev
22+
```
23+
24+
## The Environment
25+
26+
The project is making use of `@wordress/env` as a local environment to develop the solution.
27+
28+
To start the environment we need to run the following command:
29+
30+
```bash
31+
$ yarn wp-env start
32+
```
33+
34+
This will install WordPress and will set the current project as a plugin. The package contain a E2E module used by the plugin to help with the development. The module register two blocks; one for the Custom Post Type and one for the Custom Taxonomy.
35+
36+
The WordPress installation is provided without content. To add some we can run the following commands from the root of the project:
37+
38+
```bash
39+
./scripts/create-posts.sh --num 20 --title Post --type post
40+
./scripts/create-posts.sh --num 20 --title Page --type page
41+
./scripts/create-terms.sh --num 20 --name Category --taxonomy category
42+
./scripts/create-terms.sh --num 20 --name Tag --taxonomy post_tag
43+
```
44+
45+
## Basic Concepts
46+
47+
The package implement a Value Object to handle immutability called `Set`. This is the main implementation used by the package to work with external data. Whenever a data is fetched from the WordPress API it will be wrapped in a `Set` object, but also all components and functions deal with this implementation. In a summary, every data entering the package will be wrapped in a `Set` object.
48+
49+
Another commonly used data structure is the `ControlOption` which is not directly consumed but define the type of the `Set`. It should not be consumed directly but through the `Set` api.
50+
51+
## Usage Examples
52+
53+
As mentioned above the package have a E2E module which register two blocks to test the functionality. The first block is a Custom Post Type and the second one is a Custom Taxonomy. The two blocks are using the same component to render the results, you can get some insight about the usage from them.

0 commit comments

Comments
 (0)