Goals for GB Modules

These are my rambling notes from last week/weekend

• Assume polyfills for stable features up to ES6
• Strive to be dependency-free
• Strive to be platform-independent
• Simple API that a junior web dev can understand
• Clear docs that a junior web dev can understand
• Tests when possible

Why do we assume polyfills will be available?

It mainly has to do with the second goal: Strive to be dependency-free. But aren't polyfills a dependency? Well, they are, but they're a dependency to normalize our API's across platforms. They're basically only a dependency for IE (and are optional-for/implemented-by library consumers.

GB Web Components

Not to necessarily be confused with web components, but we may end up using them anyway. By GB Web Components, I simply mean our browser application code/styles/markup. Given that x-tags now relies on the polymer polyfills (IE10+), and the project hasn't been updated in 2 months, I'm going to give the axe to X-tags. Polymer fails automatically because of no IE10+ support.

Given this, I think React might be a better choice.

• Consistent interface for instantiation
• Clear method for organization and replication
• Logging should be hierarchical

Why React?

True, there is a certain amount learning and gotchas involved with React, but, I believe the consistent component API makes it worth it. React + JSX give us a happy medium between browser support, performance, and web-component style logic instantiation.

Also, I bet we could make some middleware that makes "more pure" documents out of react pages. Consider some static HTML page that needs

A Standardized Component Interface

I think we would need to provide a standardized component interface for initializing components. This interface would ensure that certain arguments are passed to the component instance (such as the element to attach to and a parent logger).

// Restaurants page
var logger      = require('logger')('App');
var components  = require('components');

module.exports = components.init( 'pages/restaurants-list', '#page', logger, {
  // ...
});

The Component Definition should provide the means to dealing with wayward arguments, (like element being a string, instance of Element, or simply null), that way the underlying technology can do its job properly.

Component.init should return a standard interace to the underlying component that looks like the following:

{
  render    // Function to render the component
, component // Underlying reference
}

We can then setup helpers in handlebars to more easily render components on the server or client:

<div class="nav">
  <ul>
    <li><a href="#">Home</a></li>
    <li>{{{component "some-specific-dropdown"}}}</li>
  </ul>
</div>

This will extend our scripts block with a script that will initialize that same component when the page is ready.

Components vs Libs

A component has to fulfill our component interface expectations. Not everything needs to be a component - we can still use regular ol' libs and jquery plugins. At first, I got very caught up on this distinction. Consider an advanced Order Status Dropdown Filter. It needs to display custom markup, it needs to communicate events to the outside (like 'change' or 'selected:submitted'). When you're thinking in terms of functionality, all of the JS required can be encapsulated. You have a Dropdown Component that can be passed custom templates and data.

But there's a problem with this approach: How do we associate custom markup to specific behavior? How does something like the specific Order Status Dropdown Filter (as opposed to Restaurant Dropdown Filter) get defined, encapsulated, instantiated, and manipulated when you simply have a single Dropdown Component that all of these things use?

I think the answer is to create specific component implementations of each dropdown and to treat the base dropdown as either a lib or a base class in which to mixin.

Maybe we have a jquery plugin lib that provides the dropdown functionality. Or perhaps we have a set of mixins (see http://facebook.github.io/react/docs/reusable-components.html#mixins). Maybe it's both. The point is that the actual component is a specific set of functionality (i.e. the Order Status Dropdown) that utilizes libs.