Skip to content

Commit e7b8f6d

Browse files
mychidarkomychidarko
committed
feat: add templating docs
1 parent e4abd44 commit e7b8f6d

File tree

3 files changed

+224
-8
lines changed

3 files changed

+224
-8
lines changed

‎src/docs/frontend/bareui.md‎

Lines changed: 2 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,3 @@
1-
---
2-
aside: 'true'
3-
---
4-
51
# BareUI
62

73
<!-- markdownlint-disable no-inline-html -->
@@ -33,11 +29,11 @@ You can install BareUI through the Leaf CLI:
3329

3430
::: code-group
3531

36-
```bash [Leaf CLI]
32+
```bash:no-line-numbers [Leaf CLI]
3733
leaf install bareui
3834
```
3935

40-
```bash [Composer]
36+
```bash:no-line-numbers [Composer]
4137
composer require leafs/bareui
4238
```
4339

‎src/docs/frontend/blade.md‎

Lines changed: 116 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,116 @@
1-
# Leaf Blade
1+
# Leaf + Blade
2+
3+
<!-- markdownlint-disable no-inline-html -->
4+
5+
<script setup>
6+
import VideoModal from '@theme/components/shared/VideoModal.vue'
7+
</script>
8+
9+
Blade is a templating engine included with Laravel that helps you create dynamic views easily. Unlike other templating engines, Blade allows you to use regular PHP code inside your templates together with all the goodness it offers you. Behind the scenes, Blade templates are turned into plain PHP and cached, so they run quickly without slowing down your app. Blade files use the `.blade.php` extension to distinguish them from regular PHP files.
10+
11+
Leaf Blade is a port of the [jenssegers/blade](https://github.com/jenssegers/blade) package that allows you to use blade templates in your Leaf PHP projects.
12+
13+
::: details New to Blade?
14+
15+
This video by The Net Ninja will help you get started with blade.
16+
17+
<VideoModal
18+
title="New to Blade?"
19+
subject="Laravel Tutorial for Beginners #5 - Blade Basics"
20+
description="This video by The Net Ninja will help you get started with blade."
21+
videoUrl="https://www.youtube.com/embed/pQ2vxa4_f2w"
22+
/>
23+
24+
:::
25+
26+
## Setting Up
27+
28+
Blade comes with Leaf MVC out of the box, fully configured and ready to use. However, if you're using Leaf Core, you'll need to set up Blade yourself. Don't worry, it's pretty easy. All you need to do is install Blade, configure it to match your project's setup, and you're good to go.
29+
30+
You can install Leaf Blade with the Leaf CLI:
31+
32+
::: code-group
33+
34+
```bash:no-line-numbers [Leaf CLI]
35+
leaf install blade
36+
```
37+
38+
```bash:no-line-numbers [Composer]
39+
composer require leafs/blade
40+
```
41+
42+
:::
43+
44+
After this, you just need to inform Leaf of Blade's existence:
45+
46+
```php
47+
app()->attachView(Leaf\Blade::class);
48+
```
49+
50+
This will magically set up Blade for you and pop up a `blade()` function you can use to render your Blade views.
51+
52+
```php
53+
app()->blade()->configure([
54+
'views' => 'views',
55+
'cache' => 'storage/cache'
56+
]);
57+
```
58+
59+
Magic! You can now use Blade to create and render your views.
60+
61+
## Creating Blade Views
62+
63+
Blade views are a pretty sweet mixture of HTML, PHP, and clean syntax. You can create a new Blade view by creating a new file with the `.blade.php` extension in your "views" folder. Here's an example of a simple Blade view:
64+
65+
::: code-group
66+
67+
```blade [hello.blade.php]
68+
<!DOCTYPE html>
69+
<html lang="en">
70+
<head>
71+
<meta charset="UTF-8">
72+
<meta http-equiv="X-UA-Compatible" content="IE=edge">
73+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
74+
<title>Document</title>
75+
</head>
76+
<body>
77+
<h1>Hello, {{ $name }}</h1>
78+
</body>
79+
</html>
80+
```
81+
82+
:::
83+
84+
This should look pretty familiar if you know HTML (of course you do). The only difference is the `{{ $name }}` part. This is Blade's way of creating a variable in your view. When you render this view, Blade will allow you pass in a variable called `$name` and it will be displayed in place of `{{ $name }}`. Let's see how you can render this view.
85+
86+
## Rendering Blade Views
87+
88+
Remember we set up Blade earlier? Now we can use it to render our Blade views. Here's how you can render the `hello.blade.php` view we created earlier:
89+
90+
```php
91+
echo app()->blade()->render('hello', ['name' => 'Michael']);
92+
```
93+
94+
This will render the `hello.blade.php` view and pass in a variable called `name` with the value `Michael`. When you open the view in your browser, you should see a big "Hello, Michael" on your screen.
95+
96+
## Extending Blade Views
97+
98+
Blade allows you to define custom directives using the `directive()` method. When the Blade compiler encounters the custom directive, it will call the provided callback with the expression that the directive contains. The callback is free to return the value of its contents however you like:
99+
100+
```php
101+
app()->blade()->directive('datetime', function ($expression) {
102+
return "<?php echo with({$expression})->format('F d, Y g:i a'); ?>";
103+
});
104+
```
105+
106+
Which allows you to use the following in your blade template:
107+
108+
```html
109+
Current date: @datetime($date)
110+
```
111+
112+
This will output the current date in the format `F d, Y g:i a`. You can define as many custom directives as you want to make your Blade views more powerful.
113+
114+
## Conclusion
115+
116+
This is just the beginning of what you can do with Blade. Blade is a powerful templating engine that allows you to create dynamic views with ease. You can use Blade to create complex views with loops, conditions, and even include other views. As this is just an adapter for the original Blade package, you can check out the [Blade documentation](https://laravel.com/docs/8.x/blade) for more information on what you can do with Blade.

‎src/docs/frontend/third-party.md‎

Lines changed: 106 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,106 @@
1-
# Other Templating Engines
1+
# Using third-party Engines
2+
3+
Leaf provides first-class support for [BareUI](/docs/frontend/bareui) and [Blade](/docs/frontend/blade). However, you can use any template engine you want with the framework. In this section, we will show you how to use the [Smarty](https://www.smarty.net/) template engine with Leaf.
4+
5+
## Install your engine
6+
7+
To install Smarty, run the following command in your terminal:
8+
9+
::: code-group
10+
11+
```bash:no-line-numbers [Leaf CLI]
12+
leaf install smarty/smarty
13+
```
14+
15+
```bash:no-line-numbers [Composer]
16+
composer require smarty/smarty
17+
```
18+
19+
:::
20+
21+
Once installed, you need to tell Leaf about your engine. Leaf will try to cache your engine for future use. You can do this using the `attachView()` method on the app instance:
22+
23+
```php
24+
app()->attachView(Smarty::class);
25+
```
26+
27+
This will attach your engine to Leaf and make it available in your app directly from the app instance. Here's how you can use it with our Smarty example:
28+
29+
```php
30+
app()->smarty()->setTemplateDir('/some/template/dir');
31+
app()->smarty()->setConfigDir('/some/config/dir');
32+
app()->smarty()->setCompileDir('/some/compile/dir');
33+
app()->smarty()->setCacheDir('/some/cache/dir');
34+
```
35+
36+
This will configure your engine, basically telling it where to look for templates, configs, compiled files, and cache files. You can now use your engine to render your views:
37+
38+
```php
39+
app()->smarty()->assign('name', 'Michael');
40+
app()->smarty()->display('index.tpl');
41+
```
42+
43+
That's it! Pretty simple, right? You can follow this same pattern to use any other template engine with Leaf.
44+
45+
## Using with Leaf MVC
46+
47+
Unlike Leaf Core, Leaf MVC comes with a view manager that makes Leaf aware of any template engine you want to use. This gives you pretty handy functions like the global `view()` function. To make our Smarty engine available in Leaf MVC, we need to let Leaf know about it and also let Leaf MVC know it's supposed to use it when you call the global `view()` function.
48+
49+
The first step is to head over to your `public/index.php` file and attach Smarty to Leaf:
50+
51+
```php
52+
app()->attachView(Smarty::class);
53+
```
54+
55+
This will immediately make Smarty available in Leaf, but there's one more thing we need to do. We need to let Leaf MVC know that Smarty is the engine we want to use. We can do this by setting the `engine` key in the `config/view.php` file:
56+
57+
```php
58+
<?php
59+
60+
use Leaf\View;
61+
62+
return [
63+
/*
64+
|--------------------------------------------------------------------------
65+
| Template Engine [EXPERIMENTAL]
66+
|--------------------------------------------------------------------------
67+
|
68+
| Leaf MVC unlike other frameworks tries to give you as much control as
69+
| you need. As such, you can decide which view engine to use.
70+
|
71+
*/
72+
'viewEngine' => Smarty::class,
73+
74+
/*
75+
|--------------------------------------------------------------------------
76+
| Custom config method
77+
|--------------------------------------------------------------------------
78+
|
79+
| Configuration for your templating engine.
80+
|
81+
*/
82+
'config' => function ($config) {
83+
app()->smarty()->setTemplateDir($config['views']);
84+
app()->smarty()->setConfigDir('/some/config/dir');
85+
app()->smarty()->setCompileDir('/some/compile/dir');
86+
app()->smarty()->setCacheDir($config['cache']);
87+
},
88+
89+
/*
90+
|--------------------------------------------------------------------------
91+
| Custom render method
92+
|--------------------------------------------------------------------------
93+
|
94+
| This render method is triggered whenever render() is called
95+
| in your app if you're using a custom view engine.
96+
|
97+
*/
98+
'render' => function ($view, $data) {
99+
foreach ($data as $key => $value) {
100+
app()->smarty()->assign($key, $value);
101+
}
102+
103+
app()->smarty()->display($view);
104+
}),
105+
];
106+
```

0 commit comments

Comments
 (0)