NOTE: These are all early recommendations and we welcome your input. Current pages (unfortunately) do not follow these guidelines and are inconsistent. We'll update all pages once this is nailed down.
Writing style
Short, declarative sentences with a crisp, active voice directed at the designer or developer who will be using our tools. View Apple's interface guidelines for a good example of the tone we'd like to follow in this wiki. Try to cross-link related plugins whenever possible.
Project name
The project name should always be written 'jQuery UI', never just 'UI'. Also we never expand to the full-length jQuery User Interface. Finally, no other forms (whether abbreviations, hyphenations, or capitaliztion) should be used, such as: JQUI, jQui, jquery.ui, jQuery.UI, jQuery-UI, jQuery UI Library, jQuery UI Framework, etc. Sentences like "Use the jQuery UI framework to get the job done" can be easily rewritten to "Use jQuery UI, the rich jQuery powered UI framework, to get the job done". This helps to focus on the branding.
Capitalization
Plugins should be named as briefly and unambiguously as possible and in the singular. Ideally, these should be a single word like "tree" or "sortable" but for longer names, we should separate words with spaces which is different than the current jQuery system. For example, we use "Progressbar" in the current documentation but "progress bar" is probably a more common way to write this. In a quick Google search, you find 3.5M results for "progressbar" and 12.3M results for "progress bar". This trend is consistent across all widget searches so it seems to be a better way to name components.
There are exceptions where the use of the singular for plugin names is insufficient. If the term in singular isn't applicable for the widget, the plural has to be used instead. A good example is the "tabs" plugin. Since instantiating a single tab would not highlight the plugin itself and is useless, "tab" does not describe semantically what the plugin does.
NOTE: this is a potentially big decision that could have ripples beyond this wiki so we need to discuss.
Plugin, page and section titles all use sentence capitalization. Only the first word is capitalized in a title, not each word.
Ex. "Language styleguide", not "Language Styleguide".
You can use spaces in wiki page titles -- these will appear in the URL as a "+" separator.
Ex. This page's URL is "http://jqueryui.pbwiki.com/Language+styleguide".
In the running text, plugins should be written in lower case with spaces.
Ex. "a select box is used...", not "a Select Box is used...".
Common terms
plugin - any jQuery widget or component
widget - a plugin that is a complete UI element that a user would interact with like a tab strip or calendar and will be styled in ThemeRoller
effect - a plugin that provides a visual effect like animation and easing
interaction - a plugin that adds user interaction behavior to an element like draggable or resizable
utility - a plugin that adds a low-level capability or tool to the library like positioning or collision detection
Comments (17)
Richard D. Worth said
at 1:27 pm on Nov 20, 2008
Also, I prefer the single word all lower-case we currently use Ex. progressbar instead of Progress Bar or progress bar. But maybe it depends on whether you're talking about the specific jQuery UI control (progressbar) or a progress bar in general? To me the name of the control should be progressbar.
Richard D. Worth said
at 1:33 pm on Nov 20, 2008
I guess I'll add a few reasons as to why I still feel that way, because it was a conscious decision when we made it. The plugin name is used in the filename, in the code, in the name of a wiki page (url). In all of those case there will be no space. So I guess it's more consistent and more easily consistent. Otherwise if you called it progress bar in a lot of places, there would be some places where you would still see and write progressbar (the name of the class, the name of the file etc.). So imagine someone goes through and fixes all those instances, but without recognizing which should remain progressbar (one word). So, because there will be many cases with no space, it seems simpler to never have a space.
Richard D. Worth said
at 1:39 pm on Nov 20, 2008
Also, as far as spaces in the urls, I'd much rather see /progresbar than /progress+bar (try as I might, I can't read that as anything bug progress PLUS bar). And thanks to Murphy's law someone is bound to end up typing 'progress bar' and ending up with /progress%20bar in their address bar. Yuck.
Richard D. Worth said
at 1:58 pm on Nov 20, 2008
Hmm, I just tried space ( ) and plus ( + ) in the url in mediawiki (jQuery Docs, end-user jQuery UI Docs wiki) and it converted both to underscore ( _ ). -1
Todd Parker said
at 2:04 pm on Nov 20, 2008
I understand the rationale and I think what you have now for names works for the limited set of widgets (you have been lucky so far!). But as I think about some of the new widgets on the horizon, trying to shorten these or jam them into a single word with no spaces could be really ugly -- "collision detection" is a good one. Maybe we can always shorten these to make a single word work. I welcome people to just re-name the items in the matrix to work out a system. Here are the tougher ones I see already in the matrix:
image preloading
data visualization
textarea list builder
infinite scrolling
layout manager
multiple checkbox picker
form validation
collision detection
Jörn Zaefferer said
at 2:24 pm on Nov 20, 2008
image preloading - just preloading? preloader?
form validation - just validation
layout manager - could be just layout
multiple checkbox picker - checklist? checkboxlist?
data visualization - just visualization?
I'd much prefer the one-word varations: Easier for development, and the style is much more common in german, eg. collision detection is Kollisionserkennung. The development argument is the strong one: In the end, we have to find names for the plugin methods, its good to have them 1:1 to the specification.
Paul Bakaus said
at 4:24 am on Nov 21, 2008
I agree with Jörn and Richard here - in the code, we try to use short, easy naming, as much as possible, the jQuery style. Something like data visualization could be "$([]).visualize()" in the code. Also, introducing whitespaces will likely introduce problems in many instances, as Richard pointed out, so if we can find single words to describe certain functionality, we should.
Ca-Phun Ung said
at 4:49 am on Nov 21, 2008
I think we should also be consistent in the names on the frontpage aswell so they follow the shortened one word name. i.e. "progress indicator" should be referred to as "progressbar" everywhere.
Also are we to continue with the old convention? Should it be Timepicker or timepicker from now on?
What if a widget really could not be shortened into one word? This might be an edge case but is a possibility. What convention should we follow then? lowercase, lowerCamelCase or UpperCamelCase?
Jörn Zaefferer said
at 5:02 am on Nov 21, 2008
Ca-Phun, that depends on the context. Take data visualization: The plugin method would be named dataVisualization, while the wiki page could be DataVisualization.
Still, I vote for working hard on finding short names. It probably results in a few less then optimal names, but that trade-off seems to be worth it to me.
Ca-Phun Ung said
at 5:03 am on Nov 21, 2008
As a personal preference I like Timepicker more than timepicker but then positionTo looks better than Positionto. :-(
Richard D. Worth said
at 5:36 am on Nov 21, 2008
I'm not too anxious to change (all) the names on the front page, because we don't have a 1:1 match (though we could work toward that). The front page currently contains pattern names, not component/plugin names. Progress Indicator is a good example. When create round spinner indeterminate indicators, I wouldn't think they'd be called progressbar.
Ca-Phun Ung said
at 6:53 am on Nov 21, 2008
Good point. Though that just means we shouldn't be calling this plugin method progressbar as it doesn't fully reflect the widget. Unless the idea is to have a different method per type of progress indicator?
Richard D. Worth said
at 7:01 am on Nov 21, 2008
I don't have a problem calling this widget a progressbar. That's what it is, and someone looking for a progressbar is going to say, "I want a progressbar. Oh here's one - jQuery UI Progressbar" As far as what to call the others, and whether they'll be incorporated or separate, that's still to be decided. But they all/both fit into the progress indicator pattern.
Ca-Phun Ung said
at 7:16 am on Nov 21, 2008
I see. Well that's where the confusion lies (for me at least). For some reason I thought that each row in the table on the front page refers to a single widget / utility / interaction. If a page refers to a pattern of widgets rather than a single widget then I agree we do not have to necessarily match the two.
Richard D. Worth said
at 8:52 am on Nov 21, 2008
We're in transition mode. This page (really this whole wiki) started as a way for the interaction design team to plan, collaborate, and design interaction patterns. It's getting closer and closer to a 1:1, especially with the recent prioritization, but there will be a lot of changes/renames still. And that'll continue.
Ca-Phun Ung said
at 9:07 am on Nov 21, 2008
Yes. I understand. And discussions of this type also help with the progression. So debating can only lead to a win win situation. :)
Todd Parker said
at 11:38 am on Nov 24, 2008
I just changed "plug-in" to plugin here. Please try to fix these elsewhere. On the topic of naming in general, I'm ok with using singel wrds like you do now as much as possible so this matches what's already out in the world.
This bigger issue we need to deal with is the difference between how we call things here for the purposes of planning and coding vs. how they may be consumed in the outside world. For example:
We're releasing the "Progressbar" plugin in rc3. In the wiki, this is a small part of the larger set of "Progress indicators" that includes determinate/indeterminate types in both bar and circular styles. Do we keep a single "Progress indicators" page with all the sub-types listed as have now or break these into pages the match the final plug-ins? Will the indeterminate bar be a future option of the determinate bar like Apple handles it (the current value is ignored I guess) or will this be a new plugin called "Indeterminateprogressbar" which would mean we should re-name "Progressbar" to "Determinateprogressbar" (yuck). Where would the circular ones fit into this world? We can handle each one as a separate plugin, group them by type (determinate/indeterminate) with shape as a secondary option under each or group them by shape (bar vs. circular) with type (determinate/indeterminate) as a secondary option under each.
You don't have permission to comment on this page.