Client API

Application

class App

This is the client side application that’s initialized once the DOM is ready.

If the JSON config script is found in the DOM, it loads the View class with the file name that equals the view_name contained in the JSON config.

The initial startup of the application executes the onPageLoad() and onLoad() functions of the View class and the Middleware.

See configurations below:

Variables:
  • debug (bool) – Default: auto - Print request and response parameters to console. If RequireJS is found then debug is true otherwise false. Override this behavior by setting a value manually.
  • mixins (dict) – Default: {} - Define mixins to execute a single module for multiple views.
  • modules.prefix (str) – Default: '' - Set a prefix for all modules loaded by RequireJS.
  • modules.viewPath (str) – Default: 'views/' - Path to view modules relative to JS root.
  • modules.mixinPath (str) – Default: 'mixins/' - Path to mixin modules relative to JS root.
  • modules.middleware (str) – Default: '' - Name and path of the middleware module relative to JS root.
  • defaults.dateWidget (dict) – Default: {} - Global default datepicker options.
  • defaults.progressBar.animationSpeed (int) – Default: 300 - Time in milliseconds.
  • defaults.dragAndDrop.sortableLib (object) – Default: null - Set the library for drag and drop support.
  • defaults.dragAndDrop.forwardElement (str) – Default: '.glyphicon-forward' - HTML symbol to select all.
  • defaults.dragAndDrop.backwardElement (str) – Default: '.glyphicon-backward' - HTML symbol to deselect all.

Views

class View

This is the base view class all other views extend from. It provides functions to update the view and request views to be displayed in bootstrap modals.

Whenever a view is requested via URL the View.onPageLoad() function is executed. When requestView() or requestModal() is called the View.onAjaxLoad() function is executed. View.onLoad() is always executed but any of those functions can also be omitted.

Variables:
  • Q (object) – Scope of the current view. Use instead of jquery object to avoid conflicts in the DOM. On page load the Q object works the same as the jquery object itself.
  • scopeName (str) – Name of the element defining the current scope.
  • jsonCfg (dict) – Data returned by response.
  • initMiddleware (bool) – Whether the middleware should be executed or not.
  • utils (dict) – Helper functions loaded from Utils module.
  • viewCache (object) – When requestModal() initializes the requested view class it saves the current view instance to viewCache.
  • jsonCache (dict) – Is used to pass data between views when a modal form is closed if changes require custom behavior to update the view below.
  • modalNr (int) – If the current view is displayed in a modal it will increment the count of modals by one.
requestView(viewName='', urlKwargs={}, jsonData={}, pageLoad=False, animate=True)

AJAX request to update the current view. urlKwargs are the parameters used to parse the URL string using django-js-reverse. The jsonData dictionary is the value assigned to json_cfg keyword argument in the query string. It’s value is stringifed so you can pass nested data structures in the request.

If the view class has getUrlKwargs() and/or getJsonData() functions, the parameters they return (as dictionaries) will also be sent to the server. The function arguments will override keyword arguments from getUrlKwargs() and getJsonData().

request view from server

The server side ajaxviews.views.GenericBaseView handles the incoming request and assigns all parameters to the json_cfg variable of the view class.

On request complete will update the client side jsonCfg variable and update the #ajax-content element that’s returned by the response. The View.onAjaxLoad() and View.onLoad() functions are executed as last action of processing the response.

Parameters:
  • viewName (str) – Name mapped to Django’s URL conf. Default is the current view name.
  • urlKwargs (dict) – Keyword arguments passed through URL string.
  • jsonData (dict) – Keyword arguments passed as additional data in request.
  • pageLoad (bool) – If True the request won’t be AJAX but via URL. Used when switching between views with different template layouts.
  • animate (bool) – Animate the ajax content when replaced.
requestSnippet(urlKwargs, jsonData, callback)

AJAX request to retrieve data or html snippets for the current view. The request works the same as requestView() except that the view is not updated automatically on request complete (the callback function is executed instead).

The usual workflow would be to catch the request in the server side get(request, *args, **kwargs) method and return a JsonResponse or HttpResponse to update specific parts of the current view.

