Krajee
Thankful to Krajee! BUY A COFFEEor to get more out of us.

A widget that turns standard Bootstrap alerts into "Growl-like" notifications. This widget is a wrapper for the Bootstrap Growl plugin by remabledesigns. The widget offers various features including

  • Alert Positioning: Position and align growl notifications at any corner of your page.
  • Icon & Title Section: Ability to set a stylish title separator section and add an icon and title for each alert as a header.
  • Fade: Ability to set a fade duration to automatically fade out the alerts after display.
  • Plugin Configuration: Ability to configure various options by passing parameters to the JQuery plugin.

Important

This widget can be also installed in isolation outside this bundle if needed. In addition to using via \kartik\widgets namespace, this widget can be also installed from the yii2-widget-growl repository and can also be accessed via \kartik\growl\Growl namespace.

Tip

Not seeing the updated content on this page! Hard refresh your browser to clean cache for this page (e.g. SHIFT-F5 on Windows Chrome)

Growl supports configuration of the bootstrap library version so that you can use this either with any Bootstrap version 3.x and above. For setting up the bootstrap version for your extension, you can configure the Growl::bsVersion property to one of the following.

  • To use with bootstrap 3 library - you can set Growl::bsVersion property to any string starting with 3 (e.g. 3 or 3.3.7 or 3.x)

  • To use with bootstrap 4 library - you can set Growl::bsVersion property to any string starting with 4 (e.g. 4 or 4.6.0 or 4.x)

  • To use with bootstrap 5 library - you can set Growl::bsVersion property to any string starting with 5 (e.g. 5 or 5.1.0 or 5.x)

The following sections describe the pre-requisites for enabling Bootstrap library specific version support in your application and other related controls/overrides.

Global Bootstrap Version


Generally, you may also want to set a default version globally for all Krajee Extensions (instead of setting it for each widget or extension separately). In order to do this, you can setup the bsVersion property within Yii 2 application params (i.e. Yii::$app->params['bsVersion']). To set this up, add this section of code to your application params configuration file (e.g. config/params.php):

'params' => [
    'bsVersion' => '5.x', // this will set globally `bsVersion` to Bootstrap 5.x for all Krajee Extensions
    // other settings
    // 'adminEmail' => 'admin@example.com'
]

If Growl::bsVersion property is set, in addition to Yii::$app->params['bsVersion'], the extension level setting (Growl::bsVersion property) will override the Yii::$app->params['bsVersion']. If Growl::bsVersion property is not set, and Yii::$app->params['bsVersion'] is also not set, Growl::bsVersion property will default to 3.x (i.e. Bootstrap 3.x version will be assumed as default).

Yii2 Bootstrap Dependency


You need to install one of yiisoft/yii2-bootstrap or yiisoft/yii2-bootstrap4 or yiisoft/yii2-bootstrap5 extensions manually in your application to enable Bootstrap 3.x or 4.x or 5.x functionality respectively. This dependency has not been pre-built into the composer configuration for Krajee extensions, to allow better control to the developers in configuring their bootstrap library version. If bsVersion is set to 5.x and yiisoft/yii2-bootstrap5 is not installed, then an exception message will be thrown mentioning you to install the yiisoft/yii2-bootstrap5 extension. If bsVersion is set to 4.x and yiisoft/yii2-bootstrap4 is not installed, then an exception message will be thrown mentioning you to install the yiisoft/yii2-bootstrap4 extension. Similarly, if bsVersion is set to 3.x and yiisoft/yii2-bootstrap is not installed, an exception message will be thrown mentioning you to install the yiisoft/yii2-bootstrap extension.

To install yiisoft/yii2-bootstrap5, add the repo to the require section of your application's composer.json.

"yiisoft/yii2-bootstrap5": "@dev"

To install yiisoft/yii2-bootstrap4, add the repo to the require section of your application's composer.json.

"yiisoft/yii2-bootstrap4": "@dev"

To install yiisoft/yii2-bootstrap, add the repo to the require section of your application's composer.json.

"yiisoft/yii2-bootstrap": "@dev"

Override Bootstrap CSS/JS


The Krajee extension asset bundle(s) by default depend on one of the following asset bundles to load the Bootstrap CSS and JS:

  • yii\bootstrap\BootstrapAsset and/or yii\bootstrap\BootstrapPluginAsset for bootstrap 3.x (bsVersion = 3 setting)

  • yii\bootstrap4\BootstrapAsset and/or yii\bootstrap4\BootstrapPluginAsset for bootstrap 4.x ( bsVersion = 4 setting)

  • yii\bootstrap5\BootstrapAsset and/or yii\bootstrap5\BootstrapPluginAsset for bootstrap 5.x (bsVersion = 5 setting)

This is controlled by the property bsDependencyEnabled within the asset bundle (which defaults to true). One can override this and prevent the default yii2 bootstrap assets (CSS & JS) from loading by doing one or all of the following:

  • Global Override: Set Yii::$app->params['bsDependencyEnabled'] to false in your Yii 2 application config params.php. This setting will be applied for all Krajee Extension Asset Bundles that depend on Bootstrap assets.

    'params' => [
        'bsDependencyEnabled' => false, // this will not load Bootstrap CSS and JS for all Krajee extensions
        // you need to ensure you load the Bootstrap CSS/JS manually in your view layout before Krajee CSS/JS assets
        //
        // other params settings below
        // 'bsVersion' => '5.x',
        // 'adminEmail' => 'admin@example.com'
    ]
    
  • Asset Bundle Specific Override: Set bsDependencyEnabled to false for the specific asset bundle within Yii2 Asset Manager component in your Yii 2 application config file.

    // ...
    'components' => [
        'assetManager' => [
            'bundles' => [
                'kartik\form\ActiveFormAsset' => [
                    'bsDependencyEnabled' => false // do not load bootstrap assets for a specific asset bundle
                ],
            ],
        ],
    ],
    

Note

When setting bsDependencyEnabled to false, you need to ensure that your app code/view layout loads the Bootstrap CSS and JS on your view before the Krajee CSS/JS are loaded to ensure that the Krajee extension JS plugins and CSS styles do not get broken.

Icons for Bootstrap


Bootstrap 5.x / 4.x does not include glyphicons or any other icons framework bundled with the library. Krajee extensions therefore will use Font Awesome 5.x icons instead of glyphicons when working with Bootstrap 5.x / 4.x. You can download Font Awesome 5.x icons from the icons website. Alternatively, you can load the free version of Font Awesome from their CDN.

For Krajee extensions and demos, the Font Awesome Free version is used and loaded as the Icons Display Package on all the Yii2 demo layouts. To include font awesome assets on your page, include the following markup on the HEAD section of your view layout file, when bsVersion is set to 4.x or 5.x.

  • Option 1: Font CSS version of Font Awesome:

    <!-- on your view layout file HEAD section -->
    <link rel="stylesheet" href="https://use.fontawesome.com/releases/v5.3.1/css/all.css">
    
  • Option 2: SVG / JS version of Font Awesome (recommended for cleaner scaling vector icons and features like icon layers):

    <!-- on your view layout file HEAD section -->
    <script defer src="https://use.fontawesome.com/releases/v5.3.1/js/all.js" crossorigin="anonymous"></script>
    

    Alternatively, you can use the FontAwesomeAsset from the kartik-v/yii2-icons package to load the SVG/JS version.

    // on your view layout file
    use kartik\icons\FontAwesomeAsset;
    FontAwesomeAsset::register($this);
    

The yii2-widget-growl extension can be installed automatically or manually using one of these options:

Composer Package Manager Recommended


Installation via Composer is the recommended and most easy option to install Krajee Yii2 extensions. You can install yii2-widget-growl via composer package manager. Either run:

