Consider exposing normalizeUIString

[bazineta]

While the 3.x UIMixin exposes normalizeUIKeys and normalizeUIValues, normalizeUIString is private.

As an example below, a shim to provide @ui functionality to backbone.stickit, so that @ui values may be used in stickit automatic bindings, via the 'bindings' hash, and via manual binding, using addBinding().

(I've kept the shim in CS as I think it reads a bit more clearly; apologies to those who require therapy after viewing such things.)

As addBinding() can take a string as well as a hash, it's necessary to translate @ui strings as well as @ui hashes. As such, there's no alternative but to copy what Mn does internally in this case.

If normalizeUIString were exposed in the same manner that the other two normalize functions are, e.g.,

 normalizeUIString: function normalizeUIKeys(string) {
      var uiBindings = this._getUIBindings();
      return _normalizeUIString(string, uiBindings);
    }

Then this particular use case could be handled without duplicating private function.

#-----------------------------------------------------------------------------#
# Imports
#-----------------------------------------------------------------------------#

_          = require 'lodash'
Marionette = require 'backbone.marionette'

#-----------------------------------------------------------------------------#
# Save original Backbone.Stickit calls.
#-----------------------------------------------------------------------------#

stickit    = Marionette.View::stickit
addBinding = Marionette.View::addBinding
unstickit  = Marionette.View::unstickit

#-----------------------------------------------------------------------------#
# Return UI bindings for the provided view.
#-----------------------------------------------------------------------------#

ui = (view) -> _.result(view, '_uiBindings') or _.result(view, 'ui')

#-----------------------------------------------------------------------------#
# Attempt to perform @ui normalization of the provided string. As of this
# writing (Marionette 3.0.0), there's exposed function to normalize a hash,
# but not a bare selector, and we need to be able to normalize bare selectors
# to support addBinding() and unstickit().
#-----------------------------------------------------------------------------#

normalizeString = (string, view) ->
  return string.replace /@ui\.[a-zA-Z-_$0-9]*/g, (r) -> ui(view)[r.slice(4)]

#-----------------------------------------------------------------------------#
# Stickit selectors can be hashes, strings, or undefined. We need to
# normalize each type.
#-----------------------------------------------------------------------------#

normalizeSelector = (selector, view) ->
  return switch
    when _.isObject selector then view.normalizeUIKeys selector
    when _.isString selector then normalizeString selector, view
    else selector

#-----------------------------------------------------------------------------#
# Shim the three standard Stickit calls into Marionette View objects so
# that we can use the @ui syntax for bindings; this eliminates repetition of
# possibly long and complex selectors and allows us to have one definition
# for them, in the ui hash or function for the View.
#-----------------------------------------------------------------------------#

_.extend Marionette.View::,

  stickit: (optionalModel, optionalBindings) ->
    return stickit.call @,
      optionalModel,
      @normalizeUIKeys(optionalBindings or _.result(@, 'bindings') or {})

  addBinding: (optionalModel, selector, configuration) ->
    return addBinding.call @,
      optionalModel,
      normalizeSelector(selector, @),
      configuration

  unstickit: (optionalModel, optionalSelector) ->
    return unstickit.call @,
      optionalModel,
      normalizeSelector(optionalSelector, @)

#-----------------------------------------------------------------------------#
# Exports
#-----------------------------------------------------------------------------#

module.exports = Marionette

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

[paulfalgout]

👍 want to PR it? Needs some documentation, but that might be copy-pasta'd from v2.

[bazineta]

Sure, I'll take a shot at it.

[bazineta]

#3179 is the code change required, which is trivial. (Ignore the closed #3178, which is me struggling to understand how to convince GitHub that I wanted next as the base, not master).

I can't seem to find documentation about the other two methods (normalizeUIKeys / normalizeUIValues), so I'm not sure where to place the documentation for this one.

[paulfalgout]

Ah good point on the docs.. it looks like these were only ever documented when they were attached to Marionette itself, but when those were removed.. the docs went with it. So we can handle that separately. I assume though it'll still need a test.

[bazineta]

Studying how to deal with a spec now.

[bazineta]

Unit test added.