Components

The reactor starter theme comes with a component framework and library.

Overview of components

This list will reflect the components that are currently available in the reactor theme, and the features they support.

• Button
• Card
• Collapsible
• Element
• Heading
• Hero

Render functions

There are several functions that come with this library, here is how and when to use which function.

fuse( $components, array $args ) : FuseComponent

The fuse command is used to create a compontent. The first paramater $components is the name of the component, while $args passes the arguments – these are the attributes that the component will be rendered with.

Args can in theory be any type, but not all types will be supported. However, any argument can be a function (though, these need to be provided as a FuseCallable).

The component object is returned, and not rendered until echo is used.

fuse_html( $html ) : FuseComponent

This is a shorthand function for fuse( ‘html’, [ ‘content’ => $content ] );

fuse_heading( $content, $level = null, array $args = [] ) : FuseComponent

A shorthand function that returns a heading component.

fuse_template( $template, array $args = [] )

A shorthand function that returns a template component. The template components will return the contents of get_template_part, of the chosen template and passes the $args onto that template. No outer wrapper is applied and the args aren’t processed by fuse.

fuse_print( $component, $args ) : FuseComponent

Same as using echo fuse(...)

fuse_loop( $callable, $args ) : array

A function ($callable) is run for each of the elements in the array ($args). The callable should return a fuse component – otherwise that item is discarded/skipped. The function returns an array that is suitable for attributes meant for child components.

Component setup

Components are located in /partials/components/. Each component has its own folder with an identically named php file inside. In addition, a file with the suffix -config.php can be added to add additional configuration of the arguments that the element supports. The following methods can used on the $args object in the -config.php file.

Adding attributes to your component

Components are meant to be flexible. And for that purpose, we try to add options to them. We call these attributes. We pass these to the component, so that the component knows how to render. A basic example of this is passing a class or href. Other attributes are more advanced, they can be set up to handle child elements, or be more like settings that configure the component, we call these options.

$args->add_attribute( $key, $value = null, $default = null, $is_attribute = null )

This is the underlying method of adding attributes.

• $key: A unique key to identify this attribute
• $value: This is the value we assign to the attribute, null means no value will be set.
• $default: The value to be used if none is set.
• $is_attribute: Determines if the value should be output as an attribute in the html element

Now, in most cases, we do not want to set the attribute directly, we use helper functions to simplify the setup. And the same goes for the value, in most cases, we want this to be set via the fuse function arguments.

$args->add_default( $key, $value )

Provides a default value for an attribute.

Functions as attributes

Any attribute can be provided in the form of a function that returns a value. The way to do this is by providing a FuseCallable object.

new FuseCallable( $callable )

The FuseCallable will be run when the attribute is output during the rendering of the component. The $callable can be an anonymous function or the name of a function.

Note: FuseCallable was implemented when a value called «next» was passed, and it was interpreted as a reference to the next function. As there are many possible collisions, a separate object was added to handle this scenario.

Inheritance

It is possible for child components to inherit values from its parent. If a value of an attribute is set to ‘inherit’, it will assume the value provided by the parent component. An example of this could be a button component inheriting the post attribute of a card component where the post attribute was provided.

Special attributes

A few attributes are handled slightly differently. Currently, these are style and class. This is because they can take an array and because we often want to combine classes – those provided by the component itself and those provided when initialising the component.

$args->add_default_class( $class )

Appends a default class (string or array) to the list of classes that will be added to the component regardless of the class argument provided by the fuse function.

Adding options

$args->mark_as_option( $key )

Marks an attribute as an option, which means that this won’t be converted to a attribute in the outer html element of the component.

$args->add_option_default( $key, $value )

Provides a default value for an attribute, and marks it as an option, which means that this option won’t be converted to a attribute in the outer html element of the component.

Handeling attributes

There are a number of helper methods for handling attributes.

$args->get( $key )

Retrieves the value of an attribute if available, the default will be returned if none is set and an empty string if no default is provided.

$args->has( $key )

Checks if a value or default value is provided for an attribute.

$args->empty( $key )

Checks if an attribute returns an empty value.

$args->is( $key, $value )

Checks if an attribute returns a value of a specific value

$args->fuse( $component, $key )

Renders a single child based on an a attribute. Passes on the parents attribute to allow components to «inherit» values.

$args->fuse_children( $key )

Renders a list of children based on an attributes. Passes on the parents arguments to allow components to «inherit» values.