README

Inspector Gadget is a web-component and Ember.js inspired library for improving data-flow, maintainability, and template reusability.

Gadgets, in inspector gadget allow for template partials or even plain strings to be rendered in a smart, explicit fashion while reducing weight and overloaded controllers or domain layers.

Install

Via Composer

$ composer require rtablada/inspector-gadget

In the app.php config file, add 'Rtablada\InspectorGadget\GadgetServiceProvider', to the providers array.

Then publish the configuration file with php artisan vendor:publish to publish the config/inspector-gadget.php file.

Note

You can optionally install install the Rtablada\InspectorGadget\Facades\Gadget' to the facades array as Gadget to use gadget facades in your views.

Usage

Gadget Classes

Gadgets are just plain PHP objects with a render method. The string returned by the render function will be sent back to your views. Since the gadgets are resolved using the application container, you can dependency inject like any other class in your application.

class ExampleGadget
{
    public function render()
    {
        return 'this string will be returned';
    }
}

Making Gadgets with the GadgetFactory

In you views, you can render gadgets using the make function on the gadgetFactory variable that is available in your views. The make function accepts a string argument for the gadget class that you want to render in your view.

$gadgetFactory->make('ExampleGadget'); // returns 'this string will be returned'

Passing Arguments to Gadgets

To allow greater flexibility, you can pass arguments to the render function in your gadget.

// app/Gadgets/ArgumentGadget.php
class ArgumentGadget
{
    public function render($str)
    {
        return $str . ' from gadget';
    }
}

// view.php
$gadgetFactory->make('ArgumentGadget', 'test'); // returns 'test from gadget'

Shortcuts

If you have registered the Gadget facade, then you can have the following in your views:

Gadget::make('ExampleGadget');

If you're using blade templates, there is a @gadget helper that calls $gadgetFactory->make()

@gadget('ExampleGadget')

Better Data Flow

Consider the following controller action:

public function show($id)
{
    $post = $this->post->find($id);
    $relevantPosts = $this->suggestionEngine->relevantPosts($post);
    $comments = $this->comment->allForPost($post);

    $user = $this->auth->user();

    $userHistory = $this->historyCache->historyForUser($user);
    // etc.

    return view('post.show', compact('post', 'relevantPosts', 'comments', 'user', 'userHistory', '...'));
}

And the accompanying view:

<div class="sidebar">
    <div class="user-history">
        <h4>History</h4>
        <?php foreach ($userHistory->posts as $historyPost) ?>
            <!-- Markup for $historyPost-->
        <?php endforeach ?>
    </div>

    <div class="suggested-articles">
        <h4>Things You Might Like</h4>
        <?php foreach ($relevantPosts as $relevantPost) ?>
            <!-- Markup for $relevantPost-->
        <?php endforeach ?>
    </div>

    <!-- etc. -->
</div>

This can be cleaned up using gadgets:

// Controller
public function show($id)
{
    $post = $this->post->find($id);
    $user = $this->auth->user();

    return view('post.show', compact('post', 'user'));
}

// View
<div class="sidebar">
    <div class="user-history">
        <h4>History</h4>
        @gadget('UserPostHistory', $user)
    </div>

    <div class="suggested-articles">
        <h4>Things You Might Like</h4>
        @gadget('RelevantPosts', $post)
    </div>

    <!-- etc. -->
</div>

Configuring

Default Namespace

To shorten the need for full class names in your Gadget::make calls, Inspector Gadget has a namespace configuration option in the config/inspector-gadget.php file. This is used as a default namespace to look up gadgets. If a class is not found in your configured default namespace, then Inspector Gadget will attempt to load from the full class name.

Aliases

To further shorthand and ease, you can register aliases in the aliases array in the config/inspector-gadget.php file. This allows for gadgets to be aliased without poluting the app container.

Testing

$ phpunit

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email ryan@embergrep.com instead of using the issue tracker.

Credits

License

The MIT License (MIT). Please see License File for more information.

rtablada / inspector-gadget

Maintainers

Details