wp-kit/flash

A wp-kit component that handles frontend and admin flash notifications

2.0.1 2020-01-31 23:41 UTC

This package is not auto-updated.

Last update: 2024-05-04 19:18:18 UTC


README

This is a wp-kit component that handles both frontend and admin flash notifications.

This component was built to run within an Illuminate\Container\Container so is perfect for frameworks such as Themosis, Assely and wp-kit/theme.

Often, Wordpress developers want to be able to use a single component the handle flashes stored in the session and their output to the client, usually after a redirect.

In Wordpress we do have the ability to forge admin notices via some hooks but there a few hoops to jump through in that you have to write quite a bit of code to handle the session storage and the output, and currently there are no hooks for front-end flashes.

Installation

If you're using Themosis, install via Composer in the Themosis route folder, otherwise install in your Composer driven theme folder:

composer require "wp-kit/flash"

Setup

Add Service Provider

Just register the service provider and facade in your providers config:

//inside theme/resources/config/providers.config.php

return [
    //
    WPKit\Config\ConfigServiceProvider::class, // we need this too,
    Illuminate\Filesystem\FilesystemServiceProvider::class, // specify the driver provider
    Illuminate\Session\SessionServiceProvider::class, // we need this too
    WPKit\Flash\FlashServiceProvider::class
];

Add Facade

If you are using Themosis or another Iluminate driven framework, you may want to add Facades, simply add them to your aliases:

//inside theme/resource/config/theme.config.php

'aliases' => [
    //
    'AdminFlash' => WPKit\Flash\Facades\AdminFlash::class,
    'FrontendFlash' => WPKit\Flash\Facades\FrontendFlash::class
    //
]

Add Config & View File(s)

Although a config file is not required for wp-kit/flash, we do need to publish view files and a config is needed for your SessionProvider.

The recommended method of installing config files for wp-kit components is via wp kit vendor:publish command.

First, install WP CLI, and then install this component, wp kit vendor:publish will automatically be installed with wp-kit/utils, once installed you can run:

wp kit vendor:publish

For more information, please visit wp-kit/utils.

Alternatively, you can place the config file(s) and view file(s) in your theme/resources/config and theme/resources/views directories manually.

Usage

Note: AdminFlash automatically outputs notices in admin area using the hook admin_notices.

Important Don't forget to use the Illuminate\Session\Middleware\StartSession middleware to ensure flashes persist.

use Themosis\Facades\Route;
use Illuminate\Session\Middleware\StartSession;

Route::group([
    'namespace' => 'Theme\Controllers',
    'middleware' => [
	StartSession::class, 
	'auth.form'
    ]
], function () {
    require themosis_path('theme.resources').'routes.php';
});	

Using Facades

// Just in case you need to include the Facade in a custom namespace

use WPKit\Flash\Facades\AdminFlash;
use WPKit\Flash\Facades\FrontendFlash;

// Frontend

FrontendFlash::success('Well done!');
FrontendFlash::warning('Hmm, not sure about that...');
FrontendFlash::error('What on earth are you doing?');

$messages = FrontendFlash::all();

$html = FrontendFlash::render();

$chained = FrontendFlash::success('Well done!')->render();

FrontendFlash::clear();

FrontendFlash::display([
	'message' => 'Ooh, living dangerously are we?'
	'class' => 'some-classname'
]);

// Admin

AdminFlash::success('Well done!');
AdminFlash::warning('Hmm, not sure about that...');
AdminFlash::error('What on earth are you doing?');

$messages = AdminFlash::all();

$html = AdminFlash::render();

$chained = AdminFlash::success('Well done!')->render();

AdminFlash::clear();

AdminFlash::display([
	'message' => 'Ooh, living dangerously are we?'
	'class' => 'some-classname'
]);

Using Helper Function

// Frontend

flash('frontend')->success('Well done!');
flash('frontend')->warning('Hmm, not sure about that...');
flash('frontend')->error('What on earth are you doing?');

$messages = flash('frontend')->all();

$html = flash('frontend')->render();

$chained = flash('frontend')->success('Well done!')->render();

flash('frontend')->clear();

flash('frontend')->display([
	'message' => 'Ooh, living dangerously are we?'
	'class' => 'some-classname'
]);

// Admin

flash('admin')->success('Well done!');
flash('admin')->warning('Hmm, not sure about that...');
flash('admin')->error('What on earth are you doing?');

$messages = flash('admin')->all();

$html = flash('admin')->render();

$chained = flash('admin')->success('Well done!')->render();

flash('admin')->clear();

flash('admin')->display([
	'message' => 'Ooh, living dangerously are we?'
	'class' => 'some-classname'
]);

Looping through messages

This is just a guide of how you use use wp-kit/flash when looping through a load of flashes where you need to output markup around each flash:

// within theme/resources/views/some-view.php

<div class="row">

	<?php foreach( flash('frontend')->all() as $message ) : ?>
	
		<div class="column">
		
			<?php flash( 'frontend' )->display( $message ); ?>
			
		</div>
		
	<?php endforeach; ?>
	
</div>

Get Involved

To learn more about how to use wp-kit check out the docs:

View the Docs

Any help is appreciated. The project is open-source and we encourage you to participate. You can contribute to the project in multiple ways by:

  • Reporting a bug issue
  • Suggesting features
  • Sending a pull request with code fix or feature
  • Following the project on GitHub
  • Sharing the project around your community

For details about contributing to the framework, please check the contribution guide.

Requirements

Wordpress 4+

PHP 5.6+

License

wp-kit/flash is open-sourced software licensed under the MIT License.