lyrasoft/banner

Luna Banner package

1.1.0 2024-03-07 05:16 UTC

Requires

• php: >=8.2
• lyrasoft/luna: ^2.0

MIT

• Simon Asika

README

Installation

Install from composer

composer require lyrasoft/banner

Then copy files to project

php windwalker pkg:install lyrasoft/banner -t routes -t lang -t migrations -t seeders

Seeders

• Add contact-seeder.php to resources/seeders/main.php
• Add banner type to category-seeder.php

Languages

If you don't want to copy language files, remove -t lang from install command.

Then add this line to admin & front middleware:

$this->lang->loadAllFromVendor(\Lyrasoft\Banner\BannerPackage::class, 'ini');

Use Type or Category

You have 2 choice to structure banners, use type or category

Type:

Category:

The default will use category mode. If you want to use type mode, you must create a BannerType enum, for example:

class BannerType extends Enum implements EnumTranslatableInterface
{
    use EnumTranslatableTrait;

    #[Title('Home Banner')]
    public const HOME = 'home';

    #[Title('Works')]
    public const WORKS = 'works';

    // ...
}

Then register enum class to config file:

return [
    'banner' => [
        // ...
        
        'type_enum' => \App\Enum\BannerType::class,

        // ...

The package will auto switch to type mode.

Register Admin Menu

Edit resources/menu/admin/sidemenu.menu.php

Ues Type mode:

// Banner
$menu->link('橫幅管理')
    ->to($nav->to('banner_list'))
    ->icon('fal fa-gallery-thumbnails');

Use Category mode:

// Category
$menu->link('橫幅分類')
    ->to($nav->to('category_list', ['type' => 'banner']))
    ->icon('fal fa-sitemap');

// Banner
$menu->link('橫幅管理')
    ->to($nav->to('banner_list'))
    ->icon('fal fa-images');

Add Widget

Add this to packages/widget.php

return [
    'widget' => [
        'types' => [
            // ...
            'banner' => \Lyrasoft\Banner\Widget\Banner\BannerWidget::class
        ],
        // ...
    ]
];

Install Swiper and youtube-background

After packages installed, it will auto reauire swiper as node modules for root package.json.

If you needs use video & Youtbue, you must manually install youtube-background

yarn add youtube-background

• Swiper:
  • Getting Started: https://swiperjs.com/get-started
  • Demo: https://swiperjs.com/demos
• Youtbue Background
  • Github: https://github.com/stamat/youtube-background

Frontend Usage

Use BannerRepository to get banners

$repo = $app->service(BannerRepository::class);

/** @var Banner[] $banners */
$banners = $repo->getBannersByType('home')->all();
$banners = $repo->getBannersByCategoryAlias('category-alias')->all();
$banners = $repo->getBannersByCategoryId(5)->all();

Then use component in Edge:

<x-swiper-banners :banners="$banners"></x-swiper-banners>

You can add some params:

<x-swiper-banners :banners="$banners"
    link-target="_blank"
    :pagination="true"
    height="400px"
></x-swiper-banners>

Parameters

Param Name	Type	Default	Description
banners	Banner[]	null	The banner items, must be a iterable with Banner entity.
category-alias	?string	null	If not provides banner items, component will find banners by this condition.
category-id	string or int	null	If not provides banner items, component will find banners by this condition.
type	string	_default	If not provides banner items, use this type name to find banners & size & ratio settings.
link-target	string	null	The link target, can be _blank
height	string	null	Force banner height, ignore ratio settings.
ratio	float	null	The widrh / height ratio. for example: 16:9 is 1.7778. Leave empty yto let component calc it.
show-text	bool	false	Show banner title / description or not.
options	array	[]	The options for Swiper

Examples

Load by type

<x-swiper-banners :type="$type"
    link-target="_blank"
    :pagination="true"
    height="400px"
></x-swiper-banners>

Load by category alias

<x-swiper-banners :category-alias="$categoryAlias"
    link-target="_blank"
    :pagination="true"
    height="400px"
></x-swiper-banners>

Load by category ID

<x-swiper-banners :category-id="$category->getId()"
    link-target="_blank"
    :pagination="true"
    height="400px"
></x-swiper-banners>

Banner Item Slot

Use item slot with @scope(), you will get Banner entity and index $i.

Then just build you own HTML.

<x-swiper-banners :banners="$banners"
>
    <x-slot name="item">
        @scope($banner, $i)
        
        <div class="c-banner-item"
            style="background-image: url({{ $banner->getImage()) }})">
            <h2>
                {{ $banner->getTitle() }}
            </h2>
        </div>
    </x-slot>
</x-swiper-banners>

Use Banner Item Component

Use can use x-banner-item component, it;s includes default RWD and video switch functions.

<x-swiper-banners :banners="$banners"
>
    <x-slot name="item">
        @scope($banner, $i)
        
        <x-banner-item :banner="$banner">
            <h2>
                {{ $banner->getTitle() }}
            </h2>
        </x-banner-item>
    </x-slot>
</x-swiper-banners>

Parameters:

Param Name	Type	Default	Description
type	string	_default	Use this type name to find size & ratio settings.
banner	Banner	null	The banner item, must be a Banner entity.
link-target	string	null	The link target, can be _blank
height	string	null	Force banner height, ignore ratio settings.
ratio	float	null	The widrh / height ratio. for example: 16:9 is 1.7778. Leave empty yto let component calc it.
show-text	bool	false	Show banner title / description or not.

The Size Settings.

Open etc/packages/banner.php, you will see:

return [
    'banner' => [
        // ...
        
        'types' => [
            '_default' => [
                'desktop' => [
                    'width' => 1920,
                    'height' => 800,
                    'crop' => true,
                    'ajax' => false,
                    'profile' => 'image',
                ],
                'mobile' => [
                    'width' => 720,
                    'height' => 720,
                    'crop' => true,
                    'ajax' => false,
                    'profile' => 'image',
                ]
            ]
        ]
    ]
];

The _default type has 2 sizes settings, desktop and mobile, this means admin upload images will use this size:

You can change all uploading settings here.

Custom Size for Type or Category Alias

If you have a category with alias (promote), you can add a promote size settings with different size.

return [
    'banner' => [
        // ...
        'types' => [
            '_default' => [
                // ...
            ],
            'promote' => [
                'desktop' => [
                    'width' => 800,
                    'height' => 400,
                    'crop' => true,
                    'ajax' => false,
                    'profile' => 'image',
                ],
                'mobile' => [
                    'width' => 200,
                    'height' => 200,
                    'crop' => true,
                    'ajax' => false,
                    'profile' => 'image',
                ]
            ],
        ]
    ]
];

Make sure your category alias is same:

Then the banners in this category will use the new size:

Create Default Categories/Type

If you use Category mode, you may want to create some default categories in migration:

$catMapper = $orm->mapper(Category::class);
$catMapper->createOne(
    [
        'title' => '首頁作品',
        'alias' => 'works',
        'parent_id' => 1
    ]
);

If you use Type mode, just change the BannerType enum cases:

BannerScript

Directly use Swiper or Youtube Background

use Lyrasoft\Banner\Script\BannerScript;

$app->service(BannerScript::class)->swiper('#swiper', $options);

$app->service(BannerScript::class)->youtubeBackground();

Widget

If you ever added BannerWidget::class to widget.php, you'll see this widget in admin:

After you added this widget and save. Use this code to render position, for example (demo position):

<?php
$widgetService = $app->service(WidgetService::class);
?>
@if ($widgetService->hasWidgets('demo'))
    <div class="l-demo-position">
        @foreach ($widgetService->loadWidgets('demo') as $widget)
        <div class="l-demo-position__widget mb-3">
            <x-widget :widget="$widget"></x-widget>
        </div>
        @endforeach
    </div>
@endif