Laravel Blade – Larry的午茶時光 https://blog.yuyansoftware.com.tw Sun, 23 Jul 2023 03:08:52 +0000 zh-TW hourly 1 https://wordpress.org/?v=6.9.4 https://blog.yuyansoftware.com.tw/wp-content/uploads/2022/10/favicon-45x45.png Laravel Blade – Larry的午茶時光 https://blog.yuyansoftware.com.tw 32 32 Laravel Blade Templates：Components, Slots, and Building Layouts https://blog.yuyansoftware.com.tw/2021/05/laravel-blade-template-component-slot-layout/ Mon, 17 May 2021 14:15:50 +0000 https://blog.yuyansoftware.com.tw/?p=7775 https://laravel.com/docs/8.x/blade

******* 以下文章是基於 Laravel 8 *******

Component & Slot 的概念從 Laravel 5.4 開始就有了，一直演進到目前是 Laravel 8。寫法上觀念上都有很大的改變，也看得出來 Laravel 前端 template 是越來越往 component based 的框架在走。前幾年開始到目前 (2021年5月)，似乎 component based 的前端框架還是主流，這點可以再做觀察。

本篇文章主要是講 Laravel 8 的 Component & Slot。如果基礎 Laravel Blade Templates 還不熟的讀者，可以參考我之前的文章：Laravel Blade Templates：The Basics

首先，Component 分為兩種：class based component 和 anonymous component。簡單來說，class based component 是由一支 Class 檔案搭配一支 view template 檔案。而 anonymous component 則是簡單只有一支 view template 檔案。

Class based component

如上方 Laravel 8 官方文件，要建立一個 class based component，可以下這個指令

php artisan make:component Alert

這個指令會在

  • App\View\Components 新增一支 Class 檔案。
  • resources/views/components 新增一支 view template 檔案。

建立 class based component 時也可以建立檔案結構 (比較好管理) 

php artisan make:component Forms/Input

這個指令會在

  • App\View\Components\Forms 新增一支 Class 檔案。
  • resources/views/components/forms 新增一支 view template 檔案。

調用端如何使用？用 x- 開頭接 component class name，以小寫 dash (-) 分隔的方式

<x-alert/>

<x-user-profile/>

如果 component 是有檔案結構，如上例 Forms/Input，除了小寫 dash (-) 分隔的規則，檔案上下層以 dot (.) 分隔

<x-forms.input/>

Component 如何接收調用端的資料

component class 用 constructor 接收調用端的資料 (下例並非完整，僅用於勾勒出 component 如何接收資料，完整 class 請參考官方文件)

class Alert extends Component
{
    ...

    public function __construct($type, $message)
    {
        $this->type = $type;
        $this->message = $message;
    }

    ...
}

這樣調用端就可以將 type, message 傳進 component。
注意傳 php 變數的屬性前要加 colon (:)

<x-alert type="error" :message="$message"/>

再看一下上方 class Alert。component class 的 view 可以直接使用 component class 的 public 變數，不用特別傳到 view 裡 (跟一般 Laravel controller 不同)。以上方 class Alert 來說，$type, $message 應該是 public 變數，class Alert 的 view 可以直接使用。

Component Attributes

所有不在 component constructor 接收的變數，都會自動存到 component 的 “attribute bag”，其實就是 component 預設的 $attributes 變數。所以如果沒有特別設定 component constructor，想直接顯示調用端所下的屬性，component view 可以這樣寫

<div {{ $attributes }}>
    <!-- Component content -->
</div>

很多時候，component view 本身可以設定 css class，同時也開放調用端下 css，可以使用 $attributes->merge

<div {{ $attributes->merge(['class' => 'alert alert-'.$type]) }}>
    {{ $message }}
</div>

還記得 class Alert，$type 變數是 constructor 接收。如果調用端這樣寫

<x-alert type="error" :message="$message" class="mb-4"/>

上面 $attributes->merge 就會把 class=”alert alert-error” 跟 “mb-4” 合併在一起，最後產出的 html 是

<div class="alert alert-error mb-4">
    <!-- Contents of the $message variable -->
</div>