Parameters:
  • urlKwargs (dict) – Keyword arguments passed through URL string.
  • jsonData (dict) – Keyword arguments passed as additional data in request.
  • callback (object) – Function that’s called once request is complete.
requestModal(href, jsonData)

Request a view via AJAX and display it in a boostrap modal.

Parameters:
  • href (str) – URL of the view to be opend in modal.
  • jsonData (dict) – Keyword arguments passed as additional data in request.
getUrlKwargs()

Keyword arguments used for URL reverse to parse the URL string.

This function is executed whenever requestView() or requestSnippet() is called.

Returns:dict
getJsonData()

Keyword arguments passed in query string variable json_cfg. It’s data is stringified so that nested data structures can be sent through the request as well.

This function is executed whenever requestView() or requestSnippet() is called.

Returns:dict
onPageLoad()

Executed whenever a view is requested via URL.

onAjaxLoad()

Executed when a view is updated by calling requestView() or when a modal is opened by calling requestModal().

onLoad()

Executed on every request.

onBeforeFormSerialize(form, options)

For form views this function will be executed before the form is serialized.

onBeforeFormSubmit(arr, form, options)

For form views this function will be executed before the form is submitted.

class FilterView(View)

This view offers filter widgets for use with ajaxviews.views.AjaxListView. It expects certain markup in your template to be able to initialize elements automatically.

If a search_field attribute is defined on the server side view class and the input field added in your template using this templatetag {% crispy search_form %}, it will be initialized on page load. This enables the autocomplete function to search for list view entries as it’s registered with autocomplete_ligth.

Table columns with a th[data-filter-index] attribute are clickable to open a bootstrap popover which displays the filter options for the selected field.

Popover filter options

To customize the filter options for a specific field, you can catch the json_cfg['filter_index'] in the server side GET request method and return a html snippet which will be inserted in the .popover-content node.

The filter_index is used to retrieve filter options for a specific field and selected_filter_index and selected_filter_values are used to apply the filter options on the queryset when using ajaxviews.queries.AjaxQuerySet.

When including {% include 'ajaxviews/_table_sort.html' with index=<int> %} in your table headers, set the index to specify the field where either asc or desc ordering is applied.

Utils

Utils

Built-in functions available for use in the View class through the utils attribute.

Returns:dictionary containing the functions listed below.

Initialize all elements with a .modal-link class to be opened in a modal.

Those elements require a href attribute that points to a detail or form view extending from server side ajaxviews.views module.

Parameters:scope (str) – Element in which all modal links are initialized.
initDateInput(element, opts={})

Initialize the input element using the default date widget options from the App config. opts overrides the defaults.

Parameters:
  • element (object) – Date input field.
  • opts (dict) – Options to pass to the widget.
initDragAndDrop()

Initialize drag and drop fields using the Sortable JS library.

Include the _drag_drop.html template with following context parameters to enable drag and drop support for multiple choice fields.

  • field_id: Name used for the hidden input elements.
  • available_name: Header name of available choices.
  • available_list: List of available model instances.
  • selected_name: Header name of selected choices.
  • selected_list: List of selected model instances.
updateMultipleHiddenInput()

Update hidden input elements which are used to submit selected values for multiple select fields. This works for form views which are using drag and drop support to select multiple values.

A .drag-and-drop element with a data attribute field is expected. The field name is used to set the name attribute of the hidden input elements.

initDeleteConfirmation()

Initialize a confirmation popover on .delete-btn[data-toggle=confirmation] buttons using bootstrap-confirmation2 JS library.

initChosenWidget()

Initialize select fields with a .chosen-widget class using the chosen JS library.

Middleware

Middleware

The middleware module provides functions that are hooked into the view class on every request.

If you have not created a class for the requested view, the middleware will be hooked into the base view which will be executed for all requests.

Returns:dictionary containing the functions listed below.
onPageLoad()

Executed whenever a view is requested via URL.

onAjaxLoad()

Executed when a view is updated by calling View.requestView() or when a modal is opened by calling View.requestModal().

onLoad()

Executed on every request.

onListLoad()

Only executed for list views.

onDetailLoad()

Only executed for detail views.

onFormLoad()

Only executed for form views.