Callbacks

# Functions set for handling and rendering the data.
# Others developers can override these methods to tweak At.js such as matcher.
# We can override them in `callbacks` settings.
#
# @mixin
#
# The context of these functions is `$.atwho.Controller` object and they are called in this sequences:
#
# [beforeSave, matcher, filter, remoteFilter, afterMatchFailed, sorter, tplEval, highlighter, beforeReposition, beforeInsert, ]
#
DEFAULT_CALLBACKS =

  # It would be called to restructure the data before At.js invokes `Model#save` to save data
  # In default, At.js will convert it to a Hash Array.
  #
  # @param data [Array] data to refacotor.
  # @return [Array] Data after refactor.
  beforeSave: (data) ->

  # It would be called to match the `flag`.
  # It will match at start of line or after whitespace
  #
  # @param flag [String] current `flag` ("@", etc)
  # @param subtext [String] Text from start to current caret position.
  #
  # @return [String | null] Matched result.
  matcher: (flag, subtext, should_startWithSpace, acceptSpaceBar) ->

  # ---------------------

  # Filter data by matched string.
  #
  # @param query [String] Matched string.
  # @param data [Array] data list
  # @param searchKey [String] at char for searching.
  #
  # @return [Array] result data.
  filter: (query, data, searchKey) ->

  # If a function is given, At.js will invoke it if local filter can not find any data
  #
  # @param params [String] matched query
  # @param callback [Function] callback to render page.
  remoteFilter: null
  # remoteFilter: (query, callback) ->
  #   $.ajax url,
  #     data: params
  #     success: (data) ->
  #       callback(data)

  # Sorter data of course.
  #
  # @param query [String] matched string
  # @param items [Array] data that was refactored
  # @param searchKey [String] at char to search
  #
  # @return [Array] sorted data
  sorter: (query, items, searchKey) ->

  # Eval template for every single item in display list.
  #
  # @param tpl [String] The template string.
  # @param map [Hash] Data map to eval.
  #
  # @return [String] the composed display data
  tplEval: (tpl, map) ->

  # Highlight the `matched query` string.
  #
  # @param li [String] HTML String after eval.
  # @param query [String] matched query.
  #
  # @return [String] highlighted string.
  highlighter: (li, query) ->

  # What to do before inserting item's value into inputor.
  #
  # @param value [String] content to insert
  # @param $li [jQuery Object] the chosen item
  #
  # @return [String] altered content to insert.
  beforeInsert: (value, $li) ->

  # You can adjust the menu's offset here.
  #
  # @param offset [Hash] offset will be applied to menu
  # beforeReposition: (offset) ->
  #   offset.left += 10
  #   offset.top += 10
  #   offset
  beforeReposition: (offset) ->

  # After the `matcher` was failed, which it can't get any query string.
  afterMatchFailed: (at, el) ->