Develop a Simple Flynt Component in 6 Steps

Welcome to the guide for developing a simple component with the Flynt framework. In this tutorial, we will walk through six simple steps to create a basic component, starting off with static content, and then enhancing the component in each step by adding content fields, styles, and scripts.

Before we get moving, it's important that you have setup a new Flynt project with the Flynt CLI. Check out the Setting up Flynt page if you need help with this.

Something to remember is that all components must be inside the Components directory of your theme for Flynt to find them. The location of this directory can be changed with Flynt Core.

1. Creating the view file

To start, we'll create an example BlockQuote component. The most basic component only needs a single markup (view) file using the templating engine Twig.

Create a folder in the Components directory named BlockQuote and add a file named index.twig. For now, add the following plain HTML to index.twig:

<div is="flynt-block-quote" class="flyntComponent">
    <blockquote class="blockQuote">
        <p>Mistakes are always forgivable, if one has the courage to admit them.</p>
        <footer>- <cite>Bruce Lee</cite></footer>
    </blockquote>
</div>

Here, the is attribute and classes are part of the Flynt best practices. We'll come back to this in more detail later when it comes to adding styles and scripts to our component.

Your theme folder will now look like this:

├── flynt-starter-theme
| ├──Components
| | ├── BlockQuote
| | | └── index.twig

2. Rendering your component

To render our BlockQuote component, we need to add it to a page template.

All template files can be found in the theme folder, in the templates directory. Each PHP template within the templates directory takes a simple JSON configuration file, and using the Flynt Core plugin, parses and renders this into HTML.

For example, take templates/page.php:

<?php

Flynt\echoHtmlFromConfigFile('default.json');

The JSON template configuration files are found in config/templates. These configuration files define the components and their areas which are loaded into the template.

For now, we will add the BlockQuote component to the default.json template.

Open config/templates/default.json and add the BlockQuote component to the pageComponents array:

{
  "name": "DocumentDefault",
  "areas": {
    "layout": [
      {
        "name": "LayoutMultiplePosts",
        "areas": {
          "mainHeader": [],
          "pageComponents": [
            {
              "name": "BlockQuote"
            }
          ],
          "mainFooter": []
        }
      }
    ]
  }
}

You can read more about how page templates work here.

Make sure that you have started your local server by running flynt start in your terminal, then open http://localhost:3000 (your port may be different) to see your BlockQuote component on the homepage.

The flynt start command is provided by the Flynt CLI, and will take care of compiling the theme and starting up a local server, as well as watching our theme files for further changes.

Congratulations! You have successfully created your first Flynt component.

Now we'll take our static component and make it more useful by allowing our back end user to add the data for our quote dynamically.

Flynt leverages the WordPress plugin Advanced Custom Fields (ACF) so that we can quickly and easily add fields for each component to WordPress edit screens.

3. Creating a field group

Because Flynt uses ACF, we can create groups of content fields and assign each group location rules for where they should show up in the WordPress administrator back end. This is called a "field group". We create field groups using JSON configuration files, all of which can be found in config/fieldGroups.

Before we create the individual content fields for our component, we will begin by preparing our field group. Since we want to make our component available on all pages, we will add our BlockQuote component to the pageComponents.json field group in config/fieldGroups/pageComponents.json.

Replace the contents of pageComponents.json with the following:

{
  "name": "pageComponents",
  "title": "Page Components",
  "fields": [
    {
      "name": "pageComponents",
      "label": "Page Components",
      "type": "flexible_content",
      "button_label": "Add Component",
      "layouts": [
        "Flynt/Components/BlockQuote/Fields/Layout"
      ]
    }
  ],
  "location": [
    [
      {
        "param": "post_type",
        "operator": "==",
        "value": "page"
      }
    ]
  ]
}

Here, we define the essential properties of the field group: The name, the title (visible in the WordPress back end), and the location rules for where these fields should show up. We also create a Flexible Content field, so that the user will be able to add our component to any page multiple times and in any order.

Inside the layouts of our flexible content field, we tell Flynt to look for the layout array inside the fields file of our BlockQuote component:

{
  ...
  "layouts": [
    "Flynt/Components/BlockQuote/Fields/Layout"
  ]
}

Now we need to create these "layout" fields for our BlockQuote component!

4. Creating a Fields File

Inside each component, fields are defined in a JSON configuration file named fields.json.

Begin by creating fields.json inside your BlockQuote component folder so that your theme folder looks like this:

├── flynt-starter-theme
| ├──Components
| | ├── BlockQuote
| | | ├── fields.json
| | | └── index.twig

Inside fields.json add the following:

{
  "layout": {
    "name": "blockQuote",
    "label": "Block Quote",
    "sub_fields": []
  }
}

Here we provide Flynt with some basic information about our component. We have defined the layout array with a unique name property, set a display label (the visible label in the WordPress back end), and prepared an empty sub_fields array, where we will place our individual content fields.

