jQuery UI downloads - what are each of the directories in the archive holding?
jquery-ui
Solution
Let's start with an explanation of what jQuery UI downloads are: They're a full bundle of development and production files. Keep in mind that jQuery UI is downloaded over 11,000 times per day (and that's just the download builder usage). The ways in which these downloads are used can vary greatly among users. The contents of these downloads are intended to serve the largest number of users. It's important to note that the development bundle is almost an exact copy of the source repository.
source, demos, themes, tests
- `MANIFEST`: This is a file containing a list of every other file in the zip, along with checksums. Very few users will care about the manifest, but for those who do care, it provides critical information.
- `README.md`: (note that you listed `README.txt`): This is the README for the jquery-ui git repository. It's an exact copy of what you will see if you view the project on GitHub.
- `*.json`: These are plugin manifest files for the jQuery Plugin Registry. These files are never stored in the master branch (or any other branch), but are always included in tags. Because they provide useful information, they're included in the downloads. You can read more about the manifest file structure.
- `package.json`: package.json is a standard file for use with npm/node. All jQuery projects rely on node to do linting, testing, builds, releases, etc. This is completely separate from the other JSON files which are for the jQuery Plugin Registry. They have very similar structures, because the plugin manifest files were designed based on npm.
- `external`: This directory contains third party scripts which are used in demos and tests.
- `jquery-1.9.1.js`: This is the latest stable version of jQuery that jQuery UI was tested against. We never include minified jQuery versions in the jQuery UI repository since they're horrible for debugging.
- `MIT-LICENSE.txt`: The license which defines the terms under which you can use the files in the download.
- `AUTHORS.txt`: A list of contributors to the jquery-ui repository. This does not include contributors to other parts of the jQuery UI project, such as work on any of our various sites or documentation.
- `demos`: A directory of demos for the selected components (in this case all components). The demos actually originate in the jquery-ui repo and are copied to jqueryui.com during releases.
- `Gruntfile.js`: We use Grunt for linting, testing, and building. Grunt is a JavaScript task runner for node. Building jQuery UI means minification and concatenation.
- `tests`: A directory of tests for the selected components (in this case all components).
- `ui`: A copy of the source files, with @VERSION replaced with the release's version number. The `jquery-ui.js` file is generated during the build by concatenating all of the source files together. The `minified` directory is generated during the build by minifying the individual files. And of coure `jquery-ui.min.js` is generated by both concatenating and minifying the source files.
- `themes`: A copy of the source files, with @VERSION replaced with the release's version number. This undergoes the same process as the `ui` directory regarding concatenation and minification. The individual component files are theme-independent. So `jquery.ui.accordion.css` will work with any theme. These are the required CSS files for use with the JS files. You can build any theme you want, but if you don't use the functional CSS for the component, then nothing is guaranteed to work. Full themes (what pretty much all users actually use), contain all of the functional CSS plus the theme CSS in a single file.
themes
Themes are generated by ThemeRoller. They do not live in any repository and as such do not contain artifacts of any repository. This is why there is no README.
- `MANIFEST`: Same as above, the manifest contains checksums for the files in the download.
- `AUTHORS.txt`: A copy of `AUTHORS.txt` from jquery-ui. This should exactly match the source download. While this isn't a list of people who have contributed to themes, we view this as part of the code and include the same list of authors.
- `package.json`: A copy of `package.json` from jquery-ui. This file does seem a bit strange, since it's not coming from a repository. We should probably remove this.
- `themes`: A directory of generated themes. These do not contain the source variables/tokens. The base theme is not a generated theme and therefore is not included. You'll notice that generated themes also have a different directory structure. Each theme contains three files: `jquery.ui.theme.css` is just the theme CSS; this is what can be used with the functional CSS provided in the base theme. `jquery-ui.css` is a full theme; it includes the theme CSS plus the functional CSS. `jquery-ui.min.css` is a minified copy of `jquery-ui.css`.
Problem
(and why do you think the jQuery team are unable or unwilling to write decent documentation?;) For example, go to http://jqueryui.com/download/all/ and download either - jQuery UI 1.10.3 (source, demos, themes, tests) - jQuery UI 1.10.3 Themes #1 - There is a `MANIFEST` file. - There is a `README.md` file but no explanation of the the layout of the archive. - There are several files with a JSON extension e.g. `ui.accordion.jquery.json`. They contain some information about the particular UI widget. I don't know what these are used for, do you know? - A file named `package.json`. It seems just to be some library info in JSON format. Do you know what this is for? I suspect it's linked to the other `.json` files, but who knows? - There is an directory named `external` that holds javascripts. Do you know what this is for? - There is the `jquery-1.9.1.js` file. No minified version. - A licence in `MIT-LICENSE.txt`. - An `AUTHORS.txt` file, which contains the names of the contributors, that are repeated several times throughout the archive. Not one of them managed to list what's in the archive thoroughly though ;) - A `demos` directory with what appears to be all the demos from the website. - A `Gruntfile.js` that the README says is used to build jQuery. Whatever "building" jQuery means. - A `tests` directory. - There is a directory named `ui` that seems to hold all the jQuery UI effects javascripts, also minified in a subdirectory, and an `i18n` subdirectory for those widgets that need internationalization. - There is a directory named `themes`. In it there is a subdir called `base` that holds the base theme stylesheet. This subdir also contains an `images` dir for the base theme. It also holds stylesheets for several of the effects e.g. `jquery.ui.accordion.css`. Do these only work for the base theme or can they be applied to any theme? If not, why does only base have them? (see below) There is also a `minified` subdir which has minified versions of all the stylesheets. #2 - The archive contains a `MANIFEST` file - but no README. - An AUTHORS file. - A `package.json` file with a small amount of information about the project. - It has several themes but no `base`. - There are no effects/widget files in either the root directory or each of the themes' directories. - Each theme directory contains an `images` subdirectory with image files associated with that theme, a `jquery-ui.css` stylesheet, a minified version of this, and a `jquery.ui.theme.css`. The `jquery-ui.css` in each theme directory is different to each directory. Do you know what each of these files is for? Why aren't all the specific changes in the `jquery.ui.theme.css` file? Why do I need to know this? This may come up in the comments so I'll answer it here. I've written a couple of libraries to help with deploying the correct version / theme in Ruby Rack projects, Rack JQueryUI and Rack JQueryUI Themes. Every time there's a version change of jQuery UI I have to deal with these undocumented archives, that also seem to change in layout / contents between versions. I've not had good feedback when speaking with the jQuery team - I find they are lamentable at documentation and it's obviously not a priority for them, they'd rather be renaming functions or something - so I'd rather just have someone helpful answer me here, and this will make a good place to keep it (out of their reach, so to speak). I'm most interested in the questions around the theme directories as that will directly help me right now, but I've extended the scope of the question because I believe it will help others and I am curious.