Building components

1. Creating a basic component (Eyebrow)

Before we dive into the more advance stuff, let's start by creating a super simple component. The component name is Eyebrow, and this is a component you would normally use to label or tag content, or to print a sinple line of plain text.

Component's data

1. Inside nitflex_dev_theme/src/components/ create a new directory called eyebrow

2. Inside the new directory create a new file called eyebrow.json.

3. Inside eyebrow.json copy the following code:

   {
    "eyebrow": "Action and  Adventure",
    "classes": ""
   }
   

   We just created a JSON object with a key of eyebrow and value of Action and Adventure. We will get deeper into JSON objects when we build more advance components.

   The classes key is a variable placeholder so we can pass a modifier CSS class when we make use of this component. Modifier classes allow us to create variations of components without havign to recreate the component from scratch. These classes are used by CSS to make changes to the look and feel of a component. More on this later.

   Things you should know about JSON code format

   JSON code format requirements are very specific and needs to be perfect or things will not work. Each item in an object or array needs to have a trialing comman (,), except the last one. Indentation is very specific (2 or 4 spaces, but not both on the same file). Always check for typos and key names are always in lower case. Use underscores to separate multi word keys, not hyphens.

Component's markup

1. Inside the eyebrow directory create a new file called eyebrow.twig.

2. Inside eyebrow.twig copy the following code:

   
   <p class="eyebrow {{ classes|default('') }}">{{ eyebrow }}</p>
   

   The twig template allows us to write the markup we deem most appropriate for our components. In addition, we are passing data from the JSON object into Twig as well as using a placeholder for the classes variable.

Component's styles and styleguide code

1. Inside the eyebrow directory create a new file called eyebrow.scss.

2. Inside eyebrow.scss copy this code:

   // Eyebrow
   //
   // This is the eyebrow component.
   //
   // Markup: eyebrow.twig
   //
   // Style guide: Components.Eyebrow
   
   // Import site utilities.
   @import '../../global/utils/init';
   
   .eyebrow {
    display: inline-block;
    letter-spacing: 0.15rem;
    line-height: 1;
    text-transform: uppercase;
    white-space: nowrap;
   }
   

Notice the commented code?

In addition to the component's styles, you may have noticed the commented code at the top of the file. These comments are what KSS Node uses to build the component in the styleguide. You can learn more about how KSS Node works here.

Basics

• First line of commented code is reserved for the component name, followed by an empty line.

• Next line of commented code is for a description of the component. This can be as brief or long as you woud like and can include plain text as well as html markup. This is followed by an empty line.

• The Markup tag accepts a path to a file where the component markup exists (i.e. eyebrow.twig), or you can literally write the component markup inline (i.e. <p class="eyebrow">Eyebrow text</p>). Also followed by an empty line.

• Finally, Style guide indicates where in the styleguide our component will appear. In the example above the component will appear under the Components section and it will be labeled as Eyebrow. Think of this line as categories for style guide where you can categorize your components (i.e. components, utils, typography, etc.).

• There is also an option you don't see here, that's the weight option which allows you to set the order in which components are listed in the styleguide within a given section. By default the order is alphabetical.

Compiling the styleguide

Now that we have writen all the necessary code to build the Eyebrow component, it's time to see the component in the styleguide. Let's compile our project first.

• From the theme's root (/themes/custom/nitflex_dev_theme), run the following command:

  lando npm run build
  

Viewing the Eyebrow component

Open your drupal site and point to the URL below

http://nitflex.lndo.site:8000/themes/custom/nitflex_dev_theme/dist/style-guide/index.html

Depending on your setup, you may not need to enter ":8000". Also if you did not use the provided Lando setup, ensure you are using your own custom URL.

Under the Components category you should see the new Eyebrow component.

Next exercise: Building a Heading component