We will now define two text fields inside the sub_fields array - one for the quote text, and one for the citation:

{
  "layout": {
    "name": "blockQuote",
    "label": "Block Quote",
    "sub_fields": [
      {
        "label": "Quote",
        "name": "quote",
        "type": "text",
        "required": 1
      },
      {
        "label": "Citation",
        "name": "citation",
        "type": "text",
        "required": 1
      }
    ]
  }
}

To output the data that the user enters into these fields, we need to replace the text in the view template with each field's name property as defined in fields.json. Update Components/BlockQuote/index.twig to match the following:

<div is="flynt-block-quote" class="flyntComponent">
    <blockquote class="blockQuote">
        <p>{{ quote }}</p>
        <footer>- <cite>{{ citation }}</cite></footer>
    </blockquote>
</div>

Refresh your page and you'll see... nothing! That's because we haven't added any data to the WordPress back end yet.

Navigate to the WordPress back end of your installation and create a new page called "Quotes". Use the "Add Component" and select the "Block Quote" component to add it to the page:

You can now add content to the fields we defined inside the fields configuration file:

Publish the page and point your browser to http://localhost:3000/quotes to see your component with the data pulled in from the back end!

To add CSS to a component, you can add a style file either as a plain CSS file (.css), or as a Stylus file (.styl). In this tutorial, we will use Stylus.

Create style.styl in your BlockQuote folder, so that your theme folder matches the following:

├── flynt-starter-theme
| ├──Components
| | ├── BlockQuote
| | | ├── fields.json
| | | ├── index.twig
| | | └── style.styl

Next, lets open style.styl and add some basic styling. We'll be using the recommended Flynt best practices when it comes to styling our component.

.flyntComponent[is='flynt-block-quote']
  *,
  *:before,
  *:after
    box-sizing: border-box

  .blockQuote
    background-color: #f3f3f3
    border-left: 5px solid #558c89
    margin: 0 auto
    max-width: 550px
    padding: 30px

Providing you have run flynt start in your terminal (from the flynt theme directory), Flynt will now compile Components/BlockQuote/style.styl into dist/Components/BlockQuote/style.css.

5. Enqueuing your assets

There is one crucial step missing. To load these styles into the front end, you must enqueue these styles using the functions.php file of your component. The functions file can be used for all of your custom server side logic that is specific to your component.

First, create functions.php inside your BlockQuote component. Your theme folder should now look like this:

├── flynt-starter-theme
| ├──Components
| | ├── BlockQuote
| | | ├── fields.json
| | | ├── functions.php
| | | ├── index.twig
| | | └── style.styl

Inside functions.php we will use the Components feature inside the WordPress wp_enqueue_scripts action to enqueue our style file. This 'action' is one of many hooks provided by WordPress to allow us to 'hook into' the rest of WordPress at a specific time. Flynt comes with a range of features that take advantage of these hooks, which you can explore here.

Add the following code to Components/BlockQuote/functions.php.

<?php
namespace Flynt\Components\BlockQuote;

use Flynt\Features\Components\Component;

add_action('wp_enqueue_scripts', function () {
    Component::enqueueAssets('BlockQuote');
});

Flynt will now look for Components/BlockQuote/style.css, and enqueue the file if it is found.

Refresh the front end of your website and you will now see your styles!

6. Adding scripts

To add custom JavaScript logic to your component, create a script.js file inside your component, so that your theme folder matches the following:

├── flynt-starter-theme
| ├──Components
| | ├── BlockQuote
| | | ├── fields.json
| | | ├── functions.php
| | | ├── index.twig
| | | ├── script.js
| | | └── style.styl

Inside script.js you can add all of the JavaScript logic that you need. Flynt supports ES2015 (ES6) out of the box, and will compile your script to ES5 using Babel. ES2015 is a significant update to the JavaScript language, but it is only our recommendation. You do not have to use this and can write your JavaScript inside script.js however you wish.

Open Components/BlockQuote/script.js and add the following:

class BlockQuote extends window.HTMLDivElement {
  connectedCallback () {
    console.log('The BlockQuote component has been inserted into the DOM!')
  }
}

window.customElements.define('flynt-block-quote', BlockQuote, {extends: 'div'})

To load this script into the front end, you must ensure you have enqueued the assets for this component, as shown above. Flynt will then look for Components/BlockQuote/script.js and enqueue the file if it is found.

That's it - refresh the front end and check your console! You have now completed your first component.

Tutorial Complete!

Congratulations on creating your first component with a view template, dynamic fields, styles, and scripts.

Download the BlockQuote component

Next Steps

Michael Carruthers

Michael is a British front end web developer working at bleech in Berlin, with a passion for creating user-friendly web experiences (and drinking tea, of course).