html 屬性不是只有 css class，其他屬性不見得能下多個值。如果 $attributes->merge 這樣寫

<button {{ $attributes->merge(['type' => 'button']) }}>
    {{ $slot }}
</button>

當調用端 x-button 沒有指定 type，最後產出的 html button type=”button”。
當調用端 x-button 有指定 type，最後產出的 html button type=調用端指定的值。
所以非 css class 的屬性，$attributes->merge 的行為是「覆寫」，而非「合併」

Slot

除了上段討論的 $attributes 變數，component 也預設了 $slot 變數。如果 component view 是

<span class="alert-title">{{ $title }}</span>

<div class="alert alert-danger">
    {{ $slot }}
</div>

調用端 x-alert 中間夾的內容，會自動填到 $slot 變數中。但 component view 還有一個 $title，此時調用端就要新增一個 <x-slot name=”title”>，中間夾的內容會填入 $title (這個地方 title 也是一個 slot)

<x-alert>
    <x-slot name="title">
        Server Error
    </x-slot>

    <strong>Whoops!</strong> Something went wrong!
</x-alert>

slot 可以看成是一個比較快，不需要 component class，又可以將資料傳到 component 的機制。

Anonymous Component

anonymous component 不需要 component class，在 resources/views/components 新增一支 view template 檔案，調用端就可使用了 <x-your-component/>

resources/views/components 可以有檔案結構，調用端檔案上下層以 dot (.) 分隔，例如 <x-forms.input/>，這些都跟 class based component 相同。

因為沒有 component class，還是要有一個機制可以傳入指定變數。anonymous component 使用 @props directive，其中並可指定變數的預設值，例如下面 type 的預設值是 “info”

@props(['type' => 'info', 'message'])

<div {{ $attributes->merge(['class' => 'alert alert-'.$type]) }}>
    {{ $message }}
</div>

使用 Component 做版面 layout

Laravel 演進到現在 (Laravel 8)，其實是鼓勵開發者用 component 做版面 layout，而不是用傳統的 @extends, @yield, @section 等。

用 component 做版面 layout，主要是上面提到的 slot 機制。例如 resources/views/components/layout.blade.php

<html>
    <head>
        <title>{{ $title ?? 'Todo Manager' }}</title>
    </head>
    <body>
        <h1>Todos</h1>
        <hr/>
        {{ $slot }}
    </body>
</html>

child view：resources/views/tasks.blade.php。其中 <x-layout> 中整段會填到 $slot，也注意到 title slot 的寫法，可以傳入 $title 變數。

<x-layout>
    <x-slot name="title">
        Custom Title
    </x-slot>

    @foreach ($tasks as $task)
        {{ $task }}
    @endforeach
</x-layout>

相較於傳統的 @extends, @yield, @section 佈局方式

  • child view 的角色是 component 的調用端
  • master view 的角色是 component 本身

如果對 design pattern 有了解的讀者，傳統的佈局方式跟 component based 的佈局方式，是類似的 design pattern，所以使用上邏輯是很像的。

也可以參考我 Design Pattern 系列的文章

結論

本文主要是希望能勾勒出 Laravel 8 component 的使用，與使用 component 做版面 layout 的方式。沒有談太多細節、或變化型的使用，很多細節的部分應該是由開發者自行斟酌使用。Laravel 前端目前看起來是往 component based 的方向在走，習慣於 @extends, @yield, @section 佈局方式的開發者，可以考慮使用 component。

]]> Laravel Blade Templates：The Basics https://blog.yuyansoftware.com.tw/2016/09/laravel-blade-template-basics/ Fri, 16 Sep 2016 04:38:00 +0000 http://test234.yuyansoftware.com.tw/2016/09/16/laravel-5-blade-template-engine/ https://laravel.com/docs/5.3/blade

******* 以下文章是基於 Laravel 5.3 *******

Laravel Blade 是 Laravel 獨家的 template 引擎。首先我們要知道兩個名詞：master view 與 child view. 可以把每頁相同的部分，例如 <head> 中的部分，放到 master view. 而把每頁實際內容放到 child view. 所以就一般情況而言，多個 child view 會共用一個 master view.

