Livewire component to show records according to their current status

Last update: May 18, 2022

Livewire Status Board

Livewire component to show records/data according to their current status

Preview

preview

Installation

You can install the package via composer:

composer require asantibanez/livewire-status-board

Requirements

This package uses livewire/livewire (https://laravel-livewire.com/) under the hood.

It also uses TailwindCSS (https://tailwindcss.com/) for base styling.

Please make sure you include both of this dependencies before using this component.

Usage

In order to use this component, you must create a new Livewire component that extends from LivewireStatusBoard

You can use make:livewire to create a new component. For example.

php artisan make:livewire SalesOrdersStatusBoard

In the SalesOrdersStatusBoard class, instead of extending from the base Livewire Component class, extend from LivewireStatusBoard. Also, remove the render method. You'll have a class similar to this snippet.

class SalesOrdersStatusBoard extends LivewireStatusBoard
{
    //
}

In this class, you must override the following methods to display data

public function statuses() : Collection 
{
    //
}

public function records() : Collection 
{
    //
}

As you may have noticed, both methods return a collection. statuses() refers to all the different status values your data may have in different points of time. records() on the other hand, stand for the data you want to show that could be in any of those previously defined statuses() collection.

To show how these two methods work together, let's discuss an example of Sales Orders and their different status along the sales process: Registered, Awaiting Confirmation, Confirmed, Delivered. Each Sales Order might be in a different status at specific times. For this example, we might define the following collection for statuses()

public function statuses() : Collection
{
    return collect([
        [
            'id' => 'registered',
            'title' => 'Registered',
        ],
        [
            'id' => 'awaiting_confirmation',
            'title' => 'Awaiting Confirmation',
        ],
        [
            'id' => 'confirmed',
            'title' => 'Confirmed',
        ],
        [
            'id' => 'delivered',
            'title' => 'Delivered',
        ],
    ]);
}

For each status we define, we must return an array with at least 2 keys: id and title.

Now, for records() we may define a list of Sales Orders that come from an Eloquent model in our project

public function records() : Collection
{
    return SalesOrder::query()
        ->map(function (SalesOrder $salesOrder) {
            return [
                'id' => $salesOrder->id,
                'title' => $salesOrder->client,
                'status' => $salesOrder->status,
            ];
        });
}

As you might see in the above snippet, we must return a collection of array items where each item must have at least 3 keys: id, title and status. The last one is of most importance since it is going to be used to match to which status the record belongs to. For this matter, the component matches status and records with the following comparison

$status['id'] == $record['status'];

To render the component in a view, just use the Livewire tag or include syntax

<livewire:sales-orders-status-board />

Populate the Sales Order model and you should have something similar to the following screenshot

basic

You can render any render and statuses of your project using this approach 👍

Sorting and Dragging

By default, sorting and dragging between statuses is disabled. To enable it, you must include the following props when using the view: sortable and sortable-between-statuses

">
<livewire:sales-orders-status-board 
    :sortable="true"
    :sortable-between-statuses="true"
/>

sortable enables sorting withing each status and sortable-between-statuses allow drag and drop from one status to the other. Adding these two properties, allow you to have drag and drop in place.

You must also install the following JS dependencies in your project to enable sorting and dragging.

npm install sortablejs

Once installed, make them available globally in the window object. This can be done in the bootstrap.js file that ships with your Laravel app.

window.Sortable = require('sortablejs').default;

Behavior and Interactions

When sorting and dragging is enabled, your component can be notified when any of these events occur. The callbacks triggered by these two events are onStatusSorted and onStatusChanged

On onStatusSorted you are notified about which record has changed position within it's status. You are also given a $orderedIds array which holds the ids of the records after being sorted. You must override the following method to get notified on this change.

public function onStatusSorted($recordId, $statusId, $orderedIds)
{
    //   
}

On onStatusChanged gets triggered when a record is moved to another status. In this scenario, you get notified about the record that was changed, the new status, the ordered ids from the previous status and the ordered ids of the new status the record in entering. To be notified about this event, you must override the following method:

public function onStatusChanged($recordId, $statusId, $fromOrderedIds, $toOrderedIds)
{
    //
}

onStatusSorted and onStatusChanged are never triggered simultaneously. You'll get notified of one or the other when an interaction occurs.

You can also get notified when a record in the status board is clicked via the onRecordClick event

public function onRecordClick($recordId)
{
    //
}

To enable onRecordClick you must specify this behavior when rendering the component through the record-click-enabled parameter

">
<livewire:sales-orders-status-board 
    :record-click-enabled="true"
/>

Styling

To modify the look and feel of the component, you can override the styles method and modify the base styles returned by this method to the view. styles() returns a keyed array with Tailwind CSS classes used to render each one of the components. These base keys and styles are:

return [
    'wrapper' => 'w-full h-full flex space-x-4 overflow-x-auto', // component wrapper
    'statusWrapper' => 'h-full flex-1', // statuses wrapper
    'status' => 'bg-blue-200 rounded px-2 flex flex-col h-full', // status column wrapper 
    'statusHeader' => 'p-2 text-sm text-gray-700', // status header
    'statusFooter' => '', // status footer
    'statusRecords' => 'space-y-2 p-2 flex-1 overflow-y-auto', // status records wrapper 
    'record' => 'shadow bg-white p-2 rounded border', // record wrapper
    'recordContent' => '', // record content
]; 

An example of overriding the styles() method can be seen below

public function styles()
{
    $baseStyles = parent::styles();

    $baseStyles['wrapper'] = 'w-full flex space-x-4 overflow-x-auto bg-blue-500 px-4 py-8';

    $baseStyles['statusWrapper'] = 'flex-1';

    $baseStyles['status'] = 'bg-gray-200 rounded px-2 flex flex-col flex-1';

    $baseStyles['statusHeader'] = 'text-sm font-medium py-2 text-gray-700';

    $baseStyles['statusRecords'] = 'space-y-2 px-1 pt-2 pb-2';

    $baseStyles['record'] = 'shadow bg-white p-2 rounded border text-sm text-gray-800';

    return $baseStyles;
}

With these new styles, your component should look like the screenshot below

basic

Looks like Trello, right? 😅

Advanced Styling and Behavior

Base views of the component can be customized as needed by exporting them to your project. To do this, run the php artisan vendor:publish command and export the livewire-status-board-views tag. The command will publish the base views under /resources/views/vendor/livewire-status-board. You can modify these base components as needed keeping in mind to maintain the data attributes and ids along the way.

Another approach is copying the base view files into your own view files and pass them directly to your component

">
<livewire:sales-orders-status-board 
    status-board-view="path/to/your/status-board-view"
    status-view="path/to/your/status-view"
    status-header-view="path/to/your/status-header-view"
    status-footer-view="path/to/your/status-footer-view"
    record-view="path/to/your/record-view"
    record-content-view="path/to/your/record-content-view"
/>

Note: Using this approach also let's you add extra behavior to your component like click events on header, footers, such as filters or any other actions

Adding Extra Views

The component let's you add a view before and/or after the status board has been rendered. These two placeholders can be used to add extra functionality to your component like a search input or toolbar of actions. To use them, just pass along the views you want to use in the before-status-board-view and after-status-board-view props when displaying the component.

">
<livewire:sales-orders-status-board 
    before-status-board-view="path/to/your/before-status-board-view"
    after-status-board-view="path/to/your/after-status-board-view"  
/>

Note: These views are optional.

In the following example, a before-status-board-view has been specified to add a search text box and a button

extra-views

Testing

composer test

Changelog

Please see CHANGELOG for more information what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

Credits

License

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

GitHub

https://github.com/asantibanez/livewire-status-board
Comments
  • 1. getting issue while installation

    Hello sir getting this issue while installation Problem 1 - Can only install one of: livewire/livewire[1.x-dev, v2.2.7]. - Can only install one of: livewire/livewire[v2.2.7, 1.x-dev]. - Can only install one of: livewire/livewire[1.x-dev, v2.2.7]. - asantibanez/livewire-status-board 1.0.0 requires livewire/livewire ^1.1 -> satisfiable by livewire/livewire[1.x-dev]. - Installation request for asantibanez/livewire-status-board ^1.0 -> satisfiable by asantibanez/livewire-status-board[1.0.0]. - Installation request for livewire/livewire (locked at v2.2.7, required as ^2.0) -> satisfiable by livewire/livewire[v2.2.7].

    Laravel version 8.6.0 Livewire version 2.2.7

    Reviewed by RohitRD31 at 2020-09-25 08:20
  • 2. Remove jQuery dependency

    I noticed the only place jQuery is being used is resources/views/sortable.blade.php

    ...
    const fromOrderedIds = $(evt.from).children().map((index, child) => child.id).get();
    
    const toOrderedIds = $(evt.to).children().map((index, child) => child.id).get();
    

    I updated this locally to make it work without jQuery:

    const fromOrderedIds = [].slice.call(evt.from.children).map((child, i) => child.id);
    

    I can make a PR if you'd like

    Reviewed by messerli90 at 2020-06-26 15:30
  • 3. Get model instead of id in callbacks

    Hey there, thanks for a great package!

    Would it be possible to have model binding in the callsbacks? Livewire supports this, but I'm not sure if this is possible when overwriting methods from LivewireStatusBoard in our own custom implementations.

    I need to do a redirect that requires some data from a related model, and right now I have to first load that model with a findOrFail. It would be nice if I could just do this

    class CustomStatusBoard extends LivewireStatusBoard
    {
        public function onRecordClick(MyModel $model)
        {
            $this->redirect(route('custom.show', ['parent' => $model->parent, 'model' => $model]));
        }
    }
    
    Reviewed by Ahrengot at 2020-10-18 20:00
  • 4. Add back support for Livewire v1

    Is there a reason Livewire v1 support was dropped? This package seems to work just fine with Livewire v1.

    Would be great to keep support for Livewire v1 until something only available in v2 needs to be used.

    Would also make upgrading our app to Laravel v8 a lot easier.

    Love,

    Wilbur.

    Reviewed by wilburpowery at 2021-06-22 20:40
  • 5. Layout component?

    Great package. My question is around using my layout components and sharing data.

    In my case, for most of my pages I use Livewire's layoutData() when rendering the component's view, a la:

    return view('livewire.pages.my-page')
    ->layoutData([
      'section' => $this->section
    ]);
    

    I know the package bypasses Livewire's native render. Aside from being able to publish the views themselves, is there a way I'm missing to override the render so I can push additional data?

    Thanks for any help!

    Reviewed by dambridge at 2021-10-14 23:22
  • 6. Changes to the records data set are not updating when in component

    I have implemented your status board library and have it working as documented. It is exactly what I needed to help maintain a large set of tasks and what status they are in. The problem I have is that I have a list of "filters" that change the records that are being mapped in the records() function, and they are not updating. I have a simple log call in the records function that I am using to even test if there is activity when I am changing the filter. I can confirm that the change is happening as the other list views and pagination is changing.

    Here is my records function:

    public function records(): Collection
        {
        
            ray("records called");
            return $this->tasks
            ->map(function (Task $task) {
                return [
                    'id' => $task->id,
                    'title' => $task->task_title,
                    'status' => $task->status,
                    'task' => $task
                ];
            });
    
        }
    

    I am getting tasks (records for this) from a property function in a trait (however I can confirm this also doesn't work if it isn't in a trait).

    public function getTasksProperty()
        {
            ray("getting tasks...");
    
            // Compose Query
            // Base Queries
            $query = Task::query();
            $query = $query->where('organization_id', Auth::user()->organization_id);
            $query = $query->where('task_title', 'like', '%' . $this->search . '%');
    
    
            // Variables for Query
            switch ($this->filter) {
                default:
                case ('open'):
                    $query = $query->where('user_id', Auth::user()->id);
                    $query = $query->where('complete', '0');
                    break;
    
                case ('assigned'):
                    $query = $query->where('assigned_to', Auth::user()->id);
                    $query = $query->where('complete', '0');
                    break;
    
                case ('completed'):
                    $query = $query->where('assigned_to', Auth::user()->id);
                    $query = $query->where('complete', '1');
                    break;
            }
    
            switch ($this->section) {
                case ('meetings'):
                    $query = $query->where('meeting_id', $this->sectionItem);
                    break;
    
                case ('projects'):
                    $query = $query->where('project_id', $this->sectionItem);
                    break;
    
                case ('people'):
                    $query = $query->where('assigned_to', $this->sectionItem);
                    break;
            }
    
            // Base Order/Paginate Queries
            $query = $query->with('user');
            $query = $query->with('subtasks');
            $query = $query->with('updates');
            $query = $query->orderBy('pin', 'desc');
            $query = $query->orderBy('priority', 'desc');
            $query = $query->orderBy('due', 'asc');
    
            if($this->component == 'board') {
                $results = $query->get();
            } else {
                $results = $query->paginate($this->tasksPerPage);
            }
    
    
            return $results;
        }
    

    When a change happens to a filter should I also refresh the component? Any help here would be appreciated.

    Reviewed by awizemann at 2021-05-25 00:53
  • 7. Fix typos

    This PR is aimed at fixing different kinds of typo and grammar in the readme file. I have also added an @include('sales-orders-status-board') method to render livewire component

    Reviewed by Williamug at 2021-05-17 05:27
OpenEMR is a Free and Open Source electronic health records and medical practice management application

OpenEMR is a Free and Open Source electronic health records and medical practice management application. It features fully integrated electronic health records, practice management, scheduling, electronic billing, internationalization, free support, a vibrant community, and a whole lot more. It runs on Windows, Linux, Mac OS X, and many other platforms.

May 18, 2022
Simplified database records management.
Simplified database records management.

Simplified database records management. Inspector will let you take care of CRUD without taking over your frontend. Example $inspector = new \InvoiceN

Mar 9, 2022
SPFtoolbox is a Javascript and PHP app to look up DNS records such as SPF, MX, Whois, and more
SPFtoolbox is a Javascript and PHP app to look up DNS records such as SPF, MX, Whois, and more

SPFtoolbox is a Javascript and PHP app to look up DNS records such as SPF, MX, Whois, and more

May 14, 2022
Switch the DokuWiki interface language according to the accept-language request header

Switch the DokuWiki interface language according to the accept-language request header

Jan 4, 2022
Our team created for you one of the most innovative CRM systems that supports mainly business processes and allows for customization according to your needs. Be ahead of your competition and implement YetiForce!
Our team created for you one of the most innovative CRM systems that supports mainly business processes and allows for customization according to your needs. Be ahead of your competition and implement YetiForce!

We design an innovative CRM system that is dedicated for large and medium sized companies. We dedicate it to everyone who values open source software,

May 24, 2022
A dynamic Laravel Livewire component for tab forms
A dynamic Laravel Livewire component for tab forms

Livewire component that provides you with a tabs that supports multiple tabs form while maintaining state.

May 15, 2022
A self hosted download manager for movie and tv show trailers.

Introduction Trailarr is a self hosted download manager for movie and tv show trailers. Features: A beautiful, easy to use UI. Easy setup, readily con

Apr 23, 2022
Retrieve MySejahtera App's data from MySejahtera API and show to users via web browser. Written in PHP
Retrieve MySejahtera App's data from MySejahtera API and show to users via web browser. Written in PHP

MySejahtera-PHP-Web Retrieve MySejahtera App's data from MySejahtera API and show to users via web browser. Written in PHP. Disclaimer This web app is

Mar 31, 2022
The objective of this project is to manage The Website Manga, this site permits to Client to show, read and download Manga with the possibility to react, vote, and save his data.
The objective of this project is to manage The Website Manga, this site permits to Client to show, read and download Manga with the possibility to react, vote, and save his data.

The objective of this project is to manage The Website Manga, this site permits to Client to show, read and download Manga with the possibility to react, vote, and save his data.

Jan 24, 2022
BicBucStriim streams books, digital books. It fills a gap in the functionality of current NAS devices that provide access to music, videos and photos

BicBucStriim streams books, digital books. It fills a gap in the functionality of current NAS devices that provide access to music, videos and photos -- but not books. BicBucStriim fills this gap and provides web-based access to your e-book collection.

May 12, 2022
CRUD php application to check in and check out employees and show daily building occupation
CRUD php application to check in and check out employees and show daily building occupation

CRUD php application to check in and check out employees and show daily building occupation. Employees are required to self check their temperature and tick a checkbox to specify whether their temperature is below 38°C else they are invited to stay home. (Implemented in php with bootstrap4 for styling and datatable jquery plugin for table formatting and additional features).

Feb 20, 2022
📛 An open source status page system for everyone.

Cachet is a beautiful and powerful open source status page system. Overview List your service components Report incidents Customise the look of your s

May 23, 2022
Linfo PHP Server Health Status
Linfo PHP Server Health Status

Linfo - Server stats UI/library Linfo is a: Light themable Web UI and REST API displaying lots of system stats Ncurses CLI view of WebUI Extensible, e

May 16, 2022
Cachet is a beautiful and powerful open source status page system.
Cachet is a beautiful and powerful open source status page system.

Cachet is a beautiful and powerful open source status page system. Overview List your service components Report incidents Customise the look of your s

Dec 5, 2021
AdoteUm.Dev has the proposal to connect people who are looking for developers for their projects

AdoteUm.Dev has the proposal to connect people who are looking for developers for their projects. AdoteUmDev is a web application, developed in PHP language and the Laravel Framework.

May 22, 2022
Server manager is a open source project made for people so that they can add the servers to one single place irrespective of their provider and manage it through one location.
Server manager is a open source project made for people so that they can add the servers to one single place irrespective of their provider and manage it through one location.

Server Manager Are you sick of having to log into hundreads of different website just to access your server? Well we got you, Server manager is a open

Jan 18, 2022
GitScrum is a Project Management Tool, developed to help entrepreneurs, freelancers, managers, and teams Skyrocket their Productivity with the Agile methodology and Gamification.
GitScrum is a Project Management Tool, developed to help entrepreneurs, freelancers, managers, and teams Skyrocket their Productivity with the Agile methodology and Gamification.

GitScrum is a Project Management Tool, developed to help entrepreneurs, freelancers, managers, and teams Skyrocket their Productivity with the Agile methodology and Gamification.

May 20, 2022
ControlPanel's Dashboard is a dashboard application designed to offer clients a management tool to manage their pterodactyl servers.
ControlPanel's Dashboard is a dashboard application designed to offer clients a management tool to manage their pterodactyl servers.

Features PayPal Integration Email Verification Audit Log Admin Dashboard User/Server Management Store (credit system) Vouchers and so much more! Contr

May 24, 2022
A PHP package that retrieves Uganda's districts with their respective counties, sub counties, parishes and villages in Uganda.
A PHP package that retrieves Uganda's districts with their respective counties, sub counties, parishes and villages in Uganda.

This package gives you the leverage to access all sub levels ranging from districts, counties, subcounties, parishes to villages in Uganda. You can also access the different mentioned areas independently.

Apr 24, 2022