Admin Listing

• Requirements
• Installation
• Basic usage
• Advanced usage
  • Basic instance
  • Columns to query
  • Ordering
  • Searching
  • Pagination
  • Additional query modification
• Listing for translatable models

AdminListing is a helper that simplifies administration listing for your Eloquent models. It helps transforming a typical request to data. It can auto-handle all the basic stuff like pagination, ordering, search. It can handle also translatable eloquent models (see How to make your model translatable).

Requirements

This package requires PHP 7.0+ and Laravel (5.5, 5.6 or 5.7).

For searching functionality your database must support like operator.

For listing of translatable models to work, use of JSON columns are required. That's why MySQL 5.7+ or PostgreSQL 9.5+ are required.

Installation

{danger.fa-exclamation-triangle} This section is only when you want to use this package as a standalone package. If you are using with Craftable, then this package is already installed.

Installation is straightforward - let's add a new requirement:

composer require brackets/admin-listing

That's it. Provider will be discovered automatically.

Basic usage

When you are creating a CRUD interface, you probably need an admin listing displaying all the rows of your data represented by an Eloquent model. You usually want such listing to be sortable, searchable and paginable.

Our helper AdminListing covers typical scenario of such requirements including:

• ordering (=sorting)
• searching (simple searching using SQL like operator)
• pagination

It's basically just a layer built on top of the query builder, but it speeds up a development a lot. The usage is very simple:

use AdminListing;

class MoviesController extends Controller
{
    public function index(Request $request)
    {
        // create and AdminListing instance for a specific model and
        $data = AdminListing::create(Movie::class)
            ->processRequestAndGet(

            // pass the request object
            $request,

            // set columns to query
            ['id', 'title', 'published_at'],

            // set columns to searchIn
            ['id', 'title', 'body']
        );

        if ($request->ajax()) {
            return ['data' => $data];
        }

        return view('admin.movie.index', ['data' => $data]);

    }

AdminListing automatically process these query parameters from request:

• orderBy, orderDirection for ordering
• search for searching
• page, per_page for pagination

{danger.fa-exclamation-triangle} AdminListing does not provide any request authorization nor validation, so you should handle that on your own.

Advanced usage

If above usage is too much magic for your needs, we provide couple of helper methods to build up your own listing.

Basic instance

Use get() method to get basic listing without any additional features:

class MoviesController extends Controller
{
    public function index(IndexMovie $request)
    {
        $data = AdminListing::create(Movie::class)
            ->get();

$data now holds a standard Collection of Eloquent model objects.

Columns to query

You can pass an array of columns to the get method just like in standard query builder.

class MoviesController extends Controller
{
    public function index(IndexMovie $request)
    {
        $data = AdminListing::create(Movie::class)
            ->get(['id', 'name']);

Ordering

To build listing with ordering functionality, use attachOrdering() method:

class MoviesController extends Controller
{
    public function index(IndexMovie $request)
    {
        $data = AdminListing::create(Movie::class)
            ->attachOrdering($request->sortBy, $request->sortDirection)
            ->get();

Searching

To build listing with search functionality, use attachSearch() method:

class MoviesController extends Controller
{
    public function index(IndexMovie $request)
    {
        $data = AdminListing::create(Movie::class)
            ->attachSearch($request->queryString,
                // specify an array of columns to search in
                ['id', 'name', 'body']
            )
            ->get();

{danger.fa-exclamation-triangle} Searching is currently available only for text attributes and primary key.

Pagination

To build listing with pagination functionality, use attachPagination() method:

class MoviesController extends Controller
{
    public function index(IndexMovie $request)
    {
        $data = AdminListing::create(Movie::class)
            ->attachPagination($request->currentPage)
            ->get();

{info} If you use pagination functionality, object of Pagination\LengthAwarePaginator is returned instead of standard Collection.

Additional query modification

In some cases you still need to modify query a bit (i.e. add some filters). In that case you can use modifyQuery() method:

class MoviesController extends Controller
{
    public function index(IndexMovie $request)
    {
        $data = AdminListing::create(Movie::class)
            ->modifyQuery(function($query) use ($request){
                if ($request->has('author_id')) {
                    $query->where('author_id', $request->author_id);
                }
            })
            ->get();

Listing for translatable models

AdminListing supports translatable models as well (see How to make your model translatable). You don't have to set up anything.

By default it uses a default locale, but you can set a locale you would like to work with:

class MoviesController extends Controller
{
    public function index(IndexMovie $request)
    {
        $data = AdminListing::create(Movie::class)
            ->setLocale('fr')
            ->get();

You can now work with ordering or search just like with non-translatable model and the class takes care of all the translation stuff. Returned $data variable is holding a collection of models that has locale set up correctly therefor returned JSON is going to be translated in French.