ordello/teeplus

Teeplus for Ordello, via Laravel 5.5

Theme Management for Laravel

For Laravel 4, please use the v1.x branch!

Theme is a theme management for Laravel 5, it is the easiest way to organize your skins, layouts and assets. Right now Theme supports PHP, Blade, and Twig., _(*1)

Installation

• Theme on Packagist
• Theme on GitHub

To get the latest version of Theme simply require it in your composer.json file., _(*2)

"teepluss/theme": "^2.0"

You'll then need to run composer install to download it and have the autoloader updated., _(*3)

Once Theme is installed you need to register the service provider with the application. Open up config/app.php and find the providers key., _(*4)

'providers' => [

    Teepluss\Theme\ThemeServiceProvider::class,

]

Theme also ships with a facade which provides the static syntax for creating collections. You can register the facade in the aliases key of your config/app.php file., _(*5)

'aliases' => [

    'Theme' => Teepluss\Theme\Facades\Theme::class,

]

Publish config using artisan CLI., _(*6)

php artisan vendor:publish --provider="Teepluss\Theme\ThemeServiceProvider"

Usage

Theme has many features to help you get started with Laravel, _(*7)

• Create theme with artisan CLI
• Configuration
• Basic usage
• Compiler
• Render from string
• Compile string
• Symlink from another view
• Basic usage of assets
• Preparing group of assets
• Partials
• Working with regions
• Preparing data to view
• Breadcrumb
• Widgets design structure
• Using theme global

Create theme with artisan CLI

The first time you have to create theme "default" structure, using the artisan command:, _(*8)

php artisan theme:create default

If you change the facade name you can add an option --facade="Alias"., _(*9)

To delete an existing theme, use the command:, _(*10)

php artisan theme:destroy default

the type can be php, blade and twig., _(*11)

Create from the applicaton without CLI., _(*12)

Artisan::call('theme:create', ['name' => 'foo', '--type' => 'blade']);

Configuration

After the config is published, you will see the config file in "config/theme", but all the configuration can be replaced by a config file inside a theme., _(*13)

Theme config location: /public/themes/[theme]/config.php, _(*14)

The config is convenient for setting up basic CSS/JS, partial composer, breadcrumb template and also metas., _(*15)

Example:, _(*16)

'events' => array(

    // Before event inherit from package config and the theme that call before,
    // you can use this event to set meta, breadcrumb template or anything
    // you want inheriting.
    'before' => function($theme)
    {
        // You can remove this line anytime.
        $theme->setTitle('Copyright ©  2013 - Laravel.in.th');

        // Breadcrumb template.
        // $theme->breadcrumb()->setTemplate('
        //     <ul class="breadcrumb">
        //     @foreach ($crumbs as $i => $crumb)
        //         @if ($i != (count($crumbs) - 1))
        //         <li><a href="{{ $crumb["url"] }}">{{ $crumb["label"] }}</a><span class="divider">/</span></li>
        //         @else
        //         <li class="active">{{ $crumb["label"] }}</li>
        //         @endif
        //     @endforeach
        //     </ul>
        // ');
    },

    // Listen on event before render a theme,
    // this event should call to assign some assets,
    // breadcrumb template.
    'beforeRenderTheme' => function($theme)
    {
        // You may use this event to set up your assets.
        // $theme->asset()->usePath()->add('core', 'core.js');
        // $theme->asset()->add('jquery', 'vendor/jquery/jquery.min.js');
        // $theme->asset()->add('jquery-ui', 'vendor/jqueryui/jquery-ui.min.js', array('jquery'));


        // $theme->partialComposer('header', function($view)
        // {
        //     $view->with('auth', Auth::user());
        // });
    },

    // Listen on event before render a layout,
    // this should call to assign style, script for a layout.
    'beforeRenderLayout' => array(

        'default' => function($theme)
        {
            // $theme->asset()->usePath()->add('ipad', 'css/layouts/ipad.css');
        }

    )

)

Basic usage

namespace App\Http\Controllers;

use Theme;

class HomeController extends Controller {

    public function getIndex()
    {
        $theme = Theme::uses('default')->layout('mobile');

        $view = array(
            'name' => 'Teepluss'
        );

        // home.index will look up the path 'resources/views/home/index.php'
        return $theme->of('home.index', $view)->render();

        // Specific status code with render.
        return $theme->of('home.index', $view)->render(200);

        // home.index will look up the path 'resources/views/mobile/home/index.php'
        return $theme->ofWithLayout('home.index', $view)->render();

        // home.index will look up the path 'public/themes/default/views/home/index.php'
        return $theme->scope('home.index', $view)->render();

        // home.index will look up the path 'public/themes/default/views/mobile/home/index.php'
        return $theme->scopeWithLayout('home.index', $view)->render();

        // Looking for a custom path.
        return $theme->load('app.somewhere.viewfile', $view)->render();

        // Working with cookie.
        $cookie = Cookie::make('name', 'Tee');
        return $theme->of('home.index', $view)->withCookie($cookie)->render();
    }

}

