Create component documentation added to components section.

[thiagodemellobueno]

Components

Component based approaches to web development have been around for some time, however more formalized systems like Brad Frost's Atomic Design have become more popular recently. Thinking about a web page as a system of discrete components enable us to approach building more granularly and maintain consistency across a whole project. The components are the building blocks that we craft sites with and maintiaining this approach allows us to use Kalastatic to quickly build out prototype pages and automagically generate a styleguide for your project.

In Kalastatic a component consists of a folder containing:

• A Sass file
  • All the styles that apply to this component.
• A Twig template
  • All the markup needed for the component
  • Twig logic and/or placeholder variables that will get populated with content on build.
• A json file
  • Dummy data used to populate the Twig template for the styleguide.
  • Can also be used to hold non-dummy static data like strings of text or images that won't get dynamically populated by other methods. TODO: link to section on json mock data.

How to add a new component

We suggest sorting your components into folders that demarkate their complexity based on Atomic Design. However Kalastatic doesn't enforce this.

To create a new component, make a new folder inside the components directory. Let's use 'button' as an example. Inside the button folder create three new files:

• button.scss
• button.html.twig
• button.json

Create Component

We provide a handy command create-component or cc that takes care of some of generating these files (and soon providing boilerplate content for valid json, and pre-configured kss headers).

Command

kalastatic create-component <objectToCreate> [otherObjects...]

Alias

cc

Options

kalastatic cc --directory=path/to/where/you/want/ defaults to src/components

Usage

kalastatic cc atoms/links or kalastatic cc atoms/link or kalastatic cc --directory=path/you/want/the/files/to/go atoms/link atoms/button molecules/article-teaser

or FTW

kalastatic cc --directory=path/you/want/the/files/to/go `cat components.txt

assuming the contents of components.txt is:

atoms/links
atoms/buttons
molecules/cta
molecules/tout

Component Sass

Adding a KSS comment to the top of your component's Sass file will enable KSS to build out the styleguide including our new component.

/*

Button

A button for our website

Markup: button.html.twig

Styleguide content.button

*/

For more indepth documentation on KSS and it's conventions see Styleguide TODO: make internal links work.

Add styles that are specific to this button component. We suggest using the fugly selector method because it promotes extensibility and reusability but this is not required by Kalastatic.

%button {
  padding: 2em 1em;
  background-color: $brand-primary;
  color: #fff;
  border-radius: 20px;
 }

 a.button,
 button,
 input[type=submit] {
   @extend %button;
 }

Now that our component's Sass file exists, it's now a good idea to include it from your main.scss so it's styles get included in the build.

@import '../components/atoms/button/button';

Component Twig

Your component's Twig file contains the markup and variables/logic needed to display the component. For more information on this see the Twig documentation

<a href="{{ url }}" class="button {{ classes|join(" ") }}">{{ text }}</a>

Component json

The component's json file contains json data that is used to populate the variables in the Twig file. The top level keys should match the variable names in the Twig template. The Kalastatic build will fail if your json is not valid. Note that when you change json data, you need to stop and restart Kalastatic to see the changes come through in the browser. This is a known quirk that will get fixed in future versions.

{
  "text": "Click me, slowly.",
  "url": "page.html"
}

How do you include another component?

Some components are made up of a collection of other components. Acheiving this in Twig is easy with the include directive.

{% include 'template.html' with {'foo': 'bar'} %}

When do you use only and why?

When including templates within other templates it's advisable to use the only declaration for passing variables.

{% include 'template.html' with var only %}

This is a form of dependecy injection that has a number of benefits:

• It saves memory
• Makes builds faster
• Keeps components self contained and therefore portable/reusable.

When the only directive is not used, the entire variable scope is passed to the template. While this may be needed/desirable in some cases it's generally considered bad practice.

Extending components

A component can also use the Twig extends directive to extend a Twig block. For more information see the Twig extends documentation.