National Party Month

    mithril.exitable

    1.2.1 • Public • Published

    mithril.exitable.js

    Join the chat at https://gitter.im/barneycarroll/mithril.exitable.js

    A Mithril wrapper whose controllers gain a new exit hook for outgoing animations. Exitable is intended for use with the Mithril 0 API - it is redundant in (at the time of writing, forthcoming) Mithril 1, thanks to the onbeforeremove hook.

    When you bind an exit method to a controller, we observe the output of each draw: as soon as we detect that the corresponding component has been removed from the view, the draw loop is frozen; all your animations execute, and when they're done, Mithril goes about business as usual.

    Demos

    …suggest more in the issues!

    Usage

    Exitable is a Mithril wrapper or patch, meaning you need to bring your own Mithril for Exitable to use as a base. Exitable then wraps certain Mithril methods to extend it with its own behaviour, and returns you a patched version of Mithril to use in your application.

    This means your original Mithril is untouched, and eg any other Mithril dependent plugins in your codebase will get access to the 'clean' version rather than going through Exitable, in contrast to eg jQuery plugins which modify the core jQuery object.

    Which source?

    ES6 / CommonJS / Browserify

    The Exitable module depends on Mithril being available as a module as mithril. In turn, you should import Exitable instead of plain Mithril.

    // ES6
    import m from 'mithril.exitable'
    // CommonJS
    var m = require( 'mithril.exitable' )

    ES3

    The ES3 version assumes a browser global environment. It will require a Map polyfill – I recommend Andrea Giammarchi's ES6 collections if this is your only outstanding jsnext dependency. You must include Mithril and your Map polyfill (if necessary) before including Exitable. Exitable will then replace the window.m reference:

    <script src="https://cdn.rawgit.com/WebReflection/es6-collections/master/es6-collections.js"></script>
    <script src="https://cdn.rawgit.com/lhorie/mithril.js/next/mithril.min.js"></script>
    <script src="https://cdn.rawgit.com/barneycarroll/mithril.exitable.js/master/src/exitable.es3.js"></script>

    Binding exit animations

    To register an exit animation, bind a function to the exit key of the controller instance:

    var myComponent {
      controller : function(){
        this.exit = myAnimation
      },
      // ...
    }

    The animation function receives the live DOM element representing the root of the component that's about to be removed from the document.

    // ...
        this.exit = function(el){
          // ...
        }
    // ...

    For convenience, Exitable also provides an enter method hook, so you can define entry and exit animations in the same place.

    {
      controller : function(){
        this.enter = function(el){
          // ...
        }
      },
      view : () =>
        m( '.root' )
    }
     
    // Is equivalent to
     
    {
      view : () =>
        m( '.root', {
          config : ( el, init ) => {
            if( !init )
              // ...
          }
        } )
    }

    exit functions

    What should the animation do? That's up to you: although I highly recommend Julian Shapiro's Velocity library, which can be supplemented with a UI pack full of pre-registered animations (which are used throughout the demos).

    All exit functions must return a 'thenable' so that Exitable knows when all animations are finished in order to resume Mithril's draw loop.

    Velocity

    Velocity returns thenables by default, which makes exit animations nice and terse, especially with the help of arrow functions:

    this.exit = el =>
      Velocity( el, 'fadeOut' )

    Other libs

    If your tool of choice doesn't return Promises, you can create your own Promise and bind it to the done callback (or whatever hooks the animation library provides):

    this.exit = el =>
      new Promise( done =>
        $( el ).fadeOut( done  )
      )

    Without Promises

    …and if you can't return thenables or use Promises, then you have to make your own thenable. Exitable doesn't depened upon chaining or suchlike, so anything with a then method which executes at the right time will do:

    this.exit = function( el ){
      var thenable = { then : function(){} }
     
      $( el ).fadeOut( thenable.then )
     
      return thenable
    }

    Install

    npm i mithril.exitable

    DownloadsWeekly Downloads

    4

    Version

    1.2.1

    License

    MIT

    Last publish

    Collaborators

    • barneycarroll