Creating Components
Components are one of the core concepts of Leaf UI. They are the foundation upon which you build user interfaces (UI), which makes them the perfect place to start your Leaf UI journey!
You will learn
- What a component is
- What role components play in your Leaf UI
- How to write your first Leaf UI component
Components: UI building blocks
Components are the building blocks of your UI. They are the smallest (or largest) pieces of your UI that can be reused and combined to create more complex UIs. A Leaf UI component basically consists of two things:
- A PHP class that defines the component's behavior
- A template file that defines the component's HTML
Leaf UI uses a component-based approach to building UIs. This means that you build your UI by combining components together. You can think of components as Lego blocks. You can use a single block to build a simple house, or you can combine multiple blocks to build a complex city.
Since Leaf UI follows the component-based approach, every page in your Leaf UI is a component. This means that you can reuse and combine pages to build more complex pages.
Writing your first component
To write your first component, you need to create a new PHP class that extends the Leaf\UI\Component class. This class will define the behavior of your component. We'll start by creating a new component class called HelloWorld:
<?php
use Leaf\UI\Component;
require __DIR__ . '/vendor/autoload.php';
class HelloWorld extends Component
{
//
}
As a class, HelloWorld can have properties and methods, it should also have a key property and a render() method that returns the HTML of the component. The render() method is called by Leaf UI when it needs to render the component's HTML. Let's add a render() method to our HelloWorld component:
<?php
use Leaf\UI\Component;
require __DIR__ . '/vendor/autoload.php';
class HelloWorld extends Component
{
public $key = 'HelloWorld';
public function render()
{
return '<body><span>Hello World!</span></body>';
}
}
Updating Component Keys
You should at no point edit your component's $key property. It should always be unique and should never change after the component's first render. This means that you can update the component's key through props, but you should never update it from within the component itself.
For now, we're just returning a simple string from the render() method. Let's make this component a bit more interesting by adding a name property to it:
<?php
use Leaf\UI\Component;
require __DIR__ . '/vendor/autoload.php';
class HelloWorld extends Component
{
public $name = 'World';
public $key = 'HelloWorld';
public function render()
{
return '<body><span>Hello ' . $this->name . '!</span></body>';
}
}
This component now has a name property that we're setting to 'World' by default. We're also using this property in the render() method to return a personalized greeting. We can make this even more interesting by adding an updateName function to the component. We can then customize the name by calling this function from an onclick event:
<?php
use Leaf\UI\Component;
require __DIR__ . '/vendor/autoload.php';
class HelloWorld extends Component
{
public $name = 'World';
public $key = 'HelloWorld';
public function updateName($name)
{
$this->name = $name;
}
public function render()
{
return '<body><span>Hello {{ $name }}!</span> <button ui-on:click="updateName(Leaf UI)">Update Name</button></body>';
}
}
Separating behavior from presentation
One popular way to build UIs is to separate the behavior of the UI from its presentation. This means that you define the behavior of your UI in a programming language (like PHP) and then use a template language (like HTML) to define the presentation of the UI. Leaf UI follows this approach. This means that you define the behavior of your components in PHP classes and then use template files to define the presentation of your components.
As you can see in the previous example, the HelloWorld component has a render() method that returns the HTML of the component. This is the behavior of the component. The HTML returned by the render() method is the presentation of the component. What we want to do now is to separate the behavior of the component from its presentation. We can do this by moving the HTML returned by the render() method to a template file.
To do this, we need to create a template file called hello-world.html:
<body>
<span>Hello {{ $name }}!</span>
<button ui-on:click="updateName(Leaf UI)">Update Name</button>
</body>
From there, we can register this template file with the HelloWorld component by calling the Core::view() method in the render() method:
<?php
use Leaf\UI;
use Leaf\UI\Component;
require __DIR__ . '/vendor/autoload.php';
class HelloWorld extends Component
{
public $name = 'World';
public $key = 'HelloWorld';
public function updateName($name)
{
$this->name = $name;
}
public function render()
{
return UI::view('hello-world.html');
}
}
Now, the HelloWorld component is using the hello-world.html template file to define its presentation. This means that we can customize the presentation of the component by modifying the hello-world.html template file.
Templating in components
You might have noticed in the example above, we switched from $this->name to when we moved our markup to the template file. This is because in a template file, Leaf allows you directly reference variables and methods set in the component's class.
You can find more information in the template section of the docs.