Laravel Nova를 위한 쉽고 완벽한 플렉서블 필드입니다. 반복적이고 유연한 필드 그룹에 적합합니다.

빠른 시작

여기에 최대한 빨리 시작할 수 있도록 간략한 가이드를 제공합니다. 전체 문서는 https://whitecube.github.io/nova-flexible-content에서 확인하세요.

설치

composer require whitecube/nova-flexible-content

사용법

플렉서블 필드는 반복 가능하고 순서를 지정할 수 있는 필드 그룹을 쉽게 관리할 수 있게 해줍니다. Laravel Nova의 기존 몇 가지 솔루션과 달리, 이 필드는 그룹 내에서 사용할 수 있는 필드에 제약이 없습니다. 즉, 모든 Laravel Nova 필드 유형과 커뮤니티에서 만든 필드를 사용할 수 있습니다.

레이아웃 추가

레이아웃은 플렉서블 필드 내에서 반복될 수 있는 필드 그룹을 나타냅니다. 원하는 만큼 많은 레이아웃을 추가할 수 있습니다. 단 하나의 레이아웃만 정의하면 필드는 간단한 리피터처럼 동작하며, 더 많은 레이아웃을 추가하면 플렉서블 콘텐츠가 됩니다. 이 두 개념은 WordPress ACF 플러그인의 cousin과 유사합니다.

레이아웃은 Flexible 필드에서 다음 메서드를 사용하여 추가할 수 있습니다:

 addLayout(string $title, string $name, array $fields)

$name 매개변수는 필드 값에서 선택한 레이아웃을 저장하는 데 사용됩니다. 현명하게 선택하세요. 애플리케이션에서 레이아웃을 식별하는 데 사용할 것입니다.

use Whitecube\NovaFlexibleContent\Flexible;

/**
 * Get the fields displayed by the resource.
 *
 * @param  \Illuminate\Http\Request  $request
 * @return array
 */
public function fields(Request $request)
{
    return [
        // ...

        Flexible::make('Content')
            ->addLayout('Simple content section', 'wysiwyg', [
                Text::make('Title'),
                Markdown::make('Content')
            ])
            ->addLayout('Video section', 'video', [
                Text::make('Title'),
                Image::make('Video Thumbnail', 'thumbnail'),
                Text::make('Video ID (YouTube)', 'video'),
                Text::make('Video Caption', 'caption')
            ])
    ];
}

버튼 레이블 사용자 정의

다음과 같이 기본 '레이아웃 추가' 버튼의 텍스트를 변경할 수 있습니다:

Flexible::make('Content')
    ->button('Add something amazing!');

뷰에서 플렉서블 값 사용하기

Laravel 6 이하를 사용하거나 캐스트를 사용하고 싶지 않다면, HasFlexible 트레이트를 사용하여 모델에 접근자를 사용하세요.

Laravel 7에서는 사용자 정의 캐스트가 도입되었으며, 플렉서블 콘텐츠 필드는 이에 완벽한 사용 사례입니다. 필드는 값을 단일 JSON 문자열로 저장하므로, 애플리케이션에서 사용하기 전에 이 문자열을 파싱해야 합니다. 이 작업은 이 패키지의 FlexibleCast 클래스를 사용하여 간단히 수행할 수 있습니다:

namespace App;

use Illuminate\Database\Eloquent\Model;
use Whitecube\NovaFlexibleContent\Value\FlexibleCast;

class MyModel extends Model
{
    protected $casts = [
        'flexible-content' => FlexibleCast::class
    ];
}

기본적으로 FlexibleCast 클래스는 기본 Layout 인스턴스를 수집합니다. 레이아웃을 사용자 정의 레이아웃 인스턴스로 매핑하려는 경우에도 가능합니다. 먼저 php artisan flexible:cast MyFlexibleCast를 실행하여 사용자 정의 플렉서블 캐스트를 생성합니다. 그러면 App\Casts 디렉토리에 파일이 생성됩니다.

그런 다음 사용자 정의 레이아웃 클래스를 적절한 키에 쉽게 매핑할 수 있습니다:

namespace App\Casts;

class MyFlexibleCast extends FlexibleCast
{
    protected $layouts = [
        'wysiwyg' => \App\Nova\Flexible\Layouts\WysiwygLayout::class,
        'video' => \App\Nova\Flexible\Layouts\VideoLayout::class,
    ]
}

더 많은 제어가 필요하다면, 대신 getLayoutMappings 메서드를 재정의할 수 있습니다.

레이아웃 컬렉션

FlexibleCast 캐스트와 HasFlexible 트레이트가 반환하는 컬렉션은 원래의 Illuminate\Support\Collection을 확장합니다. 이 사용자 정의 레이아웃 컬렉션은 find(string $name) 메서드를 노출하며, 주어진 레이아웃 $name을 가진 첫 번째 레이아웃을 반환합니다.

레이아웃 인스턴스

레이아웃은 일종의 _가짜 모델_입니다. Laravel의 HasAttributes 트레이트를 사용하므로 레이아웃 속성에 대한 접근자 및 변경자를 정의할 수 있습니다. 또한 다음 메서드를 사용하여 레이아웃의 속성에 접근할 수 있습니다:

name()

