# frontity
Apart from being the package that executes the Frontity commands in the terminal, `frontity` also exports functions, objects, etc. to be imported and used by other Frontity packages.
You can import any of these utils using:
```javascript
import { connect, styled, Head, ... } from "frontity";
```
## Table of Contents
* [Overview](#overview)
* [React](#react)
* [CSS in JS](#css-in-js)
* [Code Splitting](#code-splitting)
* [`fetch` and `URL`](#fetch-and-url)
* [API Reference](#api-reference)
* [`connect`](#connect)
* [`useConnect`](#useconnect)
* [`styled`](#styled)
* [`css`](#css)
* [`Global`](#global)
* [`keyframes`](#keyframes)
* [`loadable`](#loadable)
* [`Head`](#head)
* [`useFills`](#usefills)
* [`fetch`](#fetch)
* [`URL`](#url)
* [`error` & `warn`](#error-and-warn)
* [`error`](#error)
* [`warn`](#warn)
* [`decode`](#decode)
* [`Slot`](#slot)
## Overview
### React
Use [**`connect`**](#connect) to inject `state`, `actions` and `libraries` in your React components.
If you are familiar with React hooks, you can use also [**`useConnect`**](#useconnect) to do the same.
Use the [**`Head`**](#head) component whenever you want to add HTML tags inside the `` of any of your site's pages. You can read more in the [Head page](https://docs.frontity.org/learning-frontity/head) of the **Core Concepts** section.
Use the [**`Slot`**](#slot) component whenever you want to add a 'placeholder' to your theme which will be filled with a **`Fill`**. Fills are added to the state in the `state.fills` namespace.
### CSS in JS
[**`styled`**](#styled) creates new React components from HTML tags, or other React components, with styles attached to them. [**`css`**](#css) lets you to add inline styles to an element if you don't want to create a new component. If you want to add styles for the whole app, use [**`Global`**](#global). And [**`keyframes`**](#keyframes) is used to define and use animations in your CSS.
You can read more in the [Styles](https://docs.frontity.org/learning-frontity/styles) page of the **Core Concepts** section of the docs.
### Code Splitting
Use [**`loadable`**](#loadable) in order to separate you code into different bundles that will be dynamically loaded at runtime. This helps you to reduce your page size.
You can read more in this [Code Splitting](https://docs.frontity.org/performance/code-splitting) page of the docs.
### `fetch` and `URL`
Frontity exports [`fetch`](#fetch) and [`URL`](#url) with the same API they have in the browser, but they work the same both in the client and in the server.
## API Reference
### `connect`
It's a function that receives a React component and returns the same component but connected to the Frontity state, actions and libraries. Any instance of that component will receive three new props: `state`, `actions` and `libraries`, allowing the component to read the state, manipulate it through actions or use any code other packages have exposed in libraries.
Also, that instance will re-render automatically whenever any value from the `state` which the component is using is changed.
If you don't want to inject the Frontity state props in your connected components, you can use the `injectProps` option set to `false`. Components will still be reactive to changes in the state but without receiving more props.
For these components to access the state use the [`useConnect`](#useconnect) hook.
#### Syntax
```javascript
ConnectedComponent = connect(Component, options?);
```
#### Arguments
| Name | Object Property | Type | Required | Description | |
| ----------------- | --------------- | --------------- | -------- | --------------------------------------------------------------------------------------------------------------- | - |
| ***`Component`*** | | React component | yes | Link representing a REST API endpoint or custom handler | |
| *`options`* | | object | no | options object | |
| *`options`* | `injectProps` | boolean | - | If `false`, the `state`, `actions` and `libraries` won't be passed as props to the component. Default is `true` | |
#### Return value
* The same component as passed in as the first argument but connected to the Frontity state
#### Example
{% code title="Page.js" %}
```jsx
import React from "react";
import { connect } from "frontity";
import { Loading, List, Post, PageError } from "./components";
const Page = ({ state }) => {
// The next line will trigger a re-render whenever
// the value of "state.router.link" changes.
const data = state.source.get(state.router.link);
return (
);
};
// Connect Page to the Frontity state.
export default connect(Page);
```
{% endcode %}
### `useConnect`
It's a React hook that returns the Frontity state, allowing the component to consume `state`, `actions` and `libraries` in components without passing them as props.
{% hint style="warning" %}
You still need to use [`connect`](#connect) when using `useConnect` properly.
By using `connect`:
* Your components get optimized with *memo*, so they won't re-render whenever a parent component re-renders
* Your components get reactive, so they will re-render when the parts of state they use are changed
{% endhint %}
#### Syntax
```javascript
const { state, actions, libraries } = useConnect();
```
#### Return value
* The Frontity state (`state`, `actions` and `libraries`)
#### Example
{% code title="Page.js" %}
```jsx
import React from "react";
import { connect, useConnect } from "frontity";
import { Loading, List, Post, PageError } from "./components";
const Page = () => {
// Get state using useConnect hook.
const { state } = useConnect();
// The next line will trigger a re-render whenever
// the value of "state.router.link" changes.
const data = state.source.get(state.router.link);
return (
);
};
// Connect Page to the Frontity state.
export default connect(Page);
```
{% endcode %}
#### Use Case of `{ injectProps: false }` with `connect`
Most of the times you'll use `useConnect` in this way:
```jsx
const Input = ({ name, type }) => {
const { state } = useConnect();
// Do something with `state`.
return ;
};
export default connect(Input);
```
But if you want to pass down props to a HTML tag, like in this case:
```jsx
const Input = ({ name, type, ...props }) => {
const { state } = useConnect();
// Do something with `state`.
return ;
};
export default connect(Input);
```
You'll end up passing `actions` and `libraries` to `` as well, because they are injected by `connect`.
To avoid this you can:
* Add `{ injectProps: false }` to `connect`
* Use `const { state, actions, libraries } = useConnect();`
```jsx
const Input = (props) => {
const { state } = useConnect();
// Do something with `state` (or `actions` and `libraries`).
return ;
};
// Avoid injecting `state`, `actions` and `libraries` so they are not present in `...props`.
export default connect(Input, { injectProps: false });
```
### `styled`
`styled` is a function that receives an HTML tag or a React component as the argument and returns a function that can be used as a [tagged template literal](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#Tagged_templates). Inside, you write the CSS code for your component.
The `styled` tag function returns a styled component with the CSS you wrote.
Also, `styled` has built-in tag functions for every HTML tag so in those cases it is not necessary to call `styled` directly.
#### Syntax
```jsx
// You can use an HTML tag like this.
const StyledDiv = styled.div`
font-size: 24px;
`;
// Or use it like a function and pass a React component.
const StyledComponent = styled(Component)`
background: aliceblue;
`;
```
#### Arguments
* A template literal containing CSS code
#### Return value
* A React component with the styles defined
#### Example
```jsx
import { styled } from "frontity";
import { Page } from "./page";
const Main = () => (
);
const Container = styled.div`
display: flex;
justify-content: center;
`;
const StyledPage = styled(Page)`
background: ${(props) => props.background};
`;
```
### `css`
It's a tagged template literal to add an inline style to React Components.
The usage is quite similar to **`styled`** except that **`css`** doesn't return a React Component but a special object that can be passed to a component through the **`css`** prop.
#### Syntax
```javascript
const styleObject = css`
background: pink;
`;
```
#### Arguments
* A template literal containing CSS code
#### Return value
* A style object to be passed to a **`css`** prop or to the **``**'s **`styles`** prop
#### Example
```jsx
import { css } from "frontity";
const Component = () => (
Styling my theme
);
```
### `Global`
It's a React component that creates global styles for the whole Frontity site.
{% hint style="warning" %}
**Using `` for other than HTML tags is not recommended** because Frontity is not able to optimize it. That means you can use it for tags like `html`, `body` , `a`, `img`, and so on... But **avoid it for classes**. Use either the CSS prop or styled-components instead.
{% endhint %}
#### Syntax
```jsx
```
#### Props
* **`styles`**: an style object created with [`css`](#css)
#### Example
```jsx
import { Global, css } from "frontity";
const Page = () => (
<>
);
```
### `keyframes`
It's a function used to define and use animations in your CSS.
#### Syntax
```jsx
const animation = keyframes`
from { ... } to { ... };
`;
```
#### Arguments
* A template literal containing [CSS @keyframes](https://developer.mozilla.org/en-US/docs/Web/CSS/@keyframes) code
#### Return value
* An animation object to be used inside a template literal passed to [`styled`](#styled) or [`css`](#css)
#### Example
```jsx
import { styled, keyframes } from "frontity";
// Create the keyframes.
const rotate = keyframes`
from {
transform: rotate(0deg);
}
to {
transform: rotate(360deg);
}
`;
// Add the animation to the styled component.
const Button = styled.button`
background-color: hotpink;
animation: ${rotate} 2s linear infinite;
`;
const Component = () => ;
```
### `loadable`
It's a function that loads a component asynchronously generating a different bundle for it. Frontity has integrated and configured [Loadable Components](https://www.smooth-code.com/open-source/loadable-components/docs/code-splitting/), in case you want to check its docs.
You can also take a look at the [Code Splitting](https://docs.frontity.org/performance/code-splitting) page of the docs.
#### Syntax
```jsx
const HeavyComponent = loadable(importFunction, options);
```
#### Arguments
| Name | Object Property | Type | Required | Description |
| -------------------- | --------------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ***importFunction*** | | function | yes | a function that executes a [dynamic import](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import#Dynamic_Import) and returns a `Promise` that will contain the imported module |
| *`options`* | | object | no | options object |
| *`options`* | `fallback` | React component | - | component displayed until the `Promise` resolves |
| *`options`* | `ssr` | boolaan | - | if `false`, it will not be processed server-side (default to `true`) |
#### Return value
* A React component
#### Example
```jsx
import { loadable } from "frontity";
import Content from "./components/content";
// Thanks to loadable we prevent comments from loading until it's needed.
const HeavyComments = loadable(() => import("./components/comments"));
const Post = ({ state }) => (
<>
{state.comments.areOpened && }
);
export default connect(Post);
```
### `Head`
#### Syntax
```jsx
{children}
```
It's a React component that injects their children in the HTML `` tag. It allows you to change the title while navigating, add meta tags, scripts, etc.
As we use `react-helmet` under the hood, you may check its [reference guide](https://github.com/nfl/react-helmet#reference-guide).
#### Props
* **`children`**: the HTML tags you want to appear inside ``
#### Example
```jsx
import { Head } from "frontity";
const Theme = () => (
My awesome blog
);
```
### `useFills`
A React hook to ease the creation of `Slot` components.
#### Syntax
```javascript
const fills = useFills("Slot Name");
```
#### Arguments
| Name | Type | Required | Description |
| -------------- | ------ | -------- | --------------------------------------------- |
| ***slotName*** | string | yes | A string that refers to the name of the Slot. |
#### Return value
`Fill[]`
An array of configuration objects for the fills that want to fill the slot passed by the `slotName` parameter. The values in those objects will come from the fills defined by the user of the slot in `state.fills`.
Mind that a user might define more than one fill for a particular slot. Because of this, we always return a list of slots sorted in **ascending order** by their `priority`.
Each configuration object has this structure:
| Name | Type | Description |
| -------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`Fill`** | ReactComponent | The component that should be rendered for this fill. |
| **`slot`** | string | The name of the slot. Mind that a user can define multiple fills that fill the same slot, so there might exist more than one object with the same `slot` property. Defined in `state.fills.namespace.fillName.slot`. |
| **`props`** | object | The props that should be passed down to the component. Defined in `state.fills.namespace.fillName.props`. |
| **`library`** | string | The name of the library that is using the fill. defined in `state.fills.namespace.fillName.library`. |
| **`priority`** | number | The priority of the fill. By default, the fills are sorted in ascending order according to this value. Defined in `state.fills.namespace.fillName.priority`. |
| **`key`** | string | This is a unique value that identifies the particular fill. It's a combination of the `namespace` and the `fillName`. |
#### Example
Import the hook in your React component and use it to create a component:
```jsx
import { useFills } from "frontity";
const Comp = () => {
const fills = useFills("slot 1");
return (
<>
{fills.map(({ Fill, props, key }) => (
))}
);
};
export default connect(Comp);
```
{% hint style="info" %}
You need to wrap the component that uses the `useFills` hook with `connect()` in order for that component to work.
{% endhint %}
#### Debug mode
If you want to see all the slots added to a theme/package without having to add fills for all of them, you can turn the debug mode on:
```javascript
state.frontity.debug = true;
```
If you want to do this on the console, remember that you need to access the `state` using `frontity.state`, like this:
### `fetch`
It's a function with the [WHATWG API](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch) for fetching a resource from the network.
This function is safe to use both server and client-side, but you have to import it first.
#### Syntax
```javascript
const fetchResponsePromise = fetch(resource, init);
```
#### Arguments
| Name | Type | Required | Description |
| -------------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ***resource*** | string | yes | a string containing the direct URL of the resource you want to fetch |
| *`init`* | object | no | an options object containing any custom settings that you want to apply to the request (go to [this link](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch#Parameters) for the complete list of available settings) |
#### Return value
* A `Promise` that resolves to a [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) object
#### Example
```javascript
import { fetch } from "frontity";
const getFromSomeAPI = async (resource) => {
const response = await fetch("https://site.com/api/v1" + resource);
const body = await response.json();
return body;
};
```
### `URL`
#### Syntax
```javascript
const url = new URL(url, base);
```
It's a constructor with the [WHATWG API](https://developer.mozilla.org/en-US/docs/Web/API/URL/URL) to create [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL) objects.
This constructor is safe to use both server and client side, but you have to import it first.
#### Arguments
| Name | Type | Required | Description |
| --------- | ------ | ---------------------------------------------- | ----------------------------------------------- |
| ***url*** | string | yes | Absolute or relative URL. |
| *`base`* | string | If `url` is a relative URL, `base` is required | Base URL to use in case `url` is a relative URL |
#### Return value
* A [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL)object
#### Example
```jsx
import { URL } from "frontity";
const getApiPathname = ({ state }) => {
const { pathname } = new URL(state.source.api);
return pathname;
};
```
### `error` & `warn`
The `frontity` package exports an `error` and `warn` helpers to be used by package developers when they need to either throw an error or log a warn in the console.
#### `error`
This `error` method throws an error. In development, it adds a message that encourage users to visit the Frontity community if they need help.
[**Example of `error` usage**](https://github.com/frontity/frontity/blob/27eb4e0847b002ff26845f5e3f231dc43a637f88/packages/wp-source/src/actions.ts#L203)
```
try {
new URL(api);
} catch (e) {
error("Add the URL of your WordPress REST API in state.source.api.");
}
```
**Syntax**
```jsx
error(((message: string), (options: ErrorOptions = {})));
```
**Arguments**
| Name | Type | Required | Description |
| --------------- | ------- | -------- | ------------------------------------------------------------------------------------------------- |
| ***message*** | string | yes | The message that describes the error. |
| *options* | object | no | Options object. |
| *options.throw* | boolean | no | Indicate if the function should throw or just log the error in the console using `console.error`. |
#### `warn`
Logs a warning in the console, adding a message that indicates users to visit the Frontity community if they need help. It's intended to be used by Frontity packages.
[**Example of `warn` usage**](https://github.com/frontity/frontity/blob/27eb4e0847b002ff26845f5e3f231dc43a637f88/packages/components/switch.tsx#L29)
```
...
if (hasInvalidComponent) {
warn("Children of component should be a type of ReactNode");
}
```
**Syntax**
```jsx
warn((message: string));
```
**Arguments**
| Name | Type | Required | Description |
| ------------- | ------ | -------- | ---------------------------------------- |
| ***message*** | string | yes | The message that describes the warning.. |
### `decode`
An entity decoder that decodes HTML numeric entities and [XML named entities](https://html.spec.whatwg.org/multipage/named-characters.html#named-character-references). It works both in the server and the client and it's optimized to be both lightweight and performant.
#### Syntax
```jsx
const decodedText = decode(text);
```
#### Arguments
| Name | Type | Required | Description |
| ---------- | ------ | -------- | ------------------- |
| ***text*** | string | yes | HTML to be escaped. |
#### Return value
* `string`
#### Example
```jsx
import { decode } from "frontity";
const decodedText = decode("milk & cookies");
console.log(decodedText); // "milk and cookies"
```
### `Slot`
The `` component enables the use of a powerful pattern called Slot and Fill. This allows for any React component to be inserted into, or hooked onto, different places within the app, thereby improving extensibility.
This component allows a theme developer to insert named `` components in various places in a theme. Other package developers are then able to add *'fill'* components which will be hooked onto the named slots.
#### Rationale
When developing a site the developer is often required to make certain customisations to the structure and/or appearance of the site. This can be difficult to do and necessitates modifying the core code of the theme.
Theme developers are able to facilitate such customisations by adding `` components at various places in the theme, e.g. above the header, below the header, before the content, etc...
These 'slots' can then be filled with custom components that have been added by the site developer and which are then 'hooked' onto a particular 'slot' to insert the content in that place on the page.
An example might be as follows - the site developer wants to place a third party ad above the content of each page. The theme developer has thoughtfully provided a slot in that position in the theme:
```jsx
//...
const Content = () => {
//...
//...
//...
}
```
The site developer is now able to 'hook' a component that returns an ad onto that slot, so that the ad gets rendered in that position on the page. This component is referred to as a *'fill'*.
#### Syntax
```jsx
```
or
```jsx
{children}
```
#### Props
All the following props can be passed to the `` component.
| Name | Type | Default | Required | Description |
| ---------------- | ---------- | ------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | string | `undefined` | yes | The name of the Slot. The user of this Slot will have to specify this name in order to insert a Fill component. |
| `children` | ReactNode | `undefined` | no | The component that will be used as a fallback in case that no fill is specified for a particular Slot. You can use any type of data that is a valid React element. |
| `data` | ReturnType | `state.source.get(state.router.link)` | no | Any data that you might want to pass to the Fill. Normally used for passing route data fetched in the parent component. If you don't pass any value, the `` component will set the value of this prop to `state.source.get(state.router.link)` for you automatically. |
| `any other prop` | any | undefined | no | Any other custom prop. The theme can specify other props and they will be passed down to the Fill. |
#### Examples
The simplest example of a Slot would be:
```jsx
import { Slot } from "frontity";
const Theme = ({ state }) => (
<>
{/* ... */}
);
```
Slots can also pass data to the `Fill` components that will be inserted in place of those slots:
```jsx
import { Slot } from "frontity";
const Carousel = ({ state }) => {
// Get latest posts.
const homeData = state.source.get("/");
return homeData.items.map((post, index) => {
const data = state.source.get(post.link);
return (
<>
);
});
};
```
Slots can also pass arbitrary props to the `Fill` components that will be inserted in place of those slots. In this example we're using 'index' to pass the value of `index` to the Fills:
```jsx
import { Slot } from "frontity";
const Carousel = ({ state }) => {
// Get latest posts.
const homeData = state.source.get("/");
return homeData.items.map((post, index) => {
const data = state.source.get(post.link);
return (
<>
);
});
};
```
The Slot component supports optional children that are rendered if no fills are present. You can use any type of data that is valid as a react element:
```jsx
const Post = () => (
<>
{/* ... */}
{/* ... */}
);
```
#### Fills
Fills are added to the `state`, to a common namespace called `fills`. Each fill consists of a configuration object that should be given a unique key and assigned to a namespace. To learn more about namespaces see [this section](https://docs.frontity.org/learning-frontity/namespaces) of the docs.
More than one Fill can be hooked onto any single Slot, and these can be ordered according to a `priority` attribute assigned to the Fill.
```jsx
// my-frontity-app/packages/my-theme/src/index.js
const state = {
fills: {
namespace: {
nameOfTheFill: {
slot: "Name of the slot they want to fill", // This has to match the `name` prop passed to
library: "libNamespace.ComponentName",
priority: 5,
props: {
// Object with props that will be passed to the component.
},
},
},
},
};
```
Fills configuration objects structure:
| Name | Description | Required |
| ------------ | -------------------------------------------------------------------------------------------- | -------- |
| `object key` | Name of your fill, must be unique. | yes |
| `slot` | Name of the slot they want to fill. | yes |
| `library` | Name of the component they want to use. This is obtained from `libraries.fills` (see below). | yes |
| `priority` | Priority of the fill. Default is 10. (lower value means higher priority) | no |
| `props` | Object with props that will be passed to the component. | no |
Fills configuration objects can have a false value. This is useful if a package creates a fill by default and a user (or another package) wants to turn it off.
```jsx
// my-frontity-app/packages/my-theme/src/index.js
const state = {
fills: {
namespace: {
nameOfTheFill: false,
},
},
};
```
The actual components that will be hooked onto a `` should be exposed in `libraries.fills` by Frontity packages. They can be defined anywhere you like, as long as you can import them and pass to `libraries.fills`. For example:
```jsx
// my-frontity-app/packages/my-theme/src/fills.js
export const FillComponent = ({
// If the Slot creator has passed a `data` prop to the Slot,
// you can access it here. Otherwise, this prop will be automatically
// populated with the value of `state.source.get(state.router.link)`
data,
// Any other props passed by the creator of the Slot will be available as well!
...props
}) => (
This is the fill content
)
}
```
```jsx
// my-frontity-app/packages/my-theme/src/index.js
import { MyFillComponent } from "./fills"; // This is the component defined below
export default {
state: {
//...
},
actions: {
//...
},
libraries: {
fills: {
libNamespace: {
ComponentName: MyFillComponent,
},
},
},
};
```
Note that `libNamespace.ComponentName` here matches the value of `state.fills.namespace.nameOfTheFill.library` above. `FillComponent` here is the actual component which is defined elsewhere and may be imported. The return value of this component, i.e. `FillComponent`, is the content that will be inserted into HTML at the position of the `` that it is attached to.