The mvcct-controls js module contains:

• basic client side support code for all Mvc Controls Toolkit controls
• specific code for DefaultTagHelpersProvider controls

Further TagHelpersProviders may require addition modules

When using the DefaultTagHelpersProvider you should not call any function contained in this module, but you should just add some of its JavaScript files to your View.

The JavaScript files required by each control are specified in the control documentation. Here we describe just the functionalities of each JavaScript file included in the module, and how to add some customizations.

Ajax utilities contains the documentation of the public interface of some ajax utilities included in the module. While Light router contains the documentation of a light router included in the module. You should not use Light router with DefaultTagHelpersProvider, but it may be usefull in Views using other client controls based TagHelpersProviders, or using other client side frameworks like Knockout.js, Handlebars, etc. that do not have their own routers.

JavaScript files description

mvcct.controls.js

Basic controls event handling, and handlers registration

mvcct.controls.ajax.js

Basic (not jQuery dependent) ajax utilities, needed by Mvc Controls Toolkit, and available also to the developer. They are documented here

mvcct.routing.js

Light router available for the developer. It is documented here

mvcct.controls.serverGrid.js

Server grid specific support JavaScript file. It needs also mvcct.controls.ajax.js, and mvcct.controls.js

mvcct.controls.autocomplete.js

Autocomplete specific support JavaScript file. It needs also and mvcct.controls.js, and awesomplete.js. awesomplete.js is included in the awesomplete module that is a dependency of mvcct-control (thus, it is automatically loaded with it).

mvcct.controls.query.js

Transforms the input provided by query windows in OData format and send them to the server. It acts as an interface between the user interface and the OData library

JavaScript options

It is possible to customize the client side behaviour of specific controls, and also of some foundamental features like validation and removed nodes "cleaning". This is done by specifying properties/subproperties of the mvcct-enhancer options object available in wwwroot/startupjs/startup.js.

JavaScript options of autocomplete

These options are contained in: serverWidgets.autocomplete. This property accepts either an object with all autocomplete options or a function with a single argument that will receive the autocomplete input element (as a node not as a jQuery objects) and that returns the object with all widget options.

removeDiacritics

a function that normalizes strings before comparison. The default function remove all diacritics/accents and converts to lower case.

maxCacheSize

an integer with the maximum cache size. Default size is 40 ie last 40 word suggestions are cached in the web page. Cache is available to several autocomplete of the same type.

JavaScript options of server grid

These options are contained in: serverWidgets.grid. This property accepts an object with all autocomplete options.

onError

a function that is invoked in case of server side processing errors.It receives the error message and is responsible to show it somehow. Default function shows error message with a JavaScript alert. Important this function is invoked just in case of processing errors, validation errors returned by the server are shown as usual.

onStart

a function that is invoked immediately before any ajax operation. It receives as input the Html node that is going to be updated. It can be used to block interaction with the node that is going to change with a js module like blockUI. Default function does nothing.

onCompleted

a function that is invoked immediately after any ajax operation. It receives as input the same Html node passed to onStart. It can be used to remove block activated with onStart. It is invoked also in case of server errors. Default function does nothing.

onProgress

a function that is invoked to report progress of any ajax operation. It is used as onprogres property of the XMLHttpRequest object that performs the ajax call. Thus, it receives an event object with the progress state as its unique argument. Default function does nothing.

options of modal window

As a default detail windows of all controls are shown within a Bootstrap modal. This choice may be changed by providing an options object in serverWidgets.modal.

openModal

the function that is responsible for opening a modal. It is invoked with 3 arguments:

1. content. An html node with the detail window content.
2. id. The id to be used for the topmost modal window container
3. version. a string to insert in the data-version attribute of the topmost modal window container.

Once created the window the implementation is responsible for calling enhancer.transform(x) on the window content, in order to add client side validation and Html5 fallback. The enhancer object is available in the same wwwroot/startupjs/startup.js file that contains the overall options object.

closeModal

the function that is responsible for closing the modal. It receives the topmost window container as its argument.

Customizing ajax options: validation, and nodes cleaning

As a default content is destroyed by calling the jQuery empty function on its father node. This way jQuery data and events are released avoiding memory leaks. In case all widgets used are not jQuery based or in case you would like to add further cleaning you may substitute this setting by providing a different function in ajax.empty. This funtion receives the father node of all elements to delete. Important: At moment jQuery is used just for Bootstrap modal, for unobtrusive validation and for bootstrap-html5-fallback, so if you substitute modal implementation, don't use unobtrusive client validation, and don't use any Html5 fallback or use a not jQuery based fallback, then you may avoid jQuery cleaning.

As a default, controls rely on jQuery unobtrusive client validation, and also server returned errors are attached to standard jQuery error summary and errorl labels. You may substitute completely or partially these settings. All validation settings are contained in the ajax option property:

validateForm

performs client validation of the form that contains the node x received as unique argument.

clearErrors

clear all errors from both error summary and from each specific error label

fieldErrorClass

class applied to all invalid input fields when server errors are returned by an ajax call. It defaults to unobtrusive validation error class: input-validation-error

errorLabelInvalidClass

class applied to all error labels of invalid input fields when server errors are returned by an ajax call. It defaults to unobtrusive validation label error class: field-validation-error

errorLabelValidClass

class applied to all error labels of valid input fields after an ajax call. It defaults to unobtrusive validation valid class: field-validation-valid

errorLabelLocator

a function that given an input field and the form containing it returns the input error label. As a default it returns the standard unobtrusive validation error label associated to the input.

dispatchServerErrors

As a default ajax returned server errors are dispateched as usual client validation errors by using all settings above. You may provide a completely different way of dispatchin these errors (for instance in a modal), by providing a custom dispatchServerErrors. It receives the error list in the following format:

                [
                    ...
                    {
                        prefix: <input field name>
                        errors: ["erro1",..."errorn", ...]
                    }
                    ...
                ]
            

Model level errors have prefix=''. Important: please notice that, in general each field may have several errors associated to it.