$ php composer.phar require kartik-v/yii2-widget-growl "dev-master"

or add:

"kartik-v/yii2-widget-growl": "dev-master"

to your application's composer.json file.

Manual Install


You may also manually install the extension to your project (in case your composer install does not work). Just download the source ZIP or TAR ball and extract the extension asset files and folders into your project. You may need to install dependencies manually and also set the namespaces to the extensions in your Yii2 extensions configurations manually.

Growl Demo (Configure)


 
 
use kartik\widgets\Growl;

echo Growl::widget([
    'type' => Growl::TYPE_SUCCESS,
    'title' => 'Well done!',
    'icon' => 'fas fa-check-circle',
    'body' => 'You successfully read this important alert message.',
    'showSeparator' => true,
    'delay' => 0,
    'pluginOptions' => [
        'showProgressbar' => true,
        'placement' => [
            'from' => 'top',
            'align' => 'right',
        ]
    ]
]);
echo Growl::widget([
    'type' => Growl::TYPE_INFO,
    'title' => 'Heads up!',
    'icon' => 'fas fa-info-circle',
    'body' => 'This alert needs your attention, but it\'s not super important.',
    'showSeparator' => true,
    'delay' => 1500,
    'pluginOptions' => [
        'showProgressbar' => true,
        'placement' => [
            'from' => 'top',
            'align' => 'right',
        ]
    ]
]);
echo Growl::widget([
    'type' => Growl::TYPE_WARNING,
    'title' => 'Warning!',
    'icon' => 'fas fa-exclamation-circle',
    'body' => 'Better check yourself, you\'re not looking too good.',
    'showSeparator' => true,
    'delay' => 3000,
    'pluginOptions' => [
        'showProgressbar' => true,
        'placement' => [
            'from' => 'top',
            'align' => 'right',
        ]
    ]
]);
echo Growl::widget([
    'type' => Growl::TYPE_DANGER,
    'title' => 'Oh snap!',
    'icon' => 'fas fa-times-circle',
    'body' => 'Change a few things up and try submitting again.',
    'showSeparator' => true,
    'delay' => 4500,
    'pluginOptions' => [
        'showProgressbar' => true,
        'placement' => [
            'from' => 'top',
            'align' => 'right',
        ]
    ]
]);
echo Growl::widget([
    'type' => Growl::TYPE_GROWL,
    'title' => 'Roar!',
    'icon' => '/images/growl_64x.png',
    'body' => 'This is a default growling alert you requested for.',
    'showSeparator' => false,
    'delay' => 6000,
    'pluginOptions' => [
        'icon_type'=>'image',
        'showProgressbar' => false,
        'placement' => [
            'from' => 'top',
            'align' => 'right',
        ],
    ]
]);
echo Growl::widget([
    'type' => Growl::TYPE_MINIMALIST,
    'title' => 'Kartik Visweswaran',
    'icon' => '/images/kartik.png',
    'iconOptions' => ['class'=>'img-circle pull-left'],
    'body' => 'Momentum reduce child mortality effectiveness incubation empowerment connect.',
    'showSeparator' => false,
    'delay' => 7500,
    'pluginOptions' => [
        'icon_type'=>'image',
        'showProgressbar' => false,
        'placement' => [
            'from' => 'top',
            'align' => 'right',
        ],
    ]
]);
echo Growl::widget([
    'type' => Growl::TYPE_PASTEL,
    'title' => 'Email: Erica Fisher',
    'icon' => '/images/growl_64x.png',
    'body' => 'Investment, stakeholders micro-finance equity health Bloomberg; global citizens climate change. ' . 
        'Solve positive social change sanitation, opportunity insurmountable challenges...',
    'showSeparator' => false,
    'delay' => 9000,
    'progressBarOptions' => ['class'=>'progress-bar-warning'],
    'pluginOptions' => [
        'showProgressbar' => true,
        'icon_type'=>'image',
        'placement' => [
            'from' => 'top',
            'align' => 'right',
        ],
    ]
]);
The widget provides a wrapper for the Bootstrap Growl JQuery Plugin . Refer the plugin documentation for more details. The following parameters are important:
  • type: string the type of the growl widget. Defaults to 'alert-info' or Growl::TYPE_INFO. You can select one of the following options:

    • Growl::TYPE_INFO: Sets it to 'alert-info' CSS class.

    • Growl::TYPE_DANGER: Sets it to 'alert-danger' CSS class.

    • Growl::TYPE_SUCCESS: Sets it to 'alert-success' CSS class.

    • Growl::TYPE_WARNING: Sets it to 'alert-warning' CSS class.

    • Growl::TYPE_GROWL: Sets it to 'alert-growl' CSS class. This will display a growl notification similar to ones seen in Apple Mac OS.

    • Growl::TYPE_MINIMALIST: Sets it to 'alert-minimalist' CSS class. Minimalist Notify Notification By Danny Keane.

    • Growl::TYPE_PASTEL: Sets it to 'alert-pastel' CSS class. Simple Pastel Notify Theme By Mark Gilliland.

    • Growl::TYPE_CUSTOM: Use this for setting no style and adding your own custom style. You can pass in any style/class settings to the options to style your alert.

  • icon: string the class name for the icon to be displayed in the title section. If you want to display an image - you can set an image source here and set the icon_type property to image in pluginOptions

  • title: string display a title for the growl (this is not HTML encoded). This will help display a title with a message separator and an optional bootstrap icon. If this is null or not set, it will not be displayed.

  • linkUrl: string the url to redirect to on clicking the alert. If this is null or not set, the alert will not be clickable.

  • linkTarget: string the target to open the linked notification. Defaults to '_blank'.

  • showSeparator: boolean whether to show the title separator. Only applicable if title is set.

  • body: string the alert message body.

  • progressBarOptions: array the HTML attributes for the bootstrap progress bar. You can control the pluginOptions['showProgressBar'] property to show the progress bar. The following special options are recognized:

    • title: string the title text to be displayed within the progress bar. Defaults to empty string. You can set it for example to something like <span class="sr-only">97%<span>

    This defaults to:

    [
        'role' => 'progressbar',
        'aria-valuenow' => '0',
        'aria-valuemin' => '0',
        'aria-valuemax' => '100',
        'style' => '100',
    ]
    
  • delay: integer|boolean time in milliseconds after which each growl is displayed and auto-hidden. If set to 0 or false, it means unlimited delay. This property is slightly different than the pluginOptions['delay'], whereby this property delays the display of each alert as opposed to just delay in fading out.

  • closeButton: array the options for displaying the dismiss or closeButton. This parameter is to be set similar to the closeButton option in Yii Bootstrap Alert Widget.

  • useAnimation: boolean whether to use animation effects. If set to true, will load AnimateAsset asset bundle. Defaults to true

  • iconOptions: array the HTML attributes for the growl icon container.

  • titleOptions: array the HTML attributes for the growl title container.

  • bodyOptions: array the HTML attributes for the growl message body.

  • progressContainerOptions: array the HTML attributes for the progress bar container.

  • linkOptions: array the HTML attributes for the growl url link.

  • pluginOptions: array the bootstrap growl plugin configuration options. Refer the plugin documentation or examples on the options you can set for this plugin.

  • options: array the HTML attributes for the growl alert container.

Note

You can now visit the Krajee Webtips Q & A forum for searching OR asking questions OR helping programmers with answers on these extensions and plugins. For asking a question click here. Select the appropriate question category (i.e. Krajee Plugins) and choose this current page plugin in the question related to field.

The comments and discussion section below are intended for generic discussions or feedback for this plugin. Developers may not be able to search or lookup here specific questions or tips on usage for this plugin.

 
visitors to Krajee Yii2 Demos since 22-May-2017