Forem: Nominom

Building a personal blog with Craft CMS, React and Element API / Part 3 - React front-end

Nominom — Thu, 14 May 2020 12:09:09 +0000

This is part 3 of my tutorial on building a blog site with React front-end and Craft CMS. If you missed the first two, you can find them here:

part1
part2

All the code for this tutorial is available on github.

In this part we're going to create a front-end for our blog with React!

Step 8 - Fetching JSON in react

Let's open up our App.js file. Currently, it should look something like this:

import React from 'react'

const App = () => {
    return(
        <div>
            Hello World!
        </div>
    )
}

export default App

To render what's in our Craft blog, we need a way to access the element api json endpoints. For this reason, we need to import axios, and change our React import to include useState and useEffect.

import React, { useState, useEffect } from 'react'
import axios from 'axios'

...

Axios is a "Promise based HTTP client for the browser and node.js", that will execute the api calls to our backend.

Let's make our first api call to /site.json:

import React, { useState, useEffect } from 'react'
import axios from 'axios'

const App = () => {
    const [site,setSite] = useState(null)

    useEffect(() => {
        axios.get("/site.json").then((response) => {
            console.log(response.data)
            setSite(response.data);
        }).catch((error) => {
            console.error(error.message)
        })
    }, [])

    return (
        <div>
            Hello World!
        </div>
    )
}

export default App

If you're running the local php development server, you can open up another terminal and run

$ npm run dev

... to run webpack in watch mode, where it will automatically watch for changes and rebuild the bundle when necessary. If you're running Craft on a remote server, you can set up WinSCP or similar to sync the /web/res/ folder automatically.

If you now access http://localhost:3001/ and open up your development console, you should see that the json data gets printed to the console.

Let's also fetch the page's json data, by appending .json to the current url. We should also append any query parameters in the url to make Craft live preview work with our front-end.

import React, { useState, useEffect } from 'react'
import axios from 'axios'

const App = () => {
    const [page, setPage] = useState(null)
    const [site,setSite] = useState(null)

    const path = window.location.pathname
    const query = window.location.search

    useEffect(() => {
        axios.get("/site.json").then((response) => {
            console.log(response.data)
            setSite(response.data);
        }).catch((error) => {
            console.error(error.message)
        })
    }, [])

    useEffect(() => {
        axios.get(path + '.json' + query).then((response) => {
            console.log(response.data)
            setPage(response.data);
        }).catch((error) => {
            console.error(error.message)
        })
    }, [path, query])

    return (
        <div>
            Hello World!
        </div>
    )
}

export default App

Refresh the page, and now two console logs should pop up. One with our site data and one with our page data.

Step 9 - Page layout

Let's add tailwind css include to our templates/index.twig file:

<!DOCTYPE html>
<html lang="{{ craft.app.language }}">
    <head>
        ...
        <link href="https://unpkg.com/tailwindcss@^1.0/dist/tailwind.min.css" rel="stylesheet">
    </head>
    ...
</html>

Tailwind is a low-level css framework that will help us build a fairly good looking prototype without writing any actual css. You could also use another framework like bootstrap or write your own css classes. All of the styles here are just to make our example look a bit nicer.

I will say though, I'm not a designer and don't pretend to be. So the layout is still a little bit rough. You have been warned.

Let's also make a new folder under the templates/ folder called blog, and copy the templates/index.twig to templates/blog/index.twig. This will make it so when we request for /blog url, Craft will show our React page instead of an 404 error.

To define our page layout, let's make a Layout.js file in our src/ folder:

import React from 'react'
import Nav from './components/Nav'

const Layout = ({ children, site }) => {
    return (
        <div className="flex min-h-screen">
            <div className="flex flex-col flex-grow mx-auto container px-4 md:px-8 xl:px-20">
                <header className="flex flex-grow-0 md:p-4">
                    <Nav pages={site?.pages || []} logo={site?.logo} />
                </header>
                <main className="flex flex-grow md:p-4">
                    {children}
                </main>
                <footer className="flex flex-grow-0 justify-center p-4 text-sm">
                    {site?.footerText}
                </footer>
            </div>
        </div>
    )
}

export default Layout

Let's also make a simple navigation bar to show our site pages. Make a new folder in src/ called components, and create a new file called Nav.js. Paste in the following contents:

import React, { useState } from 'react'

const Nav = ({ pages, logo }) => {
    const [open, setOpen] = useState(false)

    const switchState = () => {
        setOpen(!open)
    }

    return (
        <div
            className="flex flex-col w-full mx-auto md:items-center 
            md:justify-between md:flex-row">
            <div className="py-2 flex flex-row items-center justify-between">
                {logo ?
                    <a href={window.location.host}>
                        <img className="h-12" src={logo} alt="logo" />
                    </a>
                    : <div className="h-12"></div>}
                <button className="md:hidden rounded-lg outline-none shadow-none p-2"
                    onClick={switchState}>
                    <svg className="fill-current h-5 w-5"
                        viewBox="0 0 20 20" xmlns="http://www.w3.org/2000/svg">
                        <title>Menu</title>
                        <path d="M0 3h20v2H0V3zm0 6h20v2H0V9zm0 6h20v2H0v-2z" />
                    </svg>
                </button>
            </div>
            <nav className={`flex-col flex-grow pb-4 md:pb-0 ${open ? 'flex' : 'hidden'} 
            md:flex md:flex-row`}>
                {pages.map((page, i) => {
                    return (
                        <a key={i} href={page.url}
                            className="px-2 mt-4 text-2xl md:my-auto md:mx-2">
                            {page.title}
                        </a>
                    )
                })}
            </nav>
        </div>
    )
}

