modularity-framework

A modular web UI controller micro-framework

Modularity is a micro-framework for lightweight component-oriented client-side JavaScript. It allows to compose functionally rich web pages in clean, intuitive, and testable ways out of well structured and reusable components.

What makes Modularity stand out is that it scales very well with complexity, and overall does not get in your way. You can easily combine it with your favorite templating and data management services. Modularity just helps you organize your DOM related logic.

If some of the existing MVC frameworks fit your use case, use them! If you don't have a data-driven app, or want to stay more in control of what happens on your page, and when, Modularity might be a good general-purpose infrastructure for you.

Installation

• Have jQuery on your page
• Add the file modularity.min.js to your page

How it works

Modularity provides a single helper class called "Module". A module is a JavaScript class that manages a part of a web page. Examples for typical parts of webpages are the menu, a slideshow, a comment form, the log-in button etc.

Each module is responsible for everything that happens inside its web page part.

• making sure the DOM content is there
• wiring up event handlers to the DOM
• responding to events that get triggered by user interactions
• notifying subscribers about updates from this module
• respond to messages that are sent from the outside world to this module

Example

Let's build a button that displays how often it was clicked. It should also allow us to reset the counter.

Here is the final HTML for it:

<button id="my_click_button">
  You have clicked me <span class="click_count"> times.
  <div class="reset">Reset</div>
</button>

Let's define the JavaScript for it using Modularity.

# A button that displays how often it was clicked.
# All modules are subclasses of the "modularity.Module" class.
class CounterButton extends modularity.Module

  # Each module must be given its container as the first argument of the constructor.
  # The container is the outermost DOM element of the module content.
  # Mostly that's the <div> that contains the part of the web page this module
  # is concerned with.
  #
  # Everything that is happening inside this container element is the
  # responsibility of this module. Nothing that happens outside of this
  # container element is a concern for the module. Anything that this
  # module does must happen inside this container.
  constructor (container) ->

    # Initialize the Module part.
    # Every module must call the constructor of its superclass.
    super

    # Set up the DOM content.
    # This is optional. If the DOM is already there, we don't need to do
    # anything here.
    # If we would only be given an empty container
    # (button id="my_click_button"></button>), then we would fill it here.
    #
    # You can use any templating system here.
    container.html """You have clicked me <span class="click_count"> times.
                      <div class="reset"></div>"""

    # A data attribute.
    # It represents how often has the button has been clicked.
    #
    # We initialize it with 0 here, but the value could also be given as a
    # parameter of the constructor method, or be read from a data attribute
    # in the DOM here.
    @click_count = 0

    # A DOM attribute.
    # It contains the DOM element that displays the click count.
    #
    # The @$ method executes the jQuery constructor only for elements inside
    # this module's container. This is important.
    # Modules should only care about what happens inside of
    # their container elements, and not at all what happens outside of them.
    #
    # This method also verifies that we found something, i.e. that the
    # DOM variable isn't empty.
    @click_count_display = @$ '.click_count'

    # An embedded module.
    #
    # The point of modularity is to compose modules out of other modules or
    # raw DOM elements. This is the key element to managing complexity.
    #
    # In this case, the "ResetSwitch" module takes care of the "reset" switch
    # for this button. We don't care how it does that. It could listen to
    # mouse clicks, keyboard hotkeys, swiping gestures, or shaking of the
    # mobile device that this page runs on etc. All of this functionality is
    # encapsulated in the "ResetSwitch" module.
    #
    # All we care about here is that the "ResetSwitch" module fires a
    # "triggered" event when the user activated reset switch.
    #
    # You can see what we do when that happens in the event handler below.
    #
    # Another advantage of encapsulating the reset switch functionality into
    # its own module is that we can now easily add reset switches to
    # all sorts of other things on our site.
    #
    # Modules need the container element (or the jQuery query string to get them)
    # as their first parameter.
    @reset_switch = new ResetSwitch '.reset'

    # This method hooks up the event handlers defined below
    # to the member variables defined above.
    #
    # In our case, it wires up the following events:
    # * user clicks on container --> call @on_container_click
    # * @reset_switch fires "triggered" --> call @on_reset_switch_triggered
    #
    # All of these events are normal jQuery events.
    # * jQuery makes DOM elemens fire a "click" event when users click on them
    # * Modules can fire custom jQuery events to indicate updates
    #
    # You don't have to use autobind(). It is just a convenience method to
    # automate the straightforward cases.
    #
    # If you don't use autobind(), you have to manually wire up events, like this:
    # @container.click @on_container_click
    # @reset_switch.on 'triggered', @on_reset_switch_triggered
    autobind()


  # Called when the user clicks on this button.
  on_container_click: =>
    @click_count++
    @update_click_count_display()


  # Called when the user triggers the 'reset' switch.
  on_reset_switch_triggered: =>
    @click_count = 0
    @update_click_count_display()


  # An internal helper method.
  # It updates the click counter display with the current click count.
  update_click_count_display: ->
    @click_count_display.html @click_count

    # Let's make this a bit fancy, and indicate with colors whether the
    # button has been clicked enough.
    if @click_count_display > 3
      @container.addClass 'green'
    else
      @container.removeClass 'green'

Mixins

Similar to Ruby mixins, mixins in Modularity allow to include orthogonal functional aspects defined in separate objects into a class.

myMixin =

  # This will be called when an instance of a class that includes this mixin is created.
  constructor: ->

  # This method will be available in every class that includes
  myMethod: ->


class MyModule extends Module

  @mixin myMixin

  constructor: (container) ->

    # The super constructor will call the mixin constructors here.
    super

    # ...

Hooks

Hooks are a more direct and easier way to interact with mixins. They are methods with predefined names that mixing modules can implement to hook into events of their mixins without the need to wire up event handlers, and with the ability to interact with the workflow of the mixins.

Development

Contributing

• Fork it
• Create your feature branch (git checkout -b my-new-feature)
• Commit your changes (git commit -am 'Added some feature')
• Push to the branch (git push origin my-new-feature)
• Create a new Pull Request

Running the unit tests

$ npm test

Authors

• Kevin Goslar
• Alex David