List.js widget for Yii2

List.js is a handy way of adding searching and sorting to HTML lists and tables. It allows searching trough a list of items with multiple data fields per item. Read more on how it works and try some examples here.

So, for the ones who are interested in using List.js in a Yii2 project, here is a simple widget for it.

Requirements

Yii 2.0 or above

Installation

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

php composer.phar require --prefer-dist nterms/yii2-listjs-widget "*"

or add

"nterms/yii2-listjs-widget": "*"

to the require section of your composer.json file.

Usage

Once the extension is installed, simply use it in your code by :

<?= \nterms\listjs\ListJs::begin([ 
 'id' => 'days-list',
 'search' => true,
 'sort' => [
  'name' => [
   'label' => Yii::t('app', 'Sort by name'),
  ],
 ],
 'clientOptions' => [
  'valueNames' => ['name'],
 ],
]); ?>

<ul class="list">
 <li><div class="name">Sunday</div></li>
 <li><div class="name">Monday</div></li>
 <li><div class="name">Tuesday</div></li>
 <li><div class="name">Wednesday</div></li>
 <li><div class="name">Thursday</div></li>
 <li><div class="name">Friday</div></li>
 <li><div class="name">Saturday</div></li>
</ul>

<?= \nterms\listjs\ListJs::end(); ?>

Configurations

Following properties are available for customizing the widget.

• options: HTML attributes for the container element.
• search: Whether to show the search field.
• searchOptions: HTML attributes (name-value pairs) for the search input tag.
• sort: list of name-value pairs for rendering the sorting buttons list. Value being the HTML attributes for the button. Special parameter label is used as the button text

  ...
  'sort' => [
   'name' => [
    'class' => 'sort',
    'label' => Yii::t('app', 'Sort by name'),
   ],
  ],
  ...
  

• clientOptions: Options for List.js. Read this for list of options.
• content: HTML content, preferably a list or table. If the widget is used in content capturing mode this will be ignored.
• view: Name of the view file to render the content. If the widget is used in content capturing mode or a string is assigned to content property this will be ignored.
• viewParams: Parameters to be passed to view when it is being rendered. This property is used only when view is rendered to generate the content of the widget.

yii2-listjs-widget on github

Validate Yii2 forms before submitting with AJAX

I'm sure the code is much explanatory itself. Here is the solution. This would prevent the form being submitted the usual way while still the client validation is done.

<?php $form = ActiveForm::begin([
        'action' => ['create'],
        'enableAjaxValidation' = false,
        'enableClientValidation' = true,
        'beforeSubmit' => "function(form) {
        
                if($(form).find('.has-error').length) {
                        return false;
                }
                
                $.ajax({
                        url: form.attr('action'),
                        type: 'post',
                        data: form.serialize(),
                        success: function(data) {
                                // do something ...
                        }
                });
                
                return false;
        }",
]); ?>

This old method does not work anymore. Yii2 was updated lately to support more elegant way of handling JavaScript events. Please refer to:
https://github.com/yiisoft/yii2/pull/4955
https://github.com/yiisoft/yii2/issues/1350

Following code shows how you can use JS events to handle the same situation above.

Your php code remains same:

<?php $form = ActiveForm::begin([
        'id' => 'login-form',
        'action' => ['create'],
        'enableAjaxValidation' = false,
        'enableClientValidation' = true,
        
]); ?>

But the JavaScript part goes to a separate .js file:

$(document).ready(
        $('#login-form').on('beforeSubmit', function(event, jqXHR, settings) {
                var form = $(this);
                if(form.find('.has-error').length) {
                        return false;
                }
                
                $.ajax({
                        url: form.attr('action'),
                        type: 'post',
                        data: form.serialize(),
                        success: function(data) {
                                // do something ...
                        }
                });
                
                return false;
        }),
);