export default Nav

This might look a bit complicated, but it's mostly just a lot of tailwind classes and a button to make it responsive.

Without any styling or responsiveness, it would simply look like this:

import React from 'react'

const Nav = ({ pages, logo }) => {

    return (
        <div>
            <div>
                {logo ?
                    <a href={window.location.host}>
                        <img src={logo} alt="logo" />
                    </a>
                    : <div></div>}

            </div>
            <nav>
                {pages.map((page, i) => {
                    return (
                        <a key={i} href={page.url}>
                            {page.title}
                        </a>
                    )
                })}
            </nav>
        </div>
    )
}

export default Nav

Let's import our layout in App.js to see it in action:

import ...
import Layout from './Layout'

const App = () => {
    ...
    return (
        <Layout site={site}>
            Hello World!
        </Layout>
    )   
}

export default App

You should now see a navigation bar with your logo and our Home and Blog pages, and a footer with your defined footer text.

Step 10 - Rendering page content

Next, we'll create a React component that renders our page content we have designed in Craft.

To start, let's create a Page component that decides what type of content to render on the current page. Here's where the meta objects we have in our json endpoint come in use: for each endpoint we are sending a type variable in the meta object. We can use that type to determine what we need to render.

Create a file called Page.js in the src/ folder with the following contents:

import React from 'react'

const Page = ({ page }) => {

    if (page) {

        switch (page?.meta?.type) {
            case 'bloglist':
                return <div>Blog List</div>
            case 'blogpost':
                return <div>Blog Post</div>
            case 'page':
                return <div>Page</div>
            default:
                console.error('Unknown content type.')
        }
    }
    return (
        <>
        </>
    )
}

export default Page

Let's also add the new component to our App.js:

import ...
import Page from './Page'

const App = () => {
    ...
    return (
        <Layout site={site}>
            <Page page={page} />
        </Layout>
    )

}

export default App

If we now take a look at our Home and Blog pages, the page should show either 'page' or 'Blog List' depending on what page we are on.

Let's create a component that can render our Post Content matrix blocks. Create a file called PostContent.js in src/components/ folder:

import React from 'react'

const PostContent = ({ content }) => {
    return (
        <div className="w-full">
            {content.map((block, i) => {
                switch (block.type) {
                    case "text":
                        return <div key={i}
                            dangerouslySetInnerHTML={{ __html: block.text }}>
                        </div>
                        break;
                    case "image":

                        return <figure key={i} className="w-full my-8">
                            <img className="w-full h-auto" src={block.image}>
                            </img>
                        </figure>

                        break;
                    default:
                        console.error("Content type not recognized: ", block.type)
                        break;
                }
            })}
        </div>
    )
}

export default PostContent

And add it to our Page.js:

import React from 'react'
import PostContent from './components/PostContent'

const Page = ({ page }) => {

    if (page) {

        switch (page?.meta?.type) {
            case 'bloglist':
                return <div>Blog List</div>
            case 'blogpost':
                return <div>Blog Post</div>
            case 'page':
                return <PostContent content={page.content || []}/>
            default:
                console.error('Unknown content type.')
        }
    }
    return (
        <>
        </>
    )
}

export default Page

Now, if we navigate to the Home page, the content should appear. What you might notice at least if you're using tailwind, is that all of our headings don't look like headings.

Because we have no easy way to set classes to the html we get from the back-end, we'll have to use css child selectors to style our headers and such. We are going to use styled components to add some actual css, but you can also do this just by adding a css file in to your project.

Let's import styled components to our project.

$ npm install --save styled-components

Then, we can make a styled component inside our PostContent.js that applies styles to it's children.

import React from 'react'
import styled from 'styled-components'

const PostContainer = styled.div`

    font-size: 1.1rem;

    h1 {
        font-style: bold;
        font-size: 2rem;
    }
    h2 {
        font-style: bold;
        font-size: 1.6rem;
    }
    h3 {
        font-size: 1.3rem;
    }
    h4 {    
        font-style: italic;
        font-size: 1.2rem;
    }
    h5 {
        color: #222222;
        font-size: 1.1rem;
    }
    h6 {
        color: #222222;
        font-size: 1rem;
    }
    p {
        margin-top: 1rem;
        margin-bottom: 1rem;
    }

    a {
        font-style: bold italic;
        border-bottom: 2px solid #05dd05;
        white-space: nowrap;
        &:hover {
            color: #05dd05;
        }
    }

    pre {
        margin-top: 1rem;
        background-color: #222222;
        padding: 0.5rem;
        padding-left: 1rem;
        border-radius: 0.5rem;
        color: #eeeeee;
    }

    blockquote {
        font-style: italic;
        border-left : 0.3rem solid #bbbbbb;
        color: #666666;
        padding-top: 0.3rem;
        padding-bottom: 0.3rem;
        padding-left: 1.5rem;
    }
`


