pragmarx/steroids

Steroids v0.7

Laravel 4 Blade on Steroids

This package provides some aditional features to Laravel Blade:

Automatic command generation

Create a file named <command>.blade.php in the templates directory and it automatically becomes a blade command.

Take the file

default\css.blade.php

Whaving the contents:

<link rel="stylesheet" type="text/css" media="screen" href="@_1">

Hackers can now use the command

@css(/css/bootstrap.css)

In their blade templates to generate:

<link rel="stylesheet" type="text/css" media="screen" href="/css/bootstrap.css">

Subtemplating

Every sublevel in your template directory creates a level in command name. This tree:

├── default
│   ├── input.blade.php
│   ├── js.blade.php
│   └── php.blade.php
│   └── text.blade.php
├── bs
│   └── v2
│   │   ├── input.blade.php
│   │   └── form.blade.php
│   │   └── model.blade.php
│   ├── input.blade.php
│   └── form.blade.php

Would give you the following commands:

@input()
@js()
@php()
@text()

@bs.input()
@bs.form()

@bs.v2.input()
@bs.v2.form()
@bs.v2.model()

Block commands

Let's take the (silly, I know! :) @php (file php.blade.php) command as an example of a block:

@php
    $title = 'subscribe';
@@

Note that a block ends with @@ and you can have as many nested blocks as you want. This is the @php command's source code:

<?php 
    @_BODY;
?>

It's that simple, to create a block command you just have to add the @_BODY identifier in any part of your command.

Extending commands

You can create an @input command:

<input type="@_1" @_ATTRIBUTES />

And use it to create a

@text:

@input(text,@_PARAMETERS)

@email:

@input(email,@_PARAMETERS)

and @password commands:

@input(password,@_PARAMETERS)

HTML Attributes, Local Variables and Positional Parameters

You can dynamically create and send any number of parameters to your commands:

HTML Attributes

Take @input as an example:

@input(type=email,class=form-control,id=example,placeholder=Enter email)

Having this template

<input @_ATTRIBUTES />

It will generate this tag:

<input type="email" class="form-control" id="example" placeholder="Enter email">

Local Variables

Use a hash to define a local variable:

@input(#type=email,class=form-control,id=example,placeholder=Enter email)

And you access it by using the variable identifier @_:

<input type="@_type" @_ATTRIBUTES />

Positional Parameters

You also can access any of yours parameter by the number, let's set the type of input as the first one:

@input(email,class=form-control,id=example,placeholder=Enter email)

Then you just have to use the variable identifier followed by the parameter number:

<input type="@_1" @_ATTRIBUTES />

Another example is the Form::model(), provided by @model, this is the template

{{ Form::model(@_1, $options) }}
    @_BODY
{{ Form::close() }}

And in your view you just have to:

@model($user,url=/profile)
    ... your controls ...
@@

Assignment and Multi Assignment

You assign values to local (#) variables by using the equal sign:

@text(#label=form-control)

You assign values to html attributes by doing the same, just don't put the hash sign:

@text(class=form-control)

And you can also do multi assignments:

@text(#label=title=First Name,class=form-control)

Superglobals (licentia poetica)

@_BODY: will be replaced by your command body

@_ATTRIBUTES: all HTML attributes generated by your command

@_PARAMETERS: it's a raw list of parameters, you can use it to pass them forward to an extended command, this is the source of @text, which extends @input:

@if (@_name->has)
    @input(text,name=@_1,@_PARAMETERS)
@else
    @input(text,@_PARAMETERS)
@endif

@_SINGLE: if you have a command that accepts only one parameter

@h1(Hi There!)

You can use this superglobal:

<h1>@_SINGLE</h1>

But you can still use the positional variable:

<h1>@_1</h1>

Special functions

->has

If you need to know if a variable was set you can use the ->has function:

@if (@_label->has) 
    <label class="label">@_label</label>
@endif
<input type="@_1" @_ATTRIBUTES />

The ->has function will return true or false, and then your view (in PHP) would probably look like this:

<?php if (false): ?>
    <label class="label"></label>
<?php endif; ?>
<input type="email" ... />

Steroids comes with some examples:

->bare

If you need to access one of your HTML attributes you can use the ->bare function:

<input type="@_1" class="@_class->bare" />

Delimiters and Quotation marks

As delimiters of your parameters you can use , or ;:

@input(email,class=form-control,id=example,placeholder=Enter email)

@input(email;class=form-control;id=example;placeholder=Enter email)

You don't need to use quotation marks (single ' or double "), unless you need to use any of those delimiters in your strings:

@input(email,placeholder="Hello, World!")

Examples

Steroids comes with some examples, but you can get crazy and create as many as you wish:

├── default
│   ├── css.blade.php
│   ├── form.blade.php
│   ├── h.blade.php
│   ├── input.blade.php
│   ├── js.blade.php
│   ├── model.blade.php
│   ├── p.blade.php
│   ├── php.blade.php
│   ├── row.blade.php
│   └── text.blade.php
├── bs
│   ├── md.blade.php
│   └── xs.blade.php

Easy creation of partials

Sometimes creating s simple box can be as complicated as:

<div class="row">
    <article class="col-sm-12 col-md-12 col-lg-12">
            <div>
                <div class="jarviswidget-editbox">
                    @editbox('your name goes here')
                </div>

                <div class="widget-body no-padding">
                    @_BODY
                </div>
            </div>
        </div>
    </article>
</div>

But after Steroids, you just need to do this in your code:

@box
    And do whatever you need inside it!
@@

Artisan Commands

Steroids has two artisan commands:

steroids:templates - to copy the examples to your app/config/package folder

php artisan steroids:templates

steroids:list - list all of your Steroids commands

php artisan steroids:list

view:clear - to clear you views cache

php artisan view:clear

Using the Facade directly

To compile a view using Steroids, you just have to:

 return Steroids::inject('@input(type=email,name=email,class=form-control)')

Installation

Requirements

• Laravel 4.1+
• Composer >= 2014-01-07 - This is a PSR-4 package

Installing

Require the Steroids package:

composer require pragmarx/steroids dev-master

Add the service provider to your app/config/app.php:

'PragmaRX\Steroids\Vendor\Laravel\ServiceProvider',

To publish the configuration file you'll have to:

php artisan config:publish pragmarx/steroids

Copy the templates examples to your app folder:

php artisan steroids:templates

Tests

• Steroids Tests Coverage is at 100%

TODO

• Invalidate main templates when a Steroids command changes

Author

Antonio Carlos Ribeiro

License

Steroids is licensed under the BSD 3-Clause License - see the LICENSE file for details

Contributing

Pull requests and issues are more than welcome.