레이아웃의 이름을 반환합니다.

title()

레이아웃의 제목(Nova에 표시된 대로)을 반환합니다.

key()

레이아웃의 고유 키(레이아웃의 고유 식별자)를 반환합니다.

더 나아가기

플렉서블 콘텐츠 필드를 사용하다 보면 위에서 설명한 기본 기능만으로는 부족한 사용 사례를 빠르게 만나게 됩니다. 그래서 우리는 이 패키지를 확장 가능한 방식으로 개발하여, 필드와 그 출력에 사용자 정의 동작 및/또는 기능을 쉽게 추가할 수 있도록 했습니다.

사용자 정의 레이아웃 클래스

때로는 addLayout 정의가 상당히 길어지거나 다른 Flexible 필드와 공유하고 싶을 수 있습니다. 이에 대한 해결책은 레이아웃을 자체 클래스로 추출하는 것입니다. 자세한 내용은 문서를 참조하세요.

미리 정의된 프리셋 클래스

재사용 가능한 레이아웃 클래스 외에도 한 단계 더 나아가 Flexible 필드에 대한 Preset 클래스를 만들 수 있습니다. 이를 통해 전체 Flexible 필드를 원하는 곳 어디에서나 재사용할 수 있습니다. 또한 조건부로 레이아웃을 추가하는 등 Flexible 필드를 동적으로 만들기도 더 쉬워집니다. 마지막으로, Flexible 필드에 많은 addLayout 정의가 있는 경우 Nova 리소스 클래스를 정리하는 추가 이점도 있습니다. 자세한 내용은 문서를 참조하세요.

사용자 정의 리졸버 클래스

기본적으로 필드는 모델 테이블의 JSON 열을 활용합니다. 어떤 경우에는 이 필드를 사용하고 싶지만 어떤 이유로 JSON 속성이 적합하지 않을 수 있습니다. 예를 들어, 다른 테이블에 값을 저장하고 싶을 수 있습니다(이는 기존의 BelongsToMany 또는 HasMany 필드 대신 Flexible Content 필드를 사용한다는 의미입니다). 걱정하지 마세요, 저희가 해결해 드립니다!

자체 Resolver 클래스를 생성하여 필드에 콘텐츠를 저장하고 검색하는 방법을 알려주세요. 기본적으로 get과 set이라는 두 가지 간단한 메서드만 포함됩니다. 자세한 내용은 문서를 참조하세요.

nova-page와 함께 사용하기

저희의 다른 패키지 중 하나인 nova-page를 들어보셨을 수도 있습니다. 이는 "About" 페이지(또는 유사한)와 같은 정적 페이지를 개별적으로 모델을 선언하지 않고 편집할 수 있는 Nova 도구입니다. 대부분의 경우 Flexible Content 필드가 유용하게 사용됩니다. 걱정하지 마세요, 두 패키지는 잘 작동합니다! 먼저 nova page 템플릿을 생성하고 템플릿의 필드에 flexible content를 추가하세요.

문서에 설명된 대로, 블레이드 뷰에서 {{ Page::get('attribute') }}를 사용하여 nova-page의 정적 콘텐츠에 접근할 수 있습니다. 이렇게 플렉서블 콘텐츠를 요청하면 플렉서블 콘텐츠를 설명하는 원시 JSON 문자열이 반환되며, 이는 물론 그다지 유용하지 않습니다. 대신 페이지 템플릿에 Whitecube\NovaFlexibleContent\Concerns\HasFlexible 트레이트를 구현하면 Page::flexible('attribute') 파사드 메서드가 노출되어 플렉서블 콘텐츠의 변환을 처리합니다.

namespace App\Nova\Templates;

// ...
use Whitecube\NovaFlexibleContent\Concerns\HasFlexible;

class Home extends Template
{
    use HasFlexible;

    // ...
}

💖 스폰서십

프로덕션 애플리케이션에서 이 패키지에 의존하고 있다면, 스폰서가 되어 주시기 바랍니다! 저희가 사랑하는 일인 훌륭한 오픈 소스 소프트웨어를 계속 만들 수 있도록 도와주는 최고의 방법입니다.

기여하기

변경 사항을 제안하거나, 새로운 기능을 요청하거나, 직접 버그를 수정해 주세요. 아직 개선할 점이 많이 남아 있다고 확신하며, 유용한 풀 리퀘스트를 병합하게 되어 매우 기쁠 것입니다.

감사합니다!

단위 테스트

새로운 기능을 추가하거나 버그를 수정할 때는 해당하는 단위 테스트를 추가해 주세요. 현재 테스트 세트는 제한적이지만, 추가되는 모든 단위 테스트는 패키지의 품질을 향상시킬 것입니다.

composer test를 호출하여 PHPUnit을 실행하세요.

❤️로 만든 오픈 소스

Whitecube에서는 일상 작업의 일부로 많은 오픈 소스 소프트웨어를 사용합니다. 그래서 무언가를 환원할 기회가 있을 때 매우 기쁩니다!

이 작은 기여를 즐기시길 바라며, 프로젝트에서 유용하게 사용하신다면 의견을 보내주시기 바랍니다. 더 많은 업데이트는 Twitter에서 팔로우해 주세요!