const PostContent = ({ content }) => {
    return (
        <PostContainer className="w-full">
            {content.map((block, i) => {
                ...
            })}
        </PostContainer>
    )
}

export default PostContent

Now our page should look a little nicer.

Another thing that's good to have in a blog website is a listing of all the blogs. So let's make one!

Create a file called BlogList.js in src/components/, and paste in the following content:

import React from 'react'

const BlogListItem = ({ blog }) => {
    return (
        <article className="flex flex-row p-2">
            <div className="flex flex-col flex-grow">
                <a href={blog.url} className="flex flex-grow-0 bold text-lg"><h2>{blog.title}</h2></a>
                <p className="flex flex-grow text-md">{blog.excerpt}</p>
            </div>
            <a href={blog.url} className="flex-none h-20 w-20 ml-4">
                <img className="object-cover h-full" src={blog.featureImage}>
                </img>
            </a>
        </article>
    )
}

const BlogList = ({ blogs }) => {
    return (
        <section className="w-full grid grid-cols-1 lg:grid-cols-2 gap-8 md:gap-4">
            {blogs.map((blog, i) => {
                return <BlogListItem key={i} blog={blog} />
            })}
        </section>
    )
}

export default BlogList

And let's import it to Page.js:

import React from 'react'
import PostContent from './components/PostContent'
import BlogList from './components/BlogList'

const Page = ({ page }) => {

    if (page) {

        switch (page?.meta?.type) {
            case 'bloglist':
                return <BlogList blogs={page.data}/>
            case 'blogpost':
                return <div>Blog Post</div>
            case 'page':
                return <PostContent content={page.content || []}/>
            default:
                console.error('Unknown content type.')
        }
    }
    return (
        <>
        </>
    )
}

export default Page

And now we have a neat listing of blogs in our Blog page.

One final thing we want to do is to create a page for the blog posts. We can reuse the PostContent component to show the content, but we'll have to make another component to show the title and our feature image.

Let's make a file called BlogPost.js in the src/components/ folder with the following contents:

import React from 'react'
import PostContent from './PostContent'

const BlogPost = ({ blog }) => {

    return (
        <article className="w-full">
            {blog.featureImage ?
                <figure style={{
                    height: '60vh',
                    backgroundImage: `url(${blog.featureImage})`,
                    backgroundPosition: 'center',
                    backgroundRepeat: 'no-repeat',
                    backgroundSize: 'cover'
                }} className="w-full overflow-hidden">
                </figure>
                : <></>
            }

            <div className="w-full py-4 sm:px-4 lg:px-16">
                <header className="mb-8 text-center">
                    <h1 className="bold text-4xl">{blog.title}</h1>
                    <time className="bold text-lg text-indigo-700" dateTime={blog.date_published}>
                        {new Date(blog.date_published).toDateString()}
                    </time>
                </header>
                <PostContent content={blog.content || []} />
            </div>
        </article>
    )
}

export default BlogPost

And again, import it to our Page:

import React from 'react'
import PostContent from './components/PostContent'
import BlogList from './components/BlogList'
import BlogPost from './components/BlogPost'

const Page = ({ page }) => {

    if (page) {

        switch (page?.meta?.type) {
            case 'bloglist':
                return <BlogList blogs={page.data}/>
            case 'blogpost':
                return <BlogPost blog={page}/>
            case 'page':
                return <PostContent content={page.content || []}/>
            default:
                console.error('Unknown content type.')
        }
    }
    return (
        <>
        </>
    )
}

export default Page

And there we go. Our blog site is ready!

There's still a lot we could do, but I don't want to drag on this 3-part tutorial for 5 more parts, so we're going to end it here. I hope this was informational and enough to get you started on your own project.

I encourage you to play around a bit more and try to implement more features, or maybe you decided that Craft and React are not a good fit for you.

If you want to learn more, I would highly recommend checking out the Craft CMS Docs and Helsinki University's React web course. Unfortunately, Element API does not have much in the way of documentation, but you should still check out their Github Page.

Building a personal blog with Craft CMS, React and Element API / Part 2 - Creating a blog in Craft

Nominom — Thu, 14 May 2020 11:48:13 +0000

This is part 2 of my tutorial on building a blog site with React front-end and Craft CMS. If you missed the first one, you can find it here.

All the code for this tutorial is available on github.

In this part, we are going to set up a blog in Craft CMS, then expose the content with Element API.

Step 5 - Enabling extensions

In the last part, we told composer that we need Redactor and Element API, but in Craft, they are not yet enabled.

To enable them, navigate to your Craft admin panel, and then to Settings -> Plugins. You should see Element API and Redactor here. Just click on the gear icon next to both and click Install.

Step 6 - Setting up a simple blog in Craft

Let's start by creating our blog section. A section is a collection of entries. In Craft, an entry is the fundamental unit of content. For our website, every blog post will be a different entry of section 'blog'. Entries can also be single pages, structures of pages, or anything you want, really.

To Start, navigate to your Craft admin panel, and then to Settings -> Sections. Click on New Section, and give your section the name 'Blog'. Set the handle to 'blog' and section type to 'Channel'. The uri format should be 'blog/{slug}' and template 'index'. Click Save to save this section.

We'll also want to have a home page on our site, so let's create that one as well. Click again on New Section, and give this section the name 'Home'. Set the handle to 'home' and section type to 'Single'. Enable the little home checkmark button and select the template 'index'. Click on Save again.