官方文件提供的 master view 範例

<html>
    <head>
        <title>App Name - @yield('title')</title>
    </head>
    <body>
        @section('sidebar')
            This is the master sidebar.
        @show

        <div class="container">
            @yield('content')
        </div>
    </body>
</html>

Extending A Layout

對應的 child view 範例

@extends('layouts.app')

@section('title', 'Page Title')

@section('sidebar')
    @parent

    <p>This is appended to the master sidebar.</p>
@endsection

@section('content')
    <p>This is my body content.</p>
@endsection

要使用 master view, child view 的第一行要填入 @extend. 以上面範例來說，master view 是放在 “resources/views/layouts/app.blade.php”, 所以 @extend 參數填的是 layouts.app.

第二，master view 的 @yield, child view 用 @section 來接。child view 可以用 @section @endsection 塞一個區塊到 master view，或是 @section 參數直接填字串。child view 也可以不實作 @section，在 master view 裡就是留空。

第三，master view 的 @section @show, child view 用 @section @parent 來接。child view 的 @parent 可以「接著 master view 的內容寫」，而不是整段替換。child view 也可以只用 @section, 不寫 @parent, 這樣就是整段替換，與上面第二點同。child view 也可以不實作 @section，在 master view 裡就是顯示 @section @show 中間的內容。其實大部分使用時機，上面第二點都可以取代這個 @section @show.

要注意，概念上是 master view 管版面架構，child view 管文字、表單內容。child view 的 @section 內容會填回 master view, 而不是在 child view @section 的程式碼位置顯示。

Displaying Data

Laravel Blade 用兩個大括號來顯示 PHP 變數 {{ $your_variable }}. 而且他會自動通過 PHP htmlentities function, 防止 XSS 攻擊。例如有人留言 “<script>some malicious code</script>”, PHP htmlentities 會把 < > 等符號轉成 html symbol, 呈現給用戶時仍然是 “<script>some malicious code</script>”. 如果沒用 htmlentities 的話，那一段 script 就會跑起來了。

{!! !!} 「不會」通過 PHP htmlentities function. 使用時要特別小心，一般情況「不應該」使用 {!! !!}. 可能極少數情況，想用 Blade template 執行 html code, 例如 <br> 是換行，而 {{ }} 只是把 “<br>” 當字串顯示。

Blade & JavaScript Frameworks

Blade 使用 {{ }} 填入變數，這跟很多 JavaScript Framework 衝到，例如 Angular, Vue. 可以改用 @{{ }}，這樣 {{ }} 就會 serve 到前端，由前端框架來 templating。如果有一大段 @{{ }}，可以使用：

@verbatim
    Hello, {{ name1 }}, {{ name2 }}
    ...
@endverbatim

這樣其中所有 {{ }} 都會交由前端 templating.

Control Structures

Loop, If 等有 PHP 背景的讀者應該都熟悉，這邊不再贅述。提一下 @php @endphp 可以塞一段 native php 到 blade 檔案。

Including Sub-Views

master view 可以使用 @include 來把部分 html 切分出去，例如：

@include('view.name', ['some' => 'data'])

‘view.name’ 是檔案結構路徑，跟 @extends 參數類似，'view.name’ 是指 /resources/views/view/name.blade.php. 也可以傳參數進去 [‘some’ => ‘data’]

被 include 的檔案 「不需要」extends master view. 如果 master view 有 include 而被 include 的檔案不存在的話，會出現 error. 可以使用 includeIf 如果不確定被 include 的檔案存不存在。

@includeIf('view.name', ['some' => 'data'])

Stacks

@stack and @push. 官方文件說

“This can be particularly useful for specifying any JavaScript libraries required by your child views”

因為 @yield 和 @section 可以完全達成在 child view 中指定該 child view 要用的 JS library，其實不需要 @stack and @push. @stack and @push 唯一獨特的點在於，可以多次 @push, 但就 larry 的經驗來說，使用時機很少。

以上就是 Laravel Blade 主要的架構與語法。其他 Blade 的 service injection, custom directives 等，使用時機很少，讀者可以自行斟酌讀或不讀。

]]>