devinivy / funk

Polymer high-fives Reflux

funk

Polymer high-fives Reflux

Usage

Funk marries Polymer and Reflux by allowing you to use standard Polymer v1 data-binding alongside Reflux's stores and actions. It leverages the yarn-state-behavior to share state throughout your app.

• Your view layer is Polymer.
• Your actions are Reflux actions.
• Your stores are Polymerized Reflux stores.
  • Views subscribe to stores via Polymer data-binding!

What You'll Find

Funk.Reflux

An alias for reflux-core (identical to RefluxJS, but without the React helpers). You'll find all the standard goodies on here like Funk.Reflux.createActions().

Funk.StoreBehavior

The Polymer behavior used to create a Polymerized Reflux store. Enables data-binding from the store to your views.

Funk.ViewBehavior

The Polymer behavior used to enable data-binding to a view from your stores.

Funk.CollectionBehavior

The Polymer behavior used by Funk.StoreBehavior to provide crucial helpers for working with lists and collections.

Example

Check out the full polymer-funky-flux demo or learn to use Funk by walking through this commented code! If you're unfamiliar with Reflux or the flux pattern, start reading here to see how it will make your life better-er.

view.html

<link rel="import" href="bower_components/polymer/polymer.html">
<link rel="import" href="bower_components/funk/funk.html">
<link rel="import" href="actions.html">

<dom-module id="my-view">
  <template>
    <!-- Look, a binding from myStore! -->
    <h1>Finger length: [[_length(state.myStore.finger)]]</h1>
    <ul on-click="_clickedFinger">
      <li>ring</li>
      <li>thumb</li>
      <li>pinky</li>
      <li>middle</li>
      <li>pointer</li>
    </ul>
  </template>
</dom-module>

<script>
Polymer({

  is: 'my-view',

  // Use the ViewBehavior to receive state changes from myStore
  behaviors: [
    Funk.ViewBehavior
  ],

  // Put MyActions to good use and give a whiff!
  _clickedFinger: function(e) {
    if (e.path[0].tagName === 'LI') {
      MyActions.smellFinger(e.path[0].innerHTML);
    }
  },

  _length: function(str) {
    return (str || '').length;
  }

});
</script>

actions.html

<link rel="import" href="bower_components/funk/funk.html">

<script>
  // Funk.Reflux is just a reference to the Reflux library
  var MyActions = Funk.Reflux.createActions([
    'smellFinger'
  ]);
</script>

store.html

<link rel="import" href="bower_components/polymer/polymer.html">
<link rel="import" href="bower_components/funk/funk.html">
<link rel="import" href="actions.html">

<script>
Polymer({

  is: 'my-store',

  // The StoreBehavior makes this element act
  // like a Reflux store... but in Polymer-land.
  behaviors: [
    Funk.StoreBehavior
  ],

  properties: {

    storeName: {
      type: String,
      value: 'myStore' // Name of the store as found on `state.myStore`
    },

    finger: {
      type: String,
      value: '',    // Initial finger state
      notify: true  // Indicates that this prop is part of app state
    }

  },

  // Subscribe to actions!
  // This works identically to Reflux's "listenables"
  funkListenables: MyActions,

  onSmellFinger: function(whichFinger) {
    // Setting finger here will notify
    // state.myStore.finger across your app
    this.finger = whichFinger;
  }

});
</script>

Docs and Tests

API docs | View demo | Run tests

Locally

The relative paths used in this project assume that funk will be included alongside its dependencies using bower. So, to test this repo and view documentation, a small amount of massaging must be done. Also, HTML imports require CORS support, so we must use a simple web server to view the tests and API-level documentation.

bower install
ln -s .. bower_components/funk
python -m SimpleHTTPServer 8000
# Now navigate to, for example,
# http://localhost:8000/bower_components/funk/

Documentation

To view the API-level documentation for the Polymer behaviors, follow the process above then navigate to http://localhost:8000/bower_components/funk/.

Tests

Tests are placed inside the test folder and can be accessed at http://localhost:8000/bower_components/funk/test/.

funk's Issues

Implement state serialization and state loading

Punish views who try to mutate state

Anyone with the ViewBehavior should not be mutating state. While this is a simple rule to follow, funk should also have the ability to crush anyone who attempts to mutate state from a view. Its enforcement should probably be toggleable.

Implement method for dynamically managing a list from a collection

Imagine a collection users. We want friends to be a list of objects in that collection, with paths from users to be linked to the appropriate items in friends. Currently deriveList() does provide this functionality. However, we'd like the list of friend ids to be dynamic rather than a one-time assignment.

Example,

this.friendIds = [3, 5, 8, 13];
this.deriveDynList('friends', 'usersCollection', 'friendIds');
this.push('friendIds', 21); // Notifies friends.splices
this.set(['usersCollection', 21, 'name'], 'Copernicus'); // Notifies friends.#4.name