Now, if we want our site to have images, we need to create an asset volume. To create an asset volume, navigate to Settings -> Assets, and click on New volume. Set the name to 'Images' and handle to 'images'. Set 'Assets in this volume have public URLs' to true, and the base url to '/assets/images'. The volume type should be set to 'Local Folder', and the file system path to '@webroot/assets/images'. Click Save.

The next thing to do, is to add some fields to our sections. Fields are units of data associated with an entry. To add some fields, navigate to Settings -> Fields, and click on the Common group on the left. Click on New Field, and make the name of our field 'Post Content'. Set the handle to 'postContent', and the instructions to something like 'The content of this post or page.'

The type of this field will be 'Matrix'. A Matrix field is a field, that contains blocks of different types of data. These blocks can be in any order, and you can have as many blocks as you'd like. For example, our Matrix will contain two types of blocks: text and images. In a more complex website, there could be many more different block types to choose from.

Once our Field type is set to 'Matrix' a Configuration table will appear. Click on New block type, and set the name to 'Text' and handle to 'text'. In the field settings, set the name to 'Text' again, and handle to 'text'. Set 'this field is required' to true, and the field type to 'Redactor' or 'Rich Text', depending on your version. If you want to allow inline styles, go to Advanced and untick 'Remove inline styles'.

Click on New block type again, and set the name to 'Image' and handle to 'image'. Set the name of the field to 'Image' and handle to 'image' again. Tick 'This field is required', and set the field type to 'Assets'. Set 'Restrict uploads to a single folder?' to true, and set the upload location as our asset volume 'Images'. Set 'Restrict allowed file types?' to true, and select 'Image' as the allowed file type. Set the limit to '1'. You can now click Save to save our field.

Let's create a few more fields, but this time in a different group. Still in the 'Fields' settings, click on New Group, and set the name of the group to 'Blog'. In the blog group, create a new field called 'Feature Image', with the handle of 'featureImage' and a type of 'Assets'. Set again the restriction to our Image asset volume, and the allowed file type to 'Image'. Set the limit to 1. Click Save, and add another field called 'Excerpt' with the handle of 'excerpt'. Set the field type to 'Plain Text' and field limit to 100 characters. Click Save.

Now that we have some fields, we need to add them to our sections. Navigate to Settings -> Sections, and click on Edit entry types (1) in our blog section. Click on Blog. In the field layout section, drag the entire 'Blog' box into the layout, and add the 'Post Content' field from 'Common'. Click Save.

Also edit the 'Home' entry type, and drag the 'Common' box into the field layout. Click Save.

At this point, you should go create some content for testing. Navigate to Entries on the side bar, add some text to the Home page and create at least a few blog posts. Add some images to the pages as well.

After you're done, make two more fields in a new group called 'Site Settings'. One image field for the site Logo, with the handle 'logo', and one plain text field for the footer text, with the handle of 'footerText'.

Next, navigate to Settings -> Globals and create a new global set. Give it the name 'Site Settings' and handle 'siteSettings'. Add the fields we created to the field layout and click Save. You can now choose a logo for your site, and set the footer text in the 'Globals' section in the sidebar.

Step 7 - Setting up Element API

Setting up Element API is a fairly simple process. All we have to do, is to create a file called element-api.php in our project's config/ folder, and paste the following contents:

<?php

use craft\elements\Entry;
use craft\elements\GlobalSet;
use craft\helpers\UrlHelper;


return [
    'endpoints' => [
        'site.json' => function() {
            return[
                'elementType' => 'craft\elements\GlobalSet',
                'criteria' => ['handle' => 'siteSettings'],
                'transformer' => function(GlobalSet $entry) {
                    $logo = $entry->logo->one();

                    return [
                        'logo' => $logo ? $logo->getUrl(['height' => 100]) : null,
                        'footerText' => $entry->footerText,
                    ];
                },
                'one' => true,
                'meta' => [
                    'type' => 'sitedata'
                ],
            ];
        },
    ]
];

This will create an api endpoint to /site.json that returns our Site Settings as a json file. What Element API does is whenever the specified endpoint is called, it creates an 'element query' that finds the requested data from Craft's database.

The elementType field is the type of element we are trying to find.
The criteria field is our search criteria.
The transformer method transforms the result of the query to an output Json object.
The one parameter tells Element API that we are expecting only a single result
The meta field can contain any arbitrary data that we want to send with the result. Here we are sending the type of this response, which is 'sitedata'

After you've created the file, you can point your browser to http://localhost:3001/site.json , and you should find that craft returns the Site Settings you've entered as a neat json file.

// http://localhost:3001/site.json
{
  "logo": "/assets/images/_AUTOx100_crop_center-center_none/test_gradient_1_512.jpg",
  "footerText": "Copyright me",
  "meta": {
    "type": "sitedata"
  }
}

Another thing we probably want to know from our website is the different pages that exist. To query for all Single entries, we need to modify our code to fetch them:

<?php

use craft\elements\Entry;
use craft\elements\GlobalSet;
use craft\helpers\UrlHelper;
use craft\helpers\ArrayHelper;
use craft\models\Section;

