Mars theme is our starter theme and is installed by default on frontity create
. Here we'll explain how @frontity/mars-theme
works.
If you yet don't understand the structure of a Frontity project, please read our guide Understanding a Frontity project.
Have a look at this Frontity Talk where we talk about the mars-theme
:
Utilities are those libraries that are part of the Frontity core and need to be exposed to us in order to successfully develop a theme that integrates completely with Frontity. All those utilities are exposed in thefrontity
package.
For example, our state manager @frontity/connect
exposes a utility called connect
to wrap our React components so we can access the Frontity store from them. To avoid us the need to remember lots of packages and dependencies, we can import connect
and other libraries like this:
import { connect, styled } from "frontity";āconst HelloWorld = () => <Container>Hello World!</Container>āexport default connect(HelloWorld);āconst Container = styled.div`background: blue;color: white;`;
As you can see in the example above, we are accessing also styled
from frontity
. In this case frontity
is just exposing the API of @emotion/styled
, and it does this with other libraries like react-helmet
, so you get everything that you'd usually need in just one line.
The extension itself can be an object or a function that returns that object. You can see the object structure explained in the following code, along with what we are exporting in mars-theme
:
import Theme from "./components/theme";āconst marsTheme = {// The name of the extension.name: "@frontity/mars-theme",// The React components that will be rendered.roots: {theme: Theme,},// The default state that the extension needs to create in order to work.state: {theme: {menu: [],featured: {showOnList: false,showOnPost: false}}},// The actions that the extension needs to create in order to work.// In our case, `mars-theme` doesn't export any actions.actions: {},// The libraries that the extension needs to create in order to work.// In our case, `mars-theme` doesn't export any actions.libraries: {}};āexport default marsTheme
In each part of the exported object, what the extension defines needs to be inside its namespace
. In our case, all the things we are defining are inside the theme
namespace, but if our theme implemented, for example, a comments solution, that state, actions, etc., should be defined inside the comments
namespace. So, in the case of roots
, it would be something like:
import Theme from './components/theme';import Comments from './components/comments';āconst extension = {...roots: {theme: Theme,comments: Comments,},...};
There are some steps that we need to go through in order to have our theme working:
First of all, we want our server-side rendering to be equal to our client-side rendering to not harm the UX and SEO. In order to do this, we are going to use an action called beforeSSR
. This action will be run by @frontity/core
before the server-side render is generated by React and it's the best place to request the data we need from our WP:
We are doing this in our src/index.js
file:
const marsTheme = {name: "@frontity/mars-theme",roots: { ... },state: { ... },actions: {theme: {beforeSSR: async ({ state, actions }) => {// We fetch the initial link.await actions.source.fetch(state.router.link);// NOTE: This is not needed if autoFetch is activated in your router.}}}};
Now that we have the data we need to render our app, we can start writing some React. All the components described below can be found inside src/components
.
Our main React component will be Theme
, where we are deciding what kind of view to render, and in order for that component to access the store, we need to wrap it with the connect
function. Once it's wrapped, we can access state
and actions
directly from the props. In this case, we are using state.source.get()
to retrieve info about what kind of content should be rendered in the current path. If it happens to be an archive, we will render the <List />
component, if a post type, the <Post />
and if for some reason wp-source
couldn't retrieve the data from our WP, we will render a 404 page.
Here you have the code of Theme
with some comments:
theme.jsimport React from "react";import {// Modules from `@emotion/core` and `@emotion/styled`.Global,css,styled,// Module from `@frontity/connect`.connect,// Alias for `Helmet` from `react-helmet`.Head} from "frontity";import Header from "./header";import List from "./list";import Post from "./post";import Page404 from "./page404.js";āconst Theme = ({ state }) => (<>// Adding some elements to <head>// with `react-helmet`.<Head><title>{state.frontity.title}</title><html lang="en" /></Head>// Adding global styles to our app.<Global styles={globalStyles} />// Just rendering the Header component.<HeadContainer><Header /></HeadContainer><Body>// Here is where we use our `state.source.get()` to decide// what component we'll render.{state.source.get(state.router.link).isArchive && <List />}{state.source.get(state.router.link).isPostType && <Post />}{state.source.get(state.router.link).is404 && <Page404 />}</Body></>);āexport default connect(Theme);
Between the Post
component and the List
component there are a bunch of different things going on here. I'll start with List
.
It is exported from list/index.js
. There, we are using loadable
from frontity
(which is actually an alias for the default
export of @loadable/components
) to split the code of our List
component, so it won't be loaded if a user access directly to a Post
view, and instead the code will be requested when the user clicks on a list view. This is helpful to reduce the loading times and times to interactive of our site. The less code we have, the less time the browser spends evaluating it.
list/index.jsimport { loadable } from "frontity";ā// Codesplit the list component so it's not included if the users// load a post directly.export default loadable(() => import("./list"));
Now, our List
component is the responsible to render a list of posts, and for that it needs to know what posts to render. We are using state.source.get(link)
and its items
field.
list/list.jsconst List = ({ state }) => {// Get the data of the current list.const data = state.source.get(state.router.link);āreturn (<Container>{/* If the list is a taxonomy, we render a title. */}{data.isTaxonomy && (<Header>{data.taxonomy}: {state.source[data.taxonomy][data.id].name}</Header>)}ā{/* If the list is an author, we render a title. */}{data.isAuthor && (<Header>Author: {state.source.author[data.id].name}</Header>)}ā{/* Iterate over the items of the list. */}{data.items.map(({ type, id }) => {const item = state.source[type][id];// Render one Item component for each one.return <Item key={item.id} item={item} />;})}<Pagination /></Container>);};
The last detail we are going to explain is how we are doing pagination on List
.
We are getting the total of pages for that list from state.source.get(link)
and we are checking if we are either in the first one, the last one, or in the middle. Using the React hook useEffect
we are prefetching the next page when the component mounts, so in the case the user goes there, he doesn't have to wait for the response from the WP REST API.
Depending on the page we are at the moment, we render different links to travel through the list. For that we are using our own Link
component, which accepts the same parameters as actions.source.fetch()
or actions.router.set()
.
list/pagination.jsconst Pagination = ({ state, actions, libraries }) => {const { totalPages } = state.source.get(state.router.link);const { path, page, query } = libraries.source.parse(state.router.link);āconst isThereNextPage = page < totalPages;const isTherePreviousPage = page > 1;āconst nextPageLink = libraries.source.stringify({path,page: page + 1,query});āconst prevPageLink = libraries.source.stringify({path,page: page - 1,query});āuseEffect(() => {// Fetch the next page if it hasn't been fetched yet.if (isThereNextPage) actions.source.fetch(nextPageLink);}, []);āreturn (<div>{isThereNextPage && (<Link link={nextPageLink}><em>ā Older posts</em></Link>)}{isTherePreviousPage && isThereNextPage && " - "}{isTherePreviousPage && (<Link link={prevPageLink}><em>Newer posts ā</em></Link>)}</div>);};
There is something new here, that we haven't done on List
. We are doing a preload of the List
component (as it is a dynamic component and we don't have that code yet). Once we have our site rendered and working, we preload the code for List
, so the user won't need to wait for it later if she decides to visit a list of posts.
post.jsimport List from './list';āconst Post = ({ state, actions }) => {const data = state.source.get(state.router.link);const post = state.source[data.type][data.id];// Get the author.const author = state.source.author[post.author];const date = new Date(post.date);āuseEffect(() => {actions.source.fetch("/");// Here is where we are preloading the List component.// This will run only on mount.List.preload();}, []);āreturn data.isReady ? (<Container>{ ... }</Container>) : null;};
The Link
component will use @frontity/tiny-router
to handle the navigation within the app. It will render the children passed to it inside an <a>
. It will populate the href
attribute so the link still works even if JavaScript is not available, which will provoke a call to the server and get the next page server-side rendered.
However, if JS is available, we are overriding the anchor behaviour with an onClick
function. Inside that function, we are fetching the data needed to render our destination with source.fetch(path)
and we are setting the URL to the new route with router.set(path)
.
Note that we are mapping also a prop called className
to the <a>
class. This is done in case we want to style Link
, e.g.: const StyledLink = styled(Link)``;
.
link.jsconst Link = ({ actions, link, className, children }) => {const onClick = event => {event.preventDefault();// Set the router to the new url.actions.router.set(link);// Move scroll to the top.window.scrollTo(0, 0);};āreturn (<a href={link} onClick={onClick} className={className}>{children}</a>);};
The last thing that might need to be explained is how we define state
for our extension in order to use it within React and be able to set it with a frontity.settings
file in a Frontity project.
In mars-theme
we are defining the following state
:
// src/html/index.jsāconst marsTheme = {...,state: {theme: {// This field will be used in our Nav bar.// Here we are defining the default value.menu: [],featured: {showOnList: false,showOnPost: false}}}};
And we are using it as shown below:
nav.jsconst Nav = ({ state }) => (<Container>{state.theme.menu.map(([name, link]) => (<Item key={name} isSelected={state.router.link === link}><Link link={link}>{name}</Link></Item>))}</Container>);
And when we create a new Frontity project where our theme is installed, that state can be changed in frontity.settings.js
:
const settings = {...,packages: [...,{name: "@frontity/mars-theme",state: {theme: {// Here is where the owner of the project can// set the values of the `mars-theme` state....,menu: [["Home", "/"],["Nature", "/category/nature/"],["Travel", "/category/travel/"],["Japan", "/tag/japan/"],["About Us", "/about-us/"]],}}}]};
Still have questions? Ask the community! We are here to help š