Skip to content
This repository has been archived by the owner on Feb 12, 2022. It is now read-only.

Fuel UX 3.x API Philosophy

Jump to bottom
interactivellama edited this page Oct 19, 2014 · 5 revisions

[WORK IN PROGRESS--This page may NOT be accurate!]

This a draft proposal for high-level design rules which guide the development of Fuel UX's plugin APIs and is modeled after 2.0 BOOTSTRAP JS PHILOSOPHY

PROGRAMATIC API

We also believe you should be able to use all plugins provided by Fuel UX purely through the JavaScript API.

All public APIs should be single, chainable methods, and return the collection acted upon.

$(".combobox").combobox('selectByIndex', '1').addClass("skinny")

All methods should accept an optional options object, a string which targets a particular method, or null which initiates the default behavior:

$("#myCombobox").combobox(); // initialized with defaults
$("#myCombobox").combobox('selectByIndex', '1'); // initialized, first item is selected
$("#myCombobox").combobox('disabled'); // initialized, disables control

DATA-ATTRIBUTE API

We believe you should be able to use some plugin options provided by Fuel UX through the markup API without writing a single line of JavaScript. Unlike Bootstrap, due to the need to use datasources and the library's goal of being lightweight, data-attribute APIs are second-class APIs and only offer a few convenience options.

<div class="pillbox" data-initialize="pillbox">

OPTIONS

Options should be sparse and add universal value. We should pick the right defaults.

All plugins should have a default object which can be modified to affect all instances' default options. The defaults object should be available via $.fn.plugin.defaults.

$.fn.modal.defaults = { … }

An options definition should take the following form:

*noun*: *adjective* - describes or modifies a quality of an instance

Examples:

backdrop: true
keyboard: false
placement: 'top'

EVENTS

All events fired after an event occurs should be past participle form.

disable vs. disabled
enable vs. enabled

All infinitive events should provide preventDefault functionality. This provides the ability to stop the execution of an action. (Bootstrap example)

$('#myModal').on('show', function (e) {
    if (!data) return e.preventDefault() // stops modal from being shown
})

CONSTRUCTORS

Each plugin should expose its raw constructor on a Constructor property -- accessed in the following way:

$.fn.checkbox.Constructor

DATA ACCESSOR

Each plugin stores a copy of the invoked class on an object. This class instance can be accessed directly through jQuery's data API like this:

$('.checkbox-custom').data('fu.checkbox') instanceof $.fn.checkbox.Constructor

DATA ATTRIBUTES

Data attributes should take the following form:

  • data-target || href^=# - defined on "control" element (if element controls an element other than self)
  • data-{{noun}} - defines class instance options

Examples:

// control other targets
data-toggle="modal" data-target="#foo"

data-dismiss="modal"
data-dismiss="alert"

data-toggle="button"
data-toggle="buttons-checkbox"
data-toggle="buttons-radio"
Clone this wiki locally