Skip to content

Commit 703f0c1

Browse files
mychidarkomychidarko
committed
feat: add directives docs
1 parent fb31ec7 commit 703f0c1

File tree

1 file changed

+252
-18
lines changed

1 file changed

+252
-18
lines changed

‎src/docs/frontend/blade.md‎

Lines changed: 252 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,9 @@
66
import VideoModal from '@theme/components/shared/VideoModal.vue'
77
</script>
88

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.
9+
Blade is Laravel's own templating engine that makes creating dynamic views easy. It lets you mix regular PHP code with its own features for more flexibility, has a clean syntax and caches your views for faster performance.
1010

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.
11+
Leaf Blade is an adaptation of the original Blade package that allows you to use Blade templates in your Leaf PHP projects powered by [jenssegers/blade](https://github.com/jenssegers/blade).
1212

1313
<!-- Leaf Blade is an adaptation of the original Blade package, which provides a powerful engine that is familiar to most PHP developers. While similar, Leaf Blade has some differences from the original Blade package, so be sure to keep this documentation handy. -->
1414

@@ -27,13 +27,7 @@ This video by The Net Ninja will help you get started with blade.
2727

2828
## Setting Up
2929

30-
::: info Blade + Leaf MVC
31-
32-
Blade comes with Leaf MVC out of the box, fully configured and ready to use, so you can skip this section if you're using Leaf MVC.
33-
34-
:::
35-
36-
You can install Leaf Blade using the Leaf CLI:
30+
Blade comes with Leaf MVC out of the box, fully configured and ready to use, however, if you're using Leaf on its own, you can install Blade using the Leaf CLI or Composer.
3731

3832
::: code-group
3933

@@ -47,7 +41,9 @@ composer require leafs/blade
4741

4842
:::
4943

50-
After this, you just need to inform Leaf of Blade's existence:
44+
::: details Configuring your paths
45+
46+
After installing Blade in your Leaf app, you just need to inform Leaf of Blade's existence:
5147

5248
```php:no-line-numbers
5349
app()->attachView(Leaf\Blade::class);
@@ -62,6 +58,10 @@ app()->blade()->configure([
6258
]);
6359
```
6460

61+
Once again, this is only necessary if you're using Leaf on its own. If you're using Leaf MVC, Blade is already set up for you.
62+
63+
:::
64+
6565
Magic! You can now use Blade to create and render your views.
6666

6767
## Creating Blade Views
@@ -99,11 +99,13 @@ echo app()->blade()->render('hello', ['name' => 'Michael']);
9999

100100
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.
101101

102-
<!-- ## Directives included in Leaf Blade
102+
## Directives included in Leaf Blade
103+
104+
Although Leaf Blade is just an adaptation of the original Blade package, it comes pre-packaged with some original Blade directives remodelled to work with Leaf and a few custom directives to make your life easier. You can find all common Blade directives in the [Blade documentation](https://laravel.com/docs/8.x/blade).
103105

104-
As mentioned earlier, Leaf Blade is an adaptation of the original Blade package, so it includes some directives that are not available in the original Blade package. Here are some of the directives included in Leaf Blade:
106+
Here are some of the directives you can use in your Blade views:
105107

106-
### `@csrf`
108+
### CSRF protection
107109

108110
The `@csrf` directive generates a hidden CSRF token field for forms. This is useful when you want to include a CSRF token in your form.
109111

@@ -114,7 +116,239 @@ The `@csrf` directive generates a hidden CSRF token field for forms. This is use
114116
</form>
115117
```
116118

117-
### `@method`
119+
### Working with JSON
120+
121+
You can use the `@json` directive to convert a PHP array to a JSON string. This is useful when you want to pass a JSON string to a JavaScript variable.
122+
123+
```blade:no-line-numbers
124+
<script>
125+
var app = @json($array);
126+
</script>
127+
```
128+
129+
### Loading assets with vite
130+
131+
You can use the `@vite` directive to load assets like CSS and JS files in your Blade views using Vite.
132+
133+
```blade:no-line-numbers
134+
@vite('app.js')
135+
@vite(['app.js', 'app.css'])
136+
```
137+
138+
### Adding Alpine.js
139+
140+
Alpine.js is a minimal framework for composing JavaScript behavior in your views. You can use the `@alpine` directive to add Alpine.js to your Blade views.
141+
142+
```blade:no-line-numbers
143+
<head>
144+
...
145+
146+
@alpine
147+
</head>
148+
```
149+
150+
### Checking for null
151+
152+
You can use the `@isNull` directive to check if a variable is null.
153+
154+
```blade
155+
@isNull($variable)
156+
<p>This will only show if $variable is null</p>
157+
@else
158+
<p>This will show if $variable is not null</p>
159+
@endisNull
160+
```
161+
162+
### Conditional rendering with env
163+
164+
You can use the `@env` directive to conditionally render content based on the environment.
165+
166+
```blade
167+
@env('local')
168+
<p>This will only show in the local environment</p>
169+
@else
170+
<p>This will show in all other environments</p>
171+
@endenv
172+
```
173+
174+
### Working with sessions
175+
176+
The `@session` directive may be used to determine if a session value exists. If the session value exists, the template contents within the `@session` and `@endsession` directives will be evaluated. Within the `@session` directive's contents, you may echo the `$value` variable to display the session value:
177+
178+
```blade
179+
@session('status')
180+
<div class="p-4 bg-green-100">
181+
{{ $value }}
182+
</div>
183+
@endsession
184+
```
185+
186+
### Working with flash messages
187+
188+
The `@flash` directive may be used to determine if a flash message exists. If the flash message exists, the template contents within the `@flash` and `@endflash` directives will be evaluated. Within the `@flash` directive's contents, you may echo the `$message` variable to display the flash message:
189+
190+
```blade
191+
@flash('status')
192+
<div class="p-4 bg-green-100">
193+
{{ $message }}
194+
</div>
195+
@endflash
196+
```
197+
198+
### Conditional Classes & Styles
199+
200+
The `@class` directive conditionally compiles a CSS class string. The directive accepts an array of classes where the array key contains the class or classes you wish to add, while the value is a boolean expression. If the array element has a numeric key, it will always be included in the rendered class list:
201+
202+
```blade
203+
@php
204+
$isActive = false;
205+
$hasError = true;
206+
@endphp
207+
208+
<span @class([
209+
'p-4',
210+
'font-bold' => $isActive,
211+
'text-gray-500' => ! $isActive,
212+
'bg-red' => $hasError,
213+
])></span>
214+
215+
OUTPUT: <span class="p-4 text-gray-500 bg-red"></span>
216+
```
217+
218+
Likewise, the @style directive may be used to conditionally add inline CSS styles to an HTML element:
219+
220+
```blade
221+
@php
222+
$isActive = true;
223+
@endphp
224+
225+
<span @style([
226+
'background-color: red',
227+
'font-weight: bold' => $isActive,
228+
])></span>
229+
230+
OUTPUT: <span style="background-color: red; font-weight: bold;"></span>
231+
```
232+
233+
### Additional Attributes
234+
235+
For convenience, you may use the @checked directive to easily indicate if a given HTML checkbox input is "checked". This directive will echo checked if the provided condition evaluates to true:
236+
237+
```blade
238+
<input
239+
type="checkbox"
240+
name="active"
241+
value="active"
242+
@checked($isActive)
243+
/>
244+
```
245+
246+
Likewise, the @selected directive may be used to indicate if a given select option should be "selected":
247+
248+
```blade
249+
<select name="version">
250+
@foreach ($product->versions as $version)
251+
<option ... @selected($shouldBeSelected)>
252+
...
253+
</option>
254+
@endforeach
255+
</select>
256+
```
257+
258+
Additionally, the @disabled directive may be used to indicate if a given element should be "disabled":
259+
260+
```blade
261+
<button type="submit" @disabled($shouldBeDisabled)>Submit</button>
262+
```
263+
264+
Moreover, the @readonly directive may be used to indicate if a given element should be "readonly":
265+
266+
```blade
267+
<input
268+
type="email"
269+
name="email"
270+
value="[email protected]"
271+
@readonly($shouldBeReadonly)
272+
/>
273+
```
274+
275+
In addition, the @required directive may be used to indicate if a given element should be "required":
276+
277+
```blade
278+
<input
279+
type="text"
280+
name="title"
281+
value="title"
282+
@required($shouldBeRequired)
283+
/>
284+
```
285+
286+
### Leaf Auth
287+
288+
The `@auth` and `@guest` directives may be used to quickly determine if the current user is authenticated or is a guest:
289+
290+
```blade
291+
@auth
292+
// The user is authenticated...
293+
@endauth
294+
295+
@guest
296+
// The user is not authenticated...
297+
@endguest
298+
```
299+
300+
### Roles & Permissions
301+
302+
You can use the `@is` directive to check if the current user has a specific role:
303+
304+
```blade
305+
@is('admin')
306+
// The user has the admin role...
307+
@else
308+
// The user does not have the admin role...
309+
@endis
310+
```
311+
312+
You can also use the `@can` directive to check if the current user has a specific permission:
313+
314+
```blade
315+
@can('edit articles')
316+
// The user can edit articles...
317+
@else
318+
// The user cannot edit articles...
319+
@endcan
320+
```
321+
322+
<!-- ### SEO Meta Tags
323+
324+
You can use the `@Meta` directive to add SEO meta tags to your Blade views.
325+
326+
```blade:no-line-numbers
327+
@Meta([
328+
'title' => 'My Page',
329+
'description' => 'This is my page',
330+
'keywords' => 'page, my',
331+
'author' => 'Michael',
332+
'robots' => 'index, follow',
333+
'canonical' => 'https://example.com/page',
334+
'image' => 'https://example.com/image.jpg',
335+
'og' => [
336+
'title' => 'My Page',
337+
'description' => 'This is my page',
338+
'image' => 'https://example.com/image.jpg',
339+
'url' => 'https://example.com/page',
340+
'type' => 'website'
341+
],
342+
'twitter' => [
343+
'title' => 'My Page',
344+
'description' => 'This is my page',
345+
'image' => 'https://example.com/image.jpg',
346+
'card' => 'summary_large_image'
347+
]
348+
])
349+
``` -->
350+
351+
<!-- ### `@method`
118352
119353
The `@method` directive generates a hidden input field with the value of the method you specify. This is useful when you want to use methods other than `GET` and `POST` in your forms.
120354
@@ -128,13 +362,13 @@ The `@method` directive generates a hidden input field with the value of the met
128362
@method('DELETE')
129363
...
130364
</form>
131-
```
365+
````
132366
133367
### `@submit`
134368
135369
The `@submit` directive allows you to wrap an item with a form that submits when the item is clicked. This is useful when you want to redirect to a post route when an item is clicked.
136370
137-
```blade:no-line-numbers
371+
````blade:no-line-numbers
138372
@submit('DELETE', '/posts/1')
139373
<button>Delete</button>
140374
@endsubmit
@@ -146,9 +380,9 @@ Blade allows you to define custom directives using the `directive()` method. Whe
146380

147381
```php
148382
app()->blade()->directive('datetime', function ($expression) {
149-
return "<?php echo with({$expression})->format('F d, Y g:i a'); ?>";
383+
return "<?php echo tick({$expression})->format('F d, Y g:i a'); ?>";
150384
});
151-
```
385+
````
152386

153387
Which allows you to use the following in your blade template:
154388

0 commit comments

Comments
 (0)