Get only content "$theme->of('home.index')->content();"., _(*17)

Finding from both theme's view and application's view., _(*18)

$theme = Theme::uses('default')->layout('default');

return $theme->watch('home.index')->render();

To check whether a theme exists., _(*19)

// Returns boolean.
Theme::exists('themename');

To find the location of a view., _(*20)

$which = $theme->scope('home.index')->location();

echo $which; // themer::views.home.index

$which = $theme->scope('home.index')->location(true);

echo $which; // ./public/themes/name/views/home/index.blade.php

Compiler

Theme now supports PHP, Blade and Twig. To use Blade or Twig template you just create a file with extension, _(*21)

[file].blade.php or [file].twig.php

Render from string.

// Blade template.
return $theme->string('

{{ $name }}

', array('name' => 'Teepluss'), 'blade')->render();

// Twig Template
return $theme->string('

{{ name }}

', array('name' => 'Teepluss'), 'twig')->render();

Compile string

// Blade compile.
$template = '<h1>Name: {{ $name }}</h1><p>{{ Theme::widget("WidgetIntro", array("userId" => 9999, "title" => "Demo Widget"))->render() }}</p>';

echo Theme::blader($template, array('name' => 'Teepluss'));

// Twig compile.
$template = '

Name: {{ name }}



{{ Theme.widget("WidgetIntro", {"userId" : 9999, "title" : "Demo Widget"}).render() }}, (*22)

';

echo Theme::twigy($template, array('name' => 'Teepluss'));

Symlink from another view

This is a nice feature when you have multiple files that have the same name, but need to be located as a separate one., _(*23)

// Theme A : /public/themes/a/views/welcome.blade.php

// Theme B : /public/themes/b/views/welcome.blade.php

// File welcome.blade.php at Theme B is the same as Theme A, so you can do link below:

// ................

// Location: public/themes/b/views/welcome.blade.php
Theme::symlink('a');

// That's it!

Basic usage of assets

Add assets in your route., _(*24)

// path: public/css/style.css
$theme->asset()->add('core-style', 'css/style.css');

// path: public/js/script.css
$theme->asset()->container('footer')->add('core-script', 'js/script.js');

// path: public/themes/[current theme]/assets/css/custom.css
// This case has dependency with "core-style".
$theme->asset()->usePath()->add('custom', 'css/custom.css', array('core-style'));

// path: public/themes/[current theme]/assets/js/custom.js
// This case has dependency with "core-script".
$theme->asset()->container('footer')->usePath()->add('custom', 'js/custom.js', array('core-script'));

You can force use theme to look up existing theme by passing parameter to method: $theme->asset()->usePath('default'), _(*25)

Writing in-line style or script., _(*26)

// Dependency with.
$dependencies = array();

// Writing an in-line script.
$theme->asset()->writeScript('inline-script', '
    $(function() {
        console.log("Running");
    })
', $dependencies);

// Writing an in-line style.
$theme->asset()->writeStyle('inline-style', '
    h1 { font-size: 0.9em; }
', $dependencies);

// Writing an in-line script, style without tag wrapper.
$theme->asset()->writeContent('custom-inline-script', '
    <script>
        $(function() {
            console.log("Running");
        });
    </script>
', $dependencies);

Render styles and scripts in your layout., _(*27)

// Without container
echo Theme::asset()->styles();

// With "footer" container
echo Theme::asset()->container('footer')->scripts();

Direct path to theme asset., _(*28)

echo Theme::asset()->url('img/image.png');

Preparing group of assets.

Some assets you don't want to add on a page right now, but you still need them sometimes, so "cook" and "serve" is your magic., _(*29)

Cook your assets., _(*30)

Theme::asset()->cook('backbone', function($asset)
{
    $asset->add('backbone', '//cdnjs.cloudflare.com/ajax/libs/backbone.js/1.0.0/backbone-min.js');
    $asset->add('underscorejs', '//cdnjs.cloudflare.com/ajax/libs/underscore.js/1.4.4/underscore-min.js');
});

You can prepare on a global in package config., _(*31)

// Location: config/theme/config.php
....
    'events' => array(

        ....

        // This event will fire as a global you can add any assets you want here.
        'asset' => function($asset)
        {
            // Preparing asset you need to serve after.
            $asset->cook('backbone', function($asset)
            {
                $asset->add('backbone', '//cdnjs.cloudflare.com/ajax/libs/backbone.js/1.0.0/backbone-min.js');
                $asset->add('underscorejs', '//cdnjs.cloudflare.com/ajax/libs/underscore.js/1.4.4/underscore-min.js');
            });
        }

    )
....

Serve theme when you need., _(*32)

// At the controller.
Theme::asset()->serve('backbone');

Then you can get output., _(*33)

...
<head>
    <?php echo Theme::asset()->scripts(); ?>
    <?php echo Theme::asset()->styles(); ?>
    <?php echo Theme::asset()->container('YOUR_CONTAINER')->scripts(); ?>
    <?php echo Theme::asset()->container('YOUR_CONTAINER')->styles(); ?>
</head>
...

Partials

Render a partial in your layouts or views., _(*34)

// This will look up to "public/themes/[theme]/partials/header.php"
echo Theme::partial('header', array('title' => 'Header'));

// Partial with current layout specific.
// This will look up up to "public/themes/[theme]/partials/[CURRENT_LAYOUT]/header.php"
echo Theme::partialWithLayout('header', array('title' => 'Header'));

Finding from both theme's partial and application's partials., _(*35)

echo Theme::watchPartial('header', array('title' => 'Header'));

Partial composer., _(*36)

$theme->partialComposer('header', function($view)
{
    $view->with('key', 'value');
});

// Working with partialWithLayout.
$theme->partialComposer('header', function($view)
{
    $view->with('key', 'value');
}, 'layout-name');

Working with regions.

Theme has magic methods to set, prepend and append anything., _(*37)

$theme->setTitle('Your title');

$theme->appendTitle('Your appended title');

$theme->prependTitle('Hello: ....');

$theme->setAnything('anything');

$theme->setFoo('foo');

// or

$theme->set('foo', 'foo');

Render in your layout or view., _(*38)

Theme::getAnything();

Theme::getFoo();

// or use place.

Theme::place('anything');

Theme::place('foo', 'default-value-if-it-does-not-exist');

// or

Theme::get('foo');

Check if the place exists or not., _(*39)

<?php if (Theme::has('title')) : ?>
    <?php echo Theme::place('title'); ?>
<?php endif; ?>

// or

<?php if (Theme::hasTitle()) : ?>
    <?php echo Theme::getTitle(); ?>
<?php endif; ?>

Get argument assigned to content in layout or region., _(*40)

Theme::getContentArguments();

// or

Theme::getContentArgument('name');

// To check if it exists

Theme::hasContentArgument('name');

Theme::place('content') is a reserve region to render sub-view., _(*41)

Preparing data to view

Sometimes you don't need to execute heavy processing, so you can prepare and use when you need it., _(*42)

$theme->bind('something', function()
{
    return 'This is bound parameter.';
});

Using bound data on view., _(*43)

echo Theme::bind('something');

Breadcrumb

In order to use breadcrumbs, follow the instruction below:, _(*44)

$theme->breadcrumb()->add('label', 'http://...')->add('label2', 'http:...');

// or

$theme->breadcrumb()->add(array(
    array(
        'label' => 'label1',
        'url'   => 'http://...'
    ),
    array(
        'label' => 'label2',
        'url'   => 'http://...'
    )
));

To render breadcrumbs., _(*45)

echo $theme->breadcrumb()->render();

// or

echo Theme::breadcrumb()->render();

You can set up breadcrumbs template anywhere you want by using a blade template., _(*46)

$theme->breadcrumb()->setTemplate('
    <ul class="breadcrumb">
    @foreach ($crumbs as $i => $crumb)
        @if ($i != (count($crumbs) - 1))
        <li><a href="{{ $crumb["url"] }}">{{ $crumb["label"] }}</a><span class="divider">/</span></li>
        @else
        <li class="active">{{ $crumb["label"] }}</li>
        @endif
    @endforeach
    </ul>
');

Widgets Design Structure

Theme has many useful features called "widget" that can be anything., _(*47)

Creating a widget

You can create a widget class using artisan command:, _(*48)

Creating as a global., _(*49)

php artisan theme:widget demo --global --type=blade

Widget tpl is located in "resources/views/widgets/{widget-tpl}.{extension}", _(*50)

Creating a specific theme name., _(*51)

php artisan theme:widget demo default --type=blade

Widget tpl is located in "public/themes/[theme]/widgets/{widget-tpl}.{extension}", _(*52)

The file name can be demo.php, demo.blade.php or demo.twig.php, _(*53)

Now you will see a widget class at /app/Widgets/WidgetDemo.php, _(*54)

User Id: {{ $label }}

Calling your widget in layout or view

echo Theme::widget('demo', array('label' => 'Demo Widget'))->render();

Using theme global

use Teepluss\Theme\Contracts\Theme;
use App\Http\Controllers\Controller;

class BaseController extends Controller {

    /**
     * Theme instance.
     *
     * @var \Teepluss\Theme\Theme
     */
    protected $theme;

    /**
     * Construct
     *
     * @return void
     */
    public function __construct(Theme $theme)
    {
        // Using theme as a global.
        $this->theme = $theme->uses('default')->layout('ipad');
    }

}

To override theme or layout., _(*55)

public function getIndex()
{
    $this->theme->uses('newone');

    // or just override layout
    $this->theme->layout('desktop');

    $this->theme->of('somewhere.index')->render();
}

Support or Contact

If you have any problems, Contact teepluss@gmail.com, _(*56)

, _(*57)

teeplus-5.5