return [
    'endpoints' => [
        'site.json' => function() {
            return[
                'elementType' => 'craft\elements\GlobalSet',
                'criteria' => ['handle' => 'siteSettings'],
                'transformer' => function(GlobalSet $entry) {
                    $logo = $entry->logo->one();

                    $singleSections = ArrayHelper::where(\Craft::$app->sections->getAllSections(), 
                    'type', Section::TYPE_SINGLE);

                    $pages = Entry::find()
                        ->sectionId(ArrayHelper::getColumn($singleSections, 'id'))
                        ->all();

                    $pageInfos = [];

                    foreach ($pages as $page) {
                        $pageInfos[] = [
                            'title' => $page->title,
                            'url' => $page->url,
                            'jsonUrl' => UrlHelper::url("{$page->slug}.json")
                        ];
                    }

                    $pageInfos[] = [
                        'title' => 'Blog',
                        'url' => UrlHelper::url("blog/"),
                        'jsonUrl' => UrlHelper::url("blog.json")
                    ];

                    return [
                        'logo' => $logo ? $logo->getUrl(['height' => 100]) : null,
                        'footerText' => $entry->footerText,
                        'pages' => $pageInfos
                    ];
                },
                'one' => true,
                'meta' => [
                    'type' => 'sitedata'
                ],
            ];
        },
    ]
];

The above code makes a second query inside the transformer to find all the Single pages. Because our /blog endpoint is not a Single, we have to add it manually to the list. Now, our endpoint should return something like this:

// http://localhost:3001/site.json
{
  "logo": "/assets/images/_AUTOx100_crop_center-center_none/test_gradient_1_512.jpg",
  "footerText": "Copyright me",
  "pages": [
    {
      "title": "Home",
      "url": "http://localhost:3001/",
      "jsonUrl": "http://localhost:3001/home.json"
    },
    {
      "title": "Blog",
      "url": "http://localhost:3001/blog",
      "jsonUrl": "http://localhost:3001/blog.json"
    }
  ],
  "meta": {
    "type": "sitedata"
  }
}

The next endpoint we'll add is an endpoint to return the contents of our Home page. Add the tranformBodyContent method and the new endpoint definition to your element-api.php file:

<?php

use ...

function transformBodyContent(Entry $entry){
    $bodyBlocks = [];
    $blocks = $entry->postContent->all();
    foreach ($blocks as $block) {
        switch ($block->type->handle) {
            case 'text':
                $bodyBlocks[] = [
                    'type' => 'text',
                    'text' => $block->text->getParsedContent(),
                ];
                break;
            case 'image':
                $image = $block->image->one();
                $bodyBlocks[] = [
                    'type' => 'image',
                    'image' => $image ? $image->getUrl() : null,
                ];
                break;
        }
    }
    return $bodyBlocks;
}

return [
    'endpoints' => [
        'site.json' => function() {
            ...
        },
        '<_:home\.json|\.json>'  => function() {
            return[
                'elementType' => 'craft\elements\Entry',
                'criteria' => ['slug' => 'home'],
                'transformer' => function(Entry $entry) {
                    return [
                        'title' => $entry->title,
                        'date_published' => $entry->postDate->format(\DateTime::ATOM),
                        'date_modified' => $entry->dateUpdated->format(\DateTime::ATOM),
                        'content' => transformBodyContent($entry),
                    ];
                },
                'one' => true,
                'meta' => [
                    'type' => 'page'
                ],
            ];
        },
    ]
]

The funny looking endpoint url is just a regex for matching either /home.json or /.json, this will help our front-end in fetching the correct data without having to make an edge-case condition when the web root is requested.

You might also wonder what the transformBodyContent function does. It's a simple helper function to help us parse the body content that is the same field in multiple sections, without having to duplicate a lot of code.

Verify that both http://localhost:3001/.json and http://localhost:3001/home.json work, and send back valid data.

Next, let's create endpoints for both listing blog posts, and fetching the content of a single blog post:

<?php

use ...

function transformBodyContent(Entry $entry){
    ...
}


return [
    'endpoints' => [
        'site.json' => function() {
            ...
        },
        '<_:home\.json|\.json>'  => function() {
            ...
        },
        'blog.json'  => function() {
            return[
                'elementType' => 'craft\elements\Entry',
                'criteria' => [
                    'section' => 'blog',
                    'orderBy' => 'postDate desc',
                ],
                'transformer' => function(Entry $entry) {
                    $featureImage = $entry->featureImage->one();

                    return [
                        'title' => $entry->title,
                        'date_published' => $entry->postDate->format(\DateTime::ATOM),
                        'date_modified' => $entry->dateUpdated->format(\DateTime::ATOM),
                        'url' => $entry->url,
                        'jsonUrl' => UrlHelper::url("blog/{$entry->slug}.json"),
                        'excerpt' => $entry->excerpt,
                        'featureImage' => $featureImage? $featureImage->getUrl() : null,
                    ];
                },
                'elementsPerPage' => 8,
                'meta' => [
                    'type' => 'bloglist'
                ],
            ];
        },
        'blog/<slug:{slug}>.json'  => function($slug) {
            return[
                'elementType' => 'craft\elements\Entry',
                'criteria' => [
                    'section' => 'blog',
                    'slug' => $slug
                ],
                'transformer' => function(Entry $entry) {
                    $featureImage = $entry->featureImage->one();

                    return [
                        'title' => $entry->title,
                        'date_published' => $entry->postDate->format(\DateTime::ATOM),
                        'date_modified' => $entry->dateUpdated->format(\DateTime::ATOM),
                        'content' => transformBodyContent($entry),
                        'excerpt' => $entry->excerpt,
                        'featureImage' => $featureImage? $featureImage->getUrl() : null,
                    ];
                },
                'one' => true,
                'meta' => [
                    'type' => 'blogpost'
                ],
            ];
        },
    ]
];

