jQuery plugin options: required, optional, inaccessible

Question

I'm curious how to specify options to a jQuery plugin in a way that some are required, some are optionally overridden, and some can't be touched.

I started off with the usual:

jQuery.fn.plugin = function (options){
  var defaults = { username: "", posts:10, api: "http://myapi.com" }
  var settings = jQuery.extend({}, defaults, options);
}

Let's say I want username to be required, posts is optional (defaults to 10) and you (you being the user of the plugin) can't change api, even if they try. Ideally, they'd all still be in the same data structure instead of being split into separate objects. Ideas?

Answer 1

If you wanted username to be required, I'd make it a parameter, given it's the only required thing and there aren't 20 parameters you want to do this way. Something like this:

jQuery.fn.plugin = function (username, options){
  var defaults = { posts:10, api: "http://myapi.com" }
  var settings = jQuery.extend({}, defaults, options);
}

There's not a clean required way to do this completely in a single passed object, at least not a simple one, which is what you want for an API. The alternative would be to specify no default and alert or something if it's not there I suppose:

jQuery.fn.plugin = function (options){
  var defaults = { posts:10, api: "http://myapi.com" }
  var settings = jQuery.extend({}, defaults, options);
  if(typeof options.username == 'undefined') { 
    alert("You must specify a username");
    return this;
  }
}

Edit - Missed part of the question, for the inaccessible ones, either have the values hard-coded, since that's the same result, or a bit cleaner would be an internal object inside your plugin that is out of scope everywhere else. Again, not trivial to do on the same object unless you kept say an intenalDefaults object, and called jQuery.extend() with it after the extend of settings that so it would overwrite anything the consumer passed in.

Answer 2

$.fn.plugin = function(username, options) {
  if (!username) throw "Must provide a username.";

  var config = $.extend({}, $.fn.plugin.defaults, options);

  var privateVal = 4;
  ...
}

$.fn.plugin.defaults = {
  posts: 10
}

Here's a summary:

• required parameters are usually most clearly passed as normal ordered parameters. If there are too many of these consider some sort of structure-- or better-- a different API.
• Options are most easily specified via an options hash as the last parameter. In general these should be optional, but it's certainly possible to throw and error if they are missing.
• Fill in defaults using jQuery's extend function. You'll generally have some "defaults" to collect these. I like to scope these to the plugin's name itself for the name spacing-- and as helpful documentation of what options are available.
• Generally throw if a required parameter is missing.
• If you have values you don't want the caller messing with, define them within your plugin, where the scoping of Javascript will prevent the callers from messing with them.