Settings defaults options semantics #47

Merged
merged 2 commits into from Mar 29, 2012

Projects

None yet

2 participants

@StevenBlack

There are two commits in this pull request, which speaks to the jQuery Plugins Patterns section.

The chronologically first commit is a whitespace cleanup for consistency and to adhere to a standard; I chose the jQuery core standards.

The second commit cleanly separates the concepts of

  • Options: provided by the user

  • Defaults: provided by the plugin

  • Settings: the eventual amalgamated run-state of the plugin for its execution.

StevenBlack added some commits Mar 27, 2012
@StevenBlack StevenBlack Whitespace changes to better conform to jQuery coding standards, remo…
…ved the mix of spaces and tabs, adjusted line spacing in these two files for consistency of conceptual segmentation, and made changes to pass jsHint

The JQuery Core Style Guidelines can be found here: http://docs.jquery.com/JQuery_Core_Style_Guidelines

Adjusted the in-code white-spacing for consistency -- prior to these changes there was no evident standard, or a standard had yet to be enforced.  Chose to adhere to jQuery Core Style Guidelines because students studying jQuery will come across many examples authored by core team members who, on balance, tend towards this standard.

Fixed one minor jsHint-discovered error, an unnecessary semicolon at the end of a function definition.

Stripped-away all trailing spaces on code and blank lines.

By the way, I like your use of the leading semicolon to guard against prior concatenated code.

Signed-off-by: Steven Black <steveb@stevenblack.com>
d34a297
@StevenBlack StevenBlack Fix for the potential semantic confusion between settings, defaults, …
…and options.

Prior to this change, these two files used settings, something called "defaultOptions", and options.

Using "defaultOptions" is problematic because it does not cleanly separate defaults and options.  It needlessly confounds the two.

The `namespaced-starter.html` file actually fell into this trap.  See the comment on line 36 here: shichuan@7f3d3d3#jquery-plugin-patterns/namespaced-starter.html

Besides "defaults" is a better term than "defaultOptions".  This may matter for non-English native readers.

THEREFORE
options: values provided by the plugin's calling code.
defaults: the settings provided  A-Priori by the plugin
settings: the final, amalgamated run-time spec for the plugin

An additional benefit: cleanly separating options, defaults, and settings makes these available for subsequent runs of the plugin without mutating the plugin's defaults, which can be restored at anytime without redefining the plugin.  This is not so much a problem for these two examples, but there are other jQuery plugin patterns in this collection where this definitely applies.

For example, https://github.com/shichuan/javascript-patterns/blob/master/jquery-plugin-patterns/best-options.html where "options" is (for the moment) used in lieu of settings, thus destroying the user-provided options object.  I'll fix that separately.

Signed-off-by: Steven Black <steveb@stevenblack.com>
a506ff3
@shichuan
Owner

@StevenBlack wow, that's very well explained. thanks :)

@shichuan shichuan merged commit 404d2ca into shichuan:master Mar 29, 2012
@ahastudio ahastudio pushed a commit that referenced this pull request Jan 19, 2014
@StevenBlack StevenBlack Whitespace normalization, followed by a semantic cleanup of options, …
…defaults, and settings

Please see [pull request 47](#47) for some background on the semantics in-play here.

Note how separating the concepts of settings, defaults, and options allows us to make the comments more succinct.  That's because the concept of "options" isn't overloaded anymore.

**Options** come from the user.  **Defaults** come from the plugin.  **Settings* is what you run-with this time.

Signed-off-by: Steven Black <steveb@stevenblack.com>
2e4f4cd
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment