DetailView yii2-detail-view   Tips

Latest Stable Version Latest Unstable Version Total Downloads Monthly Downloads Daily Downloads
Thankful to Krajee!
to get more out of us.

NOTE: This extension depends on the kartik-v/yii2-krajee-base extension which in turn depends on the yiisoft/yii2-bootstrap extension. Check the composer.json for this extension's requirements and dependencies that may be updated by composer.

An extended Yii2 DetailView with many additional features. Extends the Yii DetailView to work in both VIEW and EDIT modes. Accelerates your development by using a single configuration of attributes for both VIEW and EDIT. The extension also includes easier methods to style your detail view widget cells, data, form inputs, widgets, and columns (more specifically for Bootstrap 3). The widget by default can be styled within a Bootstrap 3 panel with a buttons toolbar to toggle modes and control your data. View a complete demo.

Note

The preferred way to install this extension is through composer. Either run:

$ php composer.phar require kartik-v/yii2-detail-view "*"

or add:

"kartik-v/yii2-detail-view": "*"

to the require section of your composer.json file. Then run:

php composer.phar update

to get the updated package on your application install.

The DetailView widget contains various enhancements to the yii\widgets\DetailView.

Note

The extension includes a BC Breaking change with v1.7.0. With this release, the template property of the yii core DetailView is not anymore supported. One can use rowOptions, labelColOptions, valueColOptions at the widget level or widget attributes level to configure advanced layout functions.

You can configure the following settings in this widget:

mode

string, the mode in which you open the detail view by default. Defaults to DetailView::MODE_VIEW. Should be one of the following values:

  • DetailView::MODE_VIEW or 'view'

  • DetailView::MODE_EDIT or 'edit'

bootstrap

boolean, whether the detail view will have a Bootstrap table styling. Defaults to true. If set to false, will automatically disable/remove all Bootstrap specific markup from the detail view table and filters.

bordered

boolean, whether the detail view table will have a bordered style. Applicable only if bootstrap is true. Defaults to true.

striped

boolean, whether the detail view table will have a striped style. Applicable only if bootstrap is true. Defaults to true.

condensed

boolean, whether the detail view table will have a condensed style. Applicable only if bootstrap is true. Defaults to false.

responsive

boolean, whether the detail view table will have a responsive style. Applicable only if bootstrap is true. Defaults to true.

hover

boolean, whether the detail view table will highlight row on hover. Applicable only if bootstrap is true. Defaults to false.

enableEditMode

boolean, whether to allow editing for the detail view. Defaults to true.

hideIfEmpty

boolean, whether to hide rows in view mode if value is null or empty. Defaults to false.

tooltips

boolean, whether to display bootstrap style tooltips for titles on hover of buttons. Defaults to true.

krajeeDialogSettings

array, the configuration of Krajee Yii2 Dialog widget that will be used to render the confirmation dialogs and alerts. Refer the Krajee Dialog documentation for details.

fadeDelay

integer, the fade animation delay in microseconds when toggling between the view and edit modes.

hAlign

string, the horizontal alignment of the label column. Should be one of DetailView ALIGN constants as mentioned below.

  • DetailView::ALIGN_RIGHT or 'right'

  • DetailView::ALIGN_CENTER or 'center'

  • DetailView::ALIGN_LEFT or 'left'

vAlign

string, the vertical alignment of the label column. Should be one of DetailView ALIGN constants as mentioned below.

  • DetailView::ALIGN_TOP or 'top'

  • DetailView::ALIGN_MIDDLE or 'middle'

  • DetailView::ALIGN_BOTTOM or 'bottom'

rowOptions

array, the HTML attributes for the attribute row.

labelColOptions

array, the HTML attributes for the label column. Defaults to ['style' => 'width: 20%'].

valueColOptions

array, the HTML attributes for the value column.

hideAlerts

boolean, whether to hide all alerts. Defaults to false.

notSetIfEmpty

boolean, whether to show values as not set if empty string. Defaults to false.

alertContainerOptions

array, the HTML attributes for the alert block container which will display any alert messages received on update or delete of record. This will automatically not be displayed if there are no alert message blocks inside the container.

alertWidgetOptions

array, the widget settings for each bootstrap alert displayed in the alert container block. The CSS class in options within this will be auto derived and appended.

  • For update, which you trigger on pressing the save button, error messages will be displayed based on flash message settings via Yii::$app->session->setFlash. The CSS class for the error block will be auto-derived based on flash message type using alertMessageSettings.

  • For ajax delete which you trigger on pressing the delete button, error messages will be displayed based on the ajax response. The ajax response should be an object that contains the following:

    • success: boolean, whether the ajax delete was successful.

    • messages: array, the list of messages to display as key value pairs. The key must be one of the message keys in the alertMessageSettings, and the must be the message content to be displayed.

alertMessageSettings

array, the flash message settings which will be set as $key => $value, where:

  • $key: flash message key that you typically set via Yii::$app->session->setFlash e.g. kv-detail-success, kv-detail-error.

  • $value: CSS class for the flash message e.g. alert alert-danger, alert alert-success.

This defaults to the following setting:

[
    'kv-detail-error' => 'alert alert-danger',
    'kv-detail-success' => 'alert alert-success',
    'kv-detail-info' => 'alert alert-info',
    'kv-detail-warning' => 'alert alert-warning'
]

options

array, the HTML attributes for the detail view table.

container

array, the HTML attributes for the widget container.

formOptions

array, the configuration settings for the ActiveForm widget that will be used to edit the attributes. Read the Yii ActiveForm documentation for widget configuration details.

formClass

string, the class name for the ActiveForm widget. Defaults to yii\widgets\ActiveForm. You can override this at widget level to use other ActiveForm widget extending from yii\widgets\ActiveForm. For example, you can set this to kartik\widgets\ActiveForm or kartik\widgets\ActiveForm to use enhanced features of Krajee ActiveForm.

attributes

array, the most important part of this widget configuration, this is a list of attributes to be displayed in the detail view. Each array element represents the specification for displaying one particular attribute. All these attribute settings from the yii\widgets\DetailView are supported.

Note

All of the attribute array properties mentioned below can also be setup as a Closure callback, that will return the value matching the data type. The callback must be of the following signature:

function ($form, $widget) { }, where:

  • $form: ActiveForm, is the current active form object in the detail view.

  • $widget: DetailView, is the current detail view widget instance.

  • attribute: string|Closure, the attribute name. This is required if either label or value is not specified.

  • label: string|Closure, the label associated with the attribute. If this is not specified, it will be generated from the attribute name.

  • value: string|Closure, the value to be displayed. If this is not specified, it will be retrieved from model using the attribute name by calling ArrayHelper::getValue(). Note that this value will be formatted into a displayable text according to the format option.

  • format: string|Closure, the type of the value that determines how the value would be formatted into a displayable text. Please refer to Formatter for supported types.

  • visible: boolean|Closure, whether the attribute is visible. If set to false, the attribute will NOT be displayed.

The additional attribute settings that are supported in this enhanced widget are:

  • columns: array|Closure, the configuration of multiple attributes in the same row. Each element, will be configured as an array similar to the attributes setting. When this is set, the label or value or attribute setting is entirely skipped. For example the following code will separate the row into 2 different columns for the 2 attributes set as shown below:

    'columns' => [
        [
            'attribute'=>'publish_date', 
            'format'=>'date',
            'type'=>DetailView::INPUT_DATE,
            'widgetOptions' => [
                'pluginOptions'=>['format'=>'yyyy-mm-dd']
            ],
            'valueColOptions'=>['style'=>'width:30%']
        ],
        [
            'attribute'=>'status', 
            'label'=>'Available?',
            'format'=>'raw',
            'value'=>$model->status ? '<span class="label label-success">Yes</span>' : '<span class="label label-danger">No</span>',
            'type'=>DetailView::INPUT_SWITCH,
            'widgetOptions' => [
                'pluginOptions' => [
                    'onText' => 'Yes',
                    'offText' => 'No',
                ]
            ],
            'valueColOptions'=>['style'=>'width:30%']
        ],
    ]
    
  • rowOptions: array|Closure, HTML attributes for the row (if not set, will default to the rowOptions set at the widget level).

  • labelColOptions: array|Closure, HTML attributes for the label column (if not set, will default to the labelColOptions set at the widget level).

  • valueColOptions: array|Closure, HTML attributes for the value column (if not set, will default to the valueColOptions set at the widget level).

  • group: boolean|Closure, whether to group the selection by merging the label and value into a single column. Defaults to false.

  • groupOptions: array|Closure, HTML attributes for the grouped/merged column when group is set to true.

    Tip

    The widget includes prebuilt CSS Classes for hiding sections for view or edit modes. You can add the CSS classes kv-view-hidden or kv-edit-hidden to hide content for view or edit mode respectively. You can add these CSS classes typically through rowOptions, labelColOptions, valueColOptions, or groupOptions. In addition, you can also directly use these CSS classes in any of your other raw markup to achieve advanced use cases (e.g. changing a label display for View and Edit modes).
  • type: string|Closure, the input type for rendering the attribute in edit mode. If not provided, this defaults to DetailView::INPUT_TEXT. All common input types are supported including widgets. This should be one of the following:

    Inputs

    • DetailView::INPUT_HIDDEN or 'hiddenInput'

    • DetailView::INPUT_TEXT or 'textInput'

    • DetailView::INPUT_PASSWORD or 'passwordInput'

    • DetailView::INPUT_TEXTAREA or 'textArea'

    • DetailView::INPUT_CHECKBOX or 'checkbox'

    • DetailView::INPUT_RADIO or 'radio'

    • DetailView::INPUT_LIST_BOX or 'listBox'

    • DetailView::INPUT_DROPDOWN_LIST or 'dropDownList'

    • DetailView::INPUT_CHECKBOX_LIST or 'checkboxList'

    • DetailView::INPUT_RADIO_LIST or 'radioList'

    • DetailView::INPUT_HTML5_INPUT or 'input'

    • DetailView::INPUT_FILE or 'fileInput'

    • DetailView::INPUT_WIDGET or 'widget', use this for any custom widget class to be used

    Widgets

    • DetailView::INPUT_DEPDROP or '\kartik\widgets\DepDrop'

    • DetailView::INPUT_SELECT2 or '\kartik\widgets\Select2'

    • DetailView::INPUT_TYPEAHEAD or '\kartik\widgets\Typeahead'

    • DetailView::INPUT_SWITCH or '\kartik\widgets\Switch'

    • DetailView::INPUT_SPIN or '\kartik\widgets\TouchSpin'

    • DetailView::INPUT_STAR or '\kartik\widgets\StarRating'

    • DetailView::INPUT_DATE or '\kartik\widgets\DatePicker'

    • DetailView::INPUT_TIME or '\kartik\widgets\TimePicker'

    • DetailView::INPUT_DATETIME or '\kartik\widgets\DateTimePicker'

    • DetailView::INPUT_RANGE or '\kartik\widgets\RangeInput'

    • DetailView::INPUT_COLOR or '\kartik\widgets\ColorInput'

    • DetailView::INPUT_RATING or '\kartik\widgets\StarRating'

    • DetailView::INPUT_FILEINPUT or '\kartik\widgets\FileInput'

    • DetailView::INPUT_SLIDER or '\kartik\slider\Slider'

    • DetailView::INPUT_MONEY or '\kartik\money\MaskMoney'

  • displayOnly: boolean|Closure, if the input is to be set to as display only in edit mode. If set to true, no editable form input will be displayed, instead this will display the formatted attribute value.

  • widgetOptions: array, the widget configuration options when you set type to DetailView::INPUT_WIDGET OR when you set type to one of the INPUT widgets from \kartik\widgets. The following special options are recognized when you set type to DetailView::INPUT_WIDGET:

    • class: string, the fully namespaced widget class.

  • items: array|Closure, the list of data items if type is one of dropDownList, listBox, checkboxList & radioList.

  • inputContainer: array|Closure, the HTML attributes for the container enclosing the input. This property can be used to include bootstrap grid column classes to size the input responsively across device sizes. For example:

    [
        'attribute'=>'author_id',
        'inputContainer' => ['class'=>'col-sm-6'] 
        // will automatically enclose above within '<div class="row">'
    ],
    
  • inputWidth: string|Closure, the width of the container holding the input, should be appended along with the width unit (px or %). NOTE: This property is deprecated since v1.7.1 and will be removed in future releases. Use inputContainer to control HTML attributes for the container enclosing the input.

  • inputType: string|Closure, the HTML 5 input type if type is set to DetailView::INPUT_HTML5_INPUT.

  • fieldConfig: array|Closure, optional, the Active field configuration.

  • options: array|Closure, optional, the HTML attributes for the input.

  • updateAttr: string|Closure, optional, the name of the attribute to be updated, when in edit mode (if you do not want it to be same as attribute. If not provided, this will default to the attribute setting.

  • updateMarkup: string|Closure, the raw markup to render in edit mode. If not set, this normally will be automatically generated based on attribute or updateAttr setting. If this is set it will override the default markup. For example one can set this to generate multiple address fields like below:

    'attributes' => [
        [
            'attribute' => 'address',
            'updateMarkup' => function($form, $widget) {
                $model = $widget->model;
                return $form->field($model, 'address') . '<br>' . 
                        $form->field($model, 'city') . '<br>' .
                        $form->field($model, 'province') . '<br>' .
                        $form->field($model, 'zip');
            }
        ]
    ]
    

panel

array, the panel settings. If this is set, the detail view widget will be embedded in a Bootstrap panel. Applicable only if bootstrap is true. The following array keys are supported:

  • heading: string | boolean, the panel heading title value. If set to false, the entire heading will be not displayed. Note that the {title} tag in the headingOptions['template'] will be replaced with this value.

  • headingOptions: array, the HTML attributes for the panel heading. Defaults to ['class'=>'panel-title']. The following additional special options are available:

    • tag: string, the tag to render the heading title. Defaults to h3.

    • template: string,the template to render the heading. Defaults to {buttons}{title}, where:.

      • {title} will be replaced with the panel['heading'] value.

      • {buttons} will be replaced by the rendered buttons toolbar.

  • type: string, the Bootstrap contextual color type. Should be one of the DetailView TYPE constants below. If not set will default to default or self::TYPE_DEFAULT.

    • DetailView::TYPE_DEFAULT or 'default'

    • DetailView::TYPE_PRIMARY or 'primary'

    • DetailView::TYPE_INFO or 'info'

    • DetailView::TYPE_DANGER or 'danger'

    • DetailView::TYPE_WARNING or 'warning'

    • DetailView::TYPE_SUCCESS or 'success'

  • footer: string, the panel footer title value. Defaults to false. If set to false, the entire footer will be not displayed. Note that the {title} tag in the footerOptions['template'] will be replaced with this value.

  • footerOptions: array, the HTML attributes for the panel footer. Defaults to ['class'=>'panel-title']. The following additional special options are available:

    • tag: string, the tag to render the footer title. Defaults to h4.

    • template: string,the template to render the footer. Defaults to {title}, where:.

      • {title} will be replaced with the panel['footer'] value.

      • {buttons} will be replaced by the rendered buttons toolbar.

mainTemplate

string, the main template to render the detail view. Defaults to {detail}. The following tags will be replaced:

  • {detail}: will be replaced by the rendered detail view

  • {buttons}: the buttons to be displayed as set in buttons1 and buttons2.

buttonContainer

array, the HTML attributes for the button toolbar container.

buttons1

string, the buttons to show when in view mode. Defaults to {update} {delete}. By default this is displayed on the top right part of the panel. The following tags will be replaced:

  • {view}: the view button.

  • {update}: the update button.

  • {delete}: the delete button.

  • {save}: the save button.

  • {reset}: the form reset button.

buttons2

string, the buttons to show when in edit mode. Defaults to {view} {reset} {save}. By default this is displayed on the top right part of the panel. The following tags will be replaced:

  • {view}: the view button.

  • {update}: the update button.

  • {delete}: the delete button.

  • {save}: the save button.

  • {reset}: the form reset button.

viewAttributeContainer

array, the HTML attributes for the container displaying the VIEW mode attributes.

editAttributeContainer

array, the HTML attributes for the container displaying the EDIT mode attributes.

viewButtonsContainer

array, the HTML attributes for the container displaying the VIEW mode buttons.

editButtonsContainer

array, the HTML attributes for the container displaying the EDIT mode buttons.

viewOptions

array, HTML attributes for the view button. The following additional option is recognized:

  • label: string, the label for the view action button. This is not html encoded. Defaults to '<span class="glyphicon glyphicon-eye-open"></span>.

updateOptions

array, HTML attributes for the update button. The following additional option is recognized:

  • label: string, the label for the update action button. This is not html encoded. Defaults to '<span class="glyphicon glyphicon-pencil"></span>.

deleteOptions

array, HTML attributes for the delete button. The following additional options are recognized:

  • label: string, the label for the delete action button. This is not html encoded. Defaults to '<span class="glyphicon glyphicon-trash></span>.

  • url: string, the delete action url. If not set will default to `#`.

  • params: array, the parameters to be passed to the delete ajax action as key - value pairs.

  • confirm: string, the confirmation alert dialog message before triggering delete. Defaults to Yii::t('kvdetail', 'Are you sure you want to delete this item?').

  • ajaxSettings: array, the ajax settings if you choose to override or append to the delete ajax settings. See the jQuery ajax options documentation for details.

saveOptions

array, HTML attributes for the save button. This will default to a form submit button. The following additional option is recognized:

  • label: string, the label for the save action button. This is not html encoded. Defaults to '<span class="glyphicon glyphicon-floppy-disk"></span>.

resetOptions

array, HTML attributes for the reset button. This will default to a form reset button. The following additional option is recognized:

  • label: string, the label for the reset action button. This is not html encoded. Defaults to '<span class="glyphicon glyphicon-ban-circle"></span>.

i18n

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

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

Basic Usage

use kartik\detail\DetailView;
echo DetailView::widget([
    'model'=>$model,
    'condensed'=>true,
    'hover'=>true,
    'mode'=>DetailView::MODE_VIEW,
    'panel'=>[
        'heading'=>'Book # ' . $model->id,
        'type'=>DetailView::TYPE_INFO,
    ],
    'attributes'=>[
        'code',
        'name',
        ['attribute'=>'publish_date', 'type'=>DetailView::INPUT_DATE],
    ]
]);

Advanced Usage

Refer the detail view demo page for viewing a complete demo. The following example uses the demo configuration to display the detail view within a modal window.

use yii\bootstrap\Modal;
Modal::begin([
    'header' => '<h4 class="modal-title">Detail View Demo</h4>',
    'toggleButton' => ['label' => '<i class="glyphicon glyphicon-th-list"></i> Detail View in Modal', 'class' => 'btn btn-primary'],
    'options' => ['tabindex' => false]
]);
echo DetailView::widget($settings); // refer the demo page for widget settings
Modal::end();

yii2-detail-view is released under the BSD 3-Clause License. See the bundled LICENSE.md for details.