The /blog.json endpoint should return a list of blog posts, ordered by their post date. The elementsPerPage parameter controls how many results will be sent back. You can fetch older posts with the page query parameter, for example: /blog.json?page=2.

The /blog/<slug>.json endpoint returns a single blog post with the specified slug. The slug is usually the title of the blog post but in lower case and spaces replaced with hyphens. Here we are using the transformBodyContent function again to convert the post content to json.

The final element-api.php should look something like this:

<?php

use craft\elements\Entry;
use craft\elements\GlobalSet;
use craft\helpers\UrlHelper;
use craft\helpers\ArrayHelper;
use craft\models\Section;

function transformBodyContent(Entry $entry){
    $bodyBlocks = [];
    $blocks = $entry->postContent->all();
    foreach ($blocks as $block) {
        switch ($block->type->handle) {
            case 'text':
                $bodyBlocks[] = [
                    'type' => 'text',
                    'text' => $block->text->getParsedContent(),
                ];
                break;
            case 'image':
                $image = $block->image->one();
                $bodyBlocks[] = [
                    'type' => 'image',
                    'image' => $image ? $image->getUrl() : null,
                ];
                break;
        }
    }
    return $bodyBlocks;
}


return [
    'endpoints' => [
        'site.json' => function() {
            return[
                'elementType' => 'craft\elements\GlobalSet',
                'criteria' => ['handle' => 'siteSettings'],
                'transformer' => function(GlobalSet $entry) {
                    $logo = $entry->logo->one();

                    $singleSections = ArrayHelper::where(\Craft::$app->sections->getAllSections(), 
                    'type', Section::TYPE_SINGLE);

                    $pages = Entry::find()
                        ->sectionId(ArrayHelper::getColumn($singleSections, 'id'))
                        ->all();

                    $pageInfos = [];

                    foreach ($pages as $page) {
                        $pageInfos[] = [
                            'title' => $page->title,
                            'url' => $page->url,
                            'jsonUrl' => UrlHelper::url("{$page->slug}.json")
                        ];
                    }

                    $pageInfos[] = [
                        'title' => 'Blog',
                        'url' => UrlHelper::url("blog/"),
                        'jsonUrl' => UrlHelper::url("blog.json")
                    ];

                    return [
                        'logo' => $logo ? $logo->getUrl(['height' => 100]) : null,
                        'footerText' => $entry->footerText,
                        'pages' => $pageInfos
                    ];
                },
                'one' => true,
                'meta' => [
                    'type' => 'sitedata'
                ],
            ];
        },
        '<_:home\.json|\.json>'  => function() {
            return[
                'elementType' => 'craft\elements\Entry',
                'criteria' => ['slug' => 'home'],
                'transformer' => function(Entry $entry) {
                    return [
                        'title' => $entry->title,
                        'date_published' => $entry->postDate->format(\DateTime::ATOM),
                        'date_modified' => $entry->dateUpdated->format(\DateTime::ATOM),
                        'content' => transformBodyContent($entry),
                    ];
                },
                'one' => true,
                'meta' => [
                    'type' => 'page'
                ],
            ];
        },
        'blog.json'  => function() {
            return[
                'elementType' => 'craft\elements\Entry',
                'criteria' => [
                    'section' => 'blog',
                    'orderBy' => 'postDate desc',
                ],
                'transformer' => function(Entry $entry) {
                    $featureImage = $entry->featureImage->one();

                    return [
                        'title' => $entry->title,
                        'date_published' => $entry->postDate->format(\DateTime::ATOM),
                        'date_modified' => $entry->dateUpdated->format(\DateTime::ATOM),
                        'url' => $entry->url,
                        'jsonUrl' => UrlHelper::url("blog/{$entry->slug}.json"),
                        'excerpt' => $entry->excerpt,
                        'featureImage' => $featureImage? $featureImage->getUrl() : null,
                    ];
                },
                'elementsPerPage' => 8,
                'meta' => [
                    'type' => 'bloglist'
                ],
            ];
        },
        'blog/<slug:{slug}>.json'  => function($slug) {
            return[
                'elementType' => 'craft\elements\Entry',
                'criteria' => [
                    'section' => 'blog',
                    'slug' => $slug
                ],
                'transformer' => function(Entry $entry) {
                    $featureImage = $entry->featureImage->one();

                    return [
                        'title' => $entry->title,
                        'date_published' => $entry->postDate->format(\DateTime::ATOM),
                        'date_modified' => $entry->dateUpdated->format(\DateTime::ATOM),
                        'content' => transformBodyContent($entry),
                        'excerpt' => $entry->excerpt,
                        'featureImage' => $featureImage? $featureImage->getUrl() : null,
                    ];
                },
                'one' => true,
                'meta' => [
                    'type' => 'blogpost'
                ],
            ];
        },
    ]
];

