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 Dialog::bsVersion property is set, in addition to Yii::$app->params['bsVersion'], the extension level setting (Dialog::bsVersion property) will override the Yii::$app->params['bsVersion']. If Dialog::bsVersion property is not set, and Yii::$app->params['bsVersion'] is also not set, Dialog::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
              ],
          ],
      ],
  ],
  

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);
  

Composer Package Manager Recommended

---

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

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

or add:

"kartik-v/yii2-dialog": "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.

bsVersion

string | int, the bootstrap library version to be used for the extension. Refer the Bootstrap Info section for details and pre-requisites on setting this property.

• To use with Bootstrap library - you can set this to any string starting with 3 (e.g. 3 or 3.3.7 or 4.x / 3.x)

• To use with bootstrap 4 - you can set this to any string starting with 4 (e.g. 4 or 4.6.0 or 4.x)

• To use with bootstrap 5 - you can set this to any string starting with 4 (e.g. 5 or 5.1.0 or 5.x)

bsColCssPrefixes

array, the bootstrap grid column css prefixes mapping, the key is the bootstrap versions, and the value is an array containing the sizes and their corresponding grid column css prefixes. The class using this trait, must implement kartik\base\BootstrapInterface. If not set will default to:.

[
   3 => [
      self::SIZE_X_SMALL => 'col-xs-',
      self::SIZE_SMALL => 'col-sm-',
      self::SIZE_MEDIUM => 'col-md-',
      self::SIZE_LARGE => 'col-lg-',
      self::SIZE_X_LARGE => 'col-lg-',
      self::SIZE_XX_LARGE => 'col-lg-',
   ],
   4 => [
      self::SIZE_X_SMALL => 'col-',
      self::SIZE_SMALL => 'col-sm-',
      self::SIZE_MEDIUM => 'col-md-',
      self::SIZE_LARGE => 'col-lg-',
      self::SIZE_X_LARGE => 'col-xl-',
      self::SIZE_XX_LARGE => 'col-xl-',
   ],
   5 => [
      self::SIZE_X_SMALL => 'col-',
      self::SIZE_SMALL => 'col-sm-',
      self::SIZE_MEDIUM => 'col-md-',
      self::SIZE_LARGE => 'col-lg-',
      self::SIZE_X_LARGE => 'col-xl-',
      self::SIZE_XX_LARGE => 'col-xxl-',
   ],
];

useNative

boolean, whether to use the native javascript dialog for rendering the popup prompts. If set to false, the bootstrap3-dialog library will be used for rendering the prompts as a modal dialog. Defaults to false.

showDraggable

boolean, whether to show a draggable cursor for draggable dialog boxes when dragging. Defaults to true.

libName

boolean, the identifying name of the public javascript variable that will hold the settings for KrajeeDialog javascript object instance. Defaults to krajeeDialog. You can override this to a different name in case you want multiple dialog library instance settings on the same page.

i18n

array, the internalization configuration for this module. Defaults to:

[
    'class' => 'yii\i18n\PhpMessageSource',
    'basePath' => '@kvdialog/messages',
    'forceTranslation' => true
]

options

array the configuration options for the bootstrap3-dialog plugin (applicable when useNative is false). You can set the plugin configuration settings here as key value pairs that can be recognized by the bootstrap3-dialog plugin.

jsPosition

array, the javascript position where KrajeeDialog global variables will be initialized. Defaults to View::POS_HEAD.

dialogDefaults

array, the configuration options to be setup as defaults for the bootstrap dialog (applicable when useNative is false). This defaults to the following configuration:

[
    Dialog::DIALOG_ALERT => [
        'type' => Dialog::TYPE_INFO,
        'title' => Yii::t('kvdialog', 'Information'),
        'buttonLabel' => Dialog::ICON_OK . ' ' . Yii::t('kvdialog', 'Ok')
    ],
    Dialog::DIALOG_CONFIRM => [
        'type' => Dialog::TYPE_WARNING,
        'title' => Yii::t('kvdialog', 'Confirmation'),
        'btnOKClass' => 'btn-warning',
        'btnOKLabel' => Dialog::ICON_OK . ' ' . Yii::t('kvdialog', 'Ok'),
        'btnCancelLabel' => Dialog::ICON_CANCEL . ' ' . Yii::t('kvdialog', 'Cancel')
    ],
    Dialog::DIALOG_PROMPT => [
        'draggable' => false,
        'title' => Yii::t('kvdialog', 'Information'),
        'buttons' => [
            [
                'label' => Yii::t('kvdialog', 'Cancel'),
                'icon' => Dialog::ICON_CANCEL
            ],
            [
                'label' => Yii::t('kvdialog', 'Ok'),
                'icon' => Dialog::ICON_OK,
                'class' => 'btn-primary'
            ],
        ]
    ],
    Dialog::DIALOG_OTHER => [
        'draggable' => true,
        'closable' => false,
        'title' => Yii::t('kvdialog', 'Information'),
        'buttons' => [
            [
                'label' => Yii::t('kvdialog', 'Cancel'),
                'icon' => Dialog::ICON_CANCEL
            ],
            [
                'label' => Yii::t('kvdialog', 'Ok'),
                'icon' => Dialog::ICON_OK,
                'class' => 'btn-primary'
            ],
        ]
    ],
]

The dialogDefaults must be setup as $key => $setting pairs, where:

$key, string, is one of the following dialog types:

• Dialog::DIALOG_ALERT or 'alert'

• Dialog::DIALOG_CONFIRM or 'confirm'

• Dialog::DIALOG_PROMPT or 'prompt'

• Dialog::DIALOG_OTHER or 'dialog'

$setting, array, consists of the following property settings for each of the above dialog types:

• type: string, one of the bootstrap contextual color types for the bootstrap3-dialog. You can use one of these preconfigured types:

  • Dialog::TYPE_DEFAULT or 'type-default'

  • Dialog::TYPE_PRIMARY or 'type-primary'

  • Dialog::TYPE_SUCCESS or 'type-success'

  • Dialog::TYPE_DANGER or 'type-danger'

  • Dialog::TYPE_WARNING or 'type-warning'

  • Dialog::TYPE_INFO or 'type-info'

• title: string, the title heading for the dialog box.

• buttonLabel: string, the OK button label (applicable only for Dialog::TYPE_ALERT). Defaults to:

  • <i class="glyphicon glyphicon-ok"></i> Ok for Bootstrap 3.x.

  • <i class="fas fa-check"></i> Ok for Bootstrap 5.x / 4.x.

• btnOKClass: string, the CSS class for the OK button (applicable only for Dialog::TYPE_CONFIRM). Defaults to btn-warning.

• btnOKLabel: string, the OK button label (applicable only for Dialog::TYPE_CONFIRM).. Defaults to:

  • <i class="glyphicon glyphicon-ok"></i> Ok for Bootstrap 3.x.

  • <i class="fas fa-check"></i> Ok for Bootstrap 5.x / 4.x.

• btnCancelLabel: string, the Cancel button label (applicable only for Dialog::TYPE_CONFIRM). This defaults to:

  • <i class="glyphicon glyphicon-ban-circle"></i> Cancel for Bootstrap 5.x / 4.x / 3.x.

  • <i class="fas fa-ban"></i> Cancel for Bootstrap 5.x / 4.x.

• draggable: bool, whether the dialog box is draggable (applicable only for Dialog::DIALOG_PROMPT and Dialog::DIALOG_OTHER). Defaults to false for Dialog::DIALOG_PROMPT and true for Dialog::DIALOG_OTHER.

• closable: bool, whether the dialog box is closable (applicable only for Dialog::DIALOG_PROMPT and Dialog::DIALOG_OTHER). Defaults to true for Dialog::DIALOG_PROMPT and false for Dialog::DIALOG_OTHER.

• buttons: array, the configuration of buttons shown in the dialog box (applicable only for Dialog::DIALOG_PROMPT and Dialog::DIALOG_OTHER). Defaults to the following configuration:

  [
      [
          'label' => Yii::t('kvdialog', 'Cancel'),
          'icon' => Dialog::ICON_CANCEL
      ],
      [
          'label' => Yii::t('kvdialog', 'Ok'),
          'icon' => Dialog::ICON_OK,
          'class' => 'btn-primary'
      ],
  ]
  

Alert

The alert method of the plugin works similar to a native Javascript alert. It takes in the following parameters:

• message: string: The message to be displayed within the alert dialog box. Other settings for the alert dialog box can be configured via dialogDefaults property of the Dialog widget.

// JS Code
krajeeDialog.alert("Hold On! This is a Krajee alert!");

Confirm

The confirm method of the plugin works similar to a native Javascript confirm, but with a callback option. It takes in the following parameters:

• message: string: The message to be displayed within the confirm dialog box. Other settings for the confirm dialog box can be configured via dialogDefaults property of the Dialog widget.

• callback: function: The function to execute on confirmation (i.e. when OK button is pressed). Other settings for the confirm dialog box can be configured via dialogDefaults property of the Dialog widget.

// JS Code
krajeeDialog.confirm("Are you really sure you want to do this?", function (result) {
    if (result) { // ok button was pressed
        // execute your code for confirmation
    } else { // confirmation was cancelled
        // execute your code for cancellation
    }
});

Prompt

The prompt method of the plugin works similar to a native Javascript prompt, but with a callback option. It takes in the following parameters:

• content: string|object: If set as a string, it is treated as a raw HTML content that will be directly displayed. Typically this is setup as a object containing of the prompt input label and placeholder properties, for example:

  {label:'Provide reason', placeholder:'Upto 30 characters...'}
  

  Other settings for the prompt dialog box can be configured via dialogDefaults property of the Dialog widget.

• callback: function: The function to execute on confirmation (i.e. when OK button is pressed). Other settings for the prompt dialog box can be configured via dialogDefaults property of the Dialog widget.

// JS Code
krajeeDialog.prompt({label:'Provide reason', placeholder:'Upto 30 characters...'}, function (result) {
    if (result) { // ok button was pressed
        // execute your code on prompt confirmation
    } else { // prompt dialog was cancelled
        // execute your code for cancellation
    }
});

Dialog

The dialog method of the plugin can be used for generating other custom dialogs via BootstrapDialog.show. It takes in the following parameters:

• content: string|object: If set as a string, it is treated as a raw HTML content that will be directly displayed. Typically this is setup as a object containing of the dialog input label and placeholder properties, for example:

  {label:'Provide reason', placeholder:'Upto 30 characters...'}
  

  Other settings for the dialog box can be configured via dialogDefaults property of the Dialog widget.

• callback: function: The function to execute on confirmation (i.e. when OK button is pressed). Other settings for the dialog box can be configured via dialogDefaults property of the Dialog widget.

// JS Code
krajeeDialog.dialog('This is a custom dialog', function (result) {
    if (result) { // ok button was pressed
        // execute your code on dialog confirmation
    } else { // dialog dialog was cancelled
        // execute your code for cancellation
    }
});

Basic Usage

For a very simple usage, you can load the asset bundle in your view and render the javascript to load the Bootstrap library modal dialog.

// view.php
use kartik\dialog\DialogAsset;
DialogAsset::register($this);
$this->registerJs("$('#your-btn-id').on('click', function(){BootstrapDialog.alert('I want banana!');});");

Advanced Usage

For advanced usage (recommended), you can render the Dialog widget in your view or view layout file as shown below. As mentioned earlier, this will not display any content directly - but will rather render all the JS and CSS needed for initializing the BootstrapDialog as per your customized settings.

use kartik\dialog\Dialog;

// Example 1: Default krajeeDialog object
echo Dialog::widget([
   'options' => [], // default options
]);

// Example 2: Custom krajeeDialogCust object
echo Dialog::widget([
   'libName' => 'krajeeDialogCust', // optional if not set will default to `krajeeDialog`
   'options' => ['draggable' => true, 'closable' => true], // custom options
]);

Then in your view, you can write your own javascript to render your alert, confirm, and prompt boxes (or a custom dialog box). For example on click of HTML buttons btn-1 and btn-2, the dialogs can be popped up as shown below:

// NOTE: This is a javascript code and must be run in Yii via 'registerJs' or via a JS File in an AssetBundle

// use krajeeDialog object instance initialized by the widget
$('#btn-1').on('click', function() {
    krajeeDialog.alert('An alert');
    // or show a confirm
    krajeeDialog.confirm('Are you sure', function(out){
        if(out) {
            alert('Yes'); // or do something on confirmation
        }
    });
});

// use krajeeDialogCust object instance as in the Widget Example 2 above
$('#btn-2').on('click', function() {
    krajeeDialogCust.alert('An alert');
    // or show a prompt
    krajeeDialogCust.prompt({label:'Provide reason', placeholder:'Upto 30 characters...'}, function(out){
        if (out) {
            alert('Yes'); // or do something based on the value of out
        }
    });
});