Verify that both endpoints work and return valid data.

This part is over, but join me in the next one where we finally build a React front-end for our blog.

Building a personal blog with Craft CMS, React and Element API / Part 1 - Setting up

Nominom — Thu, 14 May 2020 11:09:29 +0000

I recently built a Craft CMS website and decided to use React as the front-end. I was inspired to make this tutorial to help you get started on your own Craft + React project by building a small blog site.

If there are punctuation marks in funny places or some weird phrases, I'll apologize in advance. English is not my first language.

I recommend having some basic knowledge of React, html and css, but complete beginners can also follow along. You don't need to know anything about Craft CMS beforehand.

This tutorial was made with the following versions:

node - 13.12.0
React - 16.13.1
composer - 1.10.5
php - 7.4.5
Craft - 3.4.18
Element API - 2.6.0
Redactor - 2.6.1

If something major changes in future versions, something in this tutorial might break or not work as expected.

All the code for this tutorial is available on github.

What is Craft CMS?

On their website, Pixel & Tonic say that

"Craft is a flexible, user-friendly CMS for creating custom digital experiences on the web and beyond."

In other words, it's a content management platform where everything is customizable, and you're in control of your content and presentation. You can learn more about craft by visiting the Craft CMS docs.

For people who have used WordPress, the editorial experience is quite similar, with the difference being that you can choose yourself what fields your posts and pages will have. Another difference is, that there are no premade templates to choose from. You're in charge of the front-end.

Why react?

Now some of you might wonder, why would I use React as the front-end for my Craft site, when I can just use Craft's built-in twig template functionality?

The main reason I would argue, is that React makes your front-end development a much less painful experience, than trying to develop twig templates with some css and javascript files. With react, you have easy access to things like styled components, Tailwind and thousands of other packages to help you make the website you want to make.

Another reason for React is performance. When your browser requests a page, it has to load the main bundle for the first time, sure. And that can slow down the first load of the site. But once the javascript bundle is loaded, loading new pages is blazing fast because all your browser has to do, is to fetch the next page as a json file, which is much lighter than fetching a whole new html document every time you navigate to a new page.

Step 0 - Getting started

If you need a refresher on React or you're a complete beginner, I recommend checking out the Full Stack Open course by University of Helsinki, which will get you started on React development. You don't need to know React to copy and paste along, but knowing the very basics is recommended to get a better understanding of what we're doing.

You will most likely need php 7.x+ and composer installed on your machine. If you don't want to do that there are ways to work around it, like developing through a remote connection to the server. In that case, you should have an ftp connection to your target server and have WinSCP or similar sync your project folder to the server. You should at least have composer installed on the target machine, and an ssh connection to run the commands.

You'll also need node and either npm or Yarn installed on your development machine to install node packages. For this tutorial I'll be using npm.

An sql or postgres database is required, running either locally or on a remote server.

Verify that everything is working by running these commands:

$ php -v
$ composer -v
$ node -v
$ npm -v

Step 1 - Installing Craft CMS

Start by creating a new folder in the directory of your choosing and going in.

$ mkdir CraftWithReact
$ cd CraftWithReact

Next, we'll use composer to install Craft by typing

$ composer create-project craftcms/craft ./

After composer has done it's job, we should find that the directory now contains a freshly installed Craft project.

The next step is to set up the .env file. Currently, it should look something like this:

# The environment Craft is currently running in 
# ('dev', 'staging', 'production', etc.)
ENVIRONMENT="dev"

# The secure key Craft will use for hashing and encrypting data
SECURITY_KEY="e3xGl7yfn-IvcdI0E1wiGAt6d1tGd4qr"

# The Data Source Name (“DSN”) that tells Craft how to connect to the database
DB_DSN=""

# The database username to connect with
DB_USER="root"

# The database password to connect with
DB_PASSWORD=""

# The database schema that will be used (PostgreSQL only)
DB_SCHEMA="public"

# The prefix that should be added to generated table names 
# (only necessary if multiple things are sharing the same database)
DB_TABLE_PREFIX=""

The main thing to change here is to input your sql or postgres database details. If you have a local mysql database running, edit your file to look something like this:

# The environment Craft is currently running in 
# ('dev', 'staging', 'production', etc.)
ENVIRONMENT="dev"

# The secure key Craft will use for hashing and encrypting data
SECURITY_KEY="e3xGl7yfn-IvcdI0E1wiGAt6d1tGd4qr"

# The Data Source Name (“DSN”) that tells Craft how to connect to the database
DB_DSN="mysql:host=localhost;port=3306;dbname=craftcms"

# The database username to connect with
DB_USER="root"

# The database password to connect with
DB_PASSWORD="password"

# The database schema that will be used (PostgreSQL only)
DB_SCHEMA="public"

# The prefix that should be added to generated table names 
# (only necessary if multiple things are sharing the same database)
DB_TABLE_PREFIX="craft"

Next up, we need to tell composer that we need to use some packages for craft. Mainly, ImageMagic, Element API and Redactor.

Open up composer.json file, and add the following lines:

{
    "require": {
        "craftcms/cms": "^3.4.0",
        ...
        "ext-imagick": "*",
        "craftcms/redactor": "*",
        "craftcms/element-api": "*"
    },
    "require-dev": {
        ...

Then, we need to run composer update to update the composer.lock file.

$ composer update

Step 2 - Creating a node project

Run the npm init command in the project directory.

$ npm init

The command will run you through creating a node project, but you can pretty much leave everything as default if you like.

After we've initialized our node project, let's install some packages!

$ npm install --save react react-dom axios
$ npm install --save-dev webpack webpack-cli 
$ npm install --save-dev @babel/core babel-loader @babel/preset-env @babel/preset-react

If you have a git repository, you should add the following lines to your .gitignore:

...
# dependencies
/node_modules
/.pnp
.pnp.js

# testing
/coverage

# misc
.DS_Store
.env.local
.env.development.local
.env.test.local
.env.production.local

npm-debug.log*
yarn-debug.log*
yarn-error.log*

Webpack and babel

Webpack will handle the packing of our javascript files, and babel will compile our ES6 code to be more compatible with older browsers.

To set up Webpack, we need to create a webpack.config.js file, with the following contents:

const path = require('path');
module.exports = {
    // define entry file and output
    entry: {
        main: './src/index.js',
    },
    output: {
        path: path.resolve('./web/res'),
        filename: '[name].js'
    },
    // define babel loader
    module: {
        rules: [
            { test: /\.(js|jsx)$/, loader: 'babel-loader', exclude: /node_modules/ }
        ]
    }
};

This sets up our webpack build, so that our entry point will be located in the ./src/index.js' file, and the final output will be in ./web/res/ folder.

The web/ folder is the folder where craft expects its static resources to be in. If your hosting environment wants this folder to be named something else like html/, public_html/ or public/, craft should be fine with it but remember to reflect that change here.

To set up Babel we need to create a .babelrc file, with the following contents:

{
    "presets": [
        "@babel/preset-env",
        "@babel/preset-react"
    ]
}

You might encounter an error if using a newer version of babel and react. In that case changing the .babelrc contents to the following might help:

{
    "presets": [
        "@babel/preset-env",
        [
            "@babel/preset-react",
            {
                "runtime": "automatic"
            }
        ]
    ]
}

And finally we add the following lines to the package.json file:

{
    ...
    "scripts": {
        ...
        "dev": "webpack --watch --mode development",
        "build": "webpack --mode production"
    },
    ...

Local php dev server (Optional)

If you want to test Craft locally without installing apache, nginx or IIS, you can install node-php-awesome-server to run Craft locally in node.

Running php in node is very slow, so the speeds you see with this setup are snail pace compared to what you'll see in production.

$ npm install --save-dev node-php-awesome-server

Next, create a devserver.js file with the following contents:

const nodePhpAwesomeServer = require('node-php-awesome-server');

const php = nodePhpAwesomeServer({
    port: 3001,
    root : 'web',
    ini_set: {
        max_execution_time: 280
    },
    output: {
        os: true,
        browser: true,
        device: true,
        reqTime: true
    },
    clustersSet: 'auto',
    phpPerCluster: 2

});

php.on('close', () => {
    console.log('php server closed');
});

php.on('connect', () => {
    console.log('All up and running');
});

And add the following line to your package.json file:

{
    ...
    "scripts": {
        ...
        "dev": "webpack --watch --mode development",
        "build": "webpack --mode production",
        "startdev": "node devserver.js"
    },
    ...

Now, if you run the command

$ npm run startdev

... you should be able to access Craft from http://localhost:3001

Note that the page will most likely throw a 503 Service Unavailable Error, because we have not yet completed Craft setup.

Step 3 - Finalizing craft setup

If you have your web server running and pointing to the project web/ directory, you should be able to access the craft installer by navigating to http://localhost:3001/admin/install on your web browser.

Some people might experience some missing php plugins here, which craft will tell you about. You can usually enable them by uncommenting the corresponding line in your php.ini file.

If all is good, and you see the "Install Craft" button, just follow the setup process by creating a user and setting up the page name and base url.

Step 4 - React Hello world

To get React working with craft, we need to to set up our twig template to load our javascript bundle.

In the templates folder, create or overwrite index.twig file with the following contents:

<!DOCTYPE html>
<html lang="{{ craft.app.language }}">
    <head>
        <meta http-equiv="X-UA-Compatible" content="IE=edge"/>
        <meta charset="utf-8"/>
        <title>{{ siteName }}</title>
        <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=5.0, viewport-fit=cover"/>
        <meta name="referrer" content="origin-when-cross-origin"/>
    </head>
    <body>
        <div id="root"></div>
        <script type="text/javascript" src="/res/main.js"></script>
    </body>
</html>

If you need to add any css files to your project, just plop them here as well.

After that, create a new folder called src/ to the base directory of the project.

$ mkdir src

Create our entry src/index.js file with the following contents:

import React from 'react'
import ReactDOM from 'react-dom'
import App from './App'

ReactDOM.render(
    <App />,
    document.getElementById('root')
)

After that, create src/App.js file with these contents:

import React from 'react'

const App = () => {
    return(
        <div>
            Hello World!
        </div>
    )
}

export default App

And then, build the bundle:

$ npm run build

If we start our development server again, and navigate to http://localhost:3001/ we should see a little "Hello World!" pop up.

Join me in the next one, where we setup element API and build a small blog website in Craft with our setup.