Blueprint's directory structure
Posted on January 03, 2008. 18 comments.
The Prototype JS framework has a great directory structure. The project has a source folder, containing different parts of the framework, and a simple script that puts these together to one file (prototype.js) for distribution. This makes both development and deployment enjoyable.
Blueprint’s directory structure has been way too complex until now, with quite a few files that were, well, unnecessary. The goal should be to have as few files as possible, organized in the most intuitive way we can think of.
We can’t go down to a single-file product, such as Prototype, since screen.css, print.css and ie.css all have to be included in the HTML in three different ways. There are ways to make these three files apply to the correct environment through one file, but including them in HTML with correct media types and conditional comments is the easiest and most predictable way of getting this to work. So that’s what we’ll do.
Another thing we must do is to move the inclusion of plugins to the HTML. This used to be done in screen.css, but with this new method, we ensure that upgrading to a new version of Blueprint is as simple as replacing the old Blueprint folder.
So we need three files in the top level directory (screen, print, ie), one source folder for all our different parts (grid, typography..), a script for compressing the source to the three top-level files, a tests folder and a plugins folder. Let’s draw it up:
Blueprint’s new directory structure
blueprint/
screen.css
print.css
ie.css
src/
reset.css
grid.css
typography.css
forms.css
print.css
ie.css
plugins/
scripts/
compress.rb
validate.rb
tests/
docs/
(The print.css and ie.css files in the src directory are the uncompressed versions of the top-level files with the same names.)
Another great result of this, is that a user not looking to experiment with Blueprint, only needs the top three files. Such distribution would require something like a Blueprint Wiki with better documentation, as these three files have no comments to explain their functionality.
The change has already been made in our SVN repository, so check it out there if anything is hazy. This also means that we have a new compression script, which you can check out in the SVN as well.
It’s a good start, but I’m sure we can do better. Suggestions? :)
18 comments
Mary-Ann Horley says:
I put my own code in a custom.css file that went in /lib, I should now put that in /src I think?
Anthony Short says:
I like the directory structure a lot more now. It’s a little more straightforward. Another idea would be to just remove the screen, print and ie css from the top level from the framework and leave the src file as ‘blueprint’ perhaps. This could focus the project a little bit more, rather than forcing a particular work method.
Lim Chee Aun says:
Two ‘ie.css’? Why?
Olav says:
@Mary-Ann: No, you should just use other CSS files as you usually apply CSS. It’s easier to upgrade if you never change anything in the Blueprint directory.
@Anthony: You mean by specifying/hacking in how the files gets applied in a blueprint.css file? I think the HTML method is more correct, but having one file would be very nice indeed.
@Lim: The top-level files are compressed - the print.css and ie.css in the src folder are uncompressed. I fear a lot of people will find this confusing - any ideas? :)
Anthony Short says:
I was suggesting you could leave the 3 top level files (screen.css, print.css and ie.css) out of the framework. But I’ve changed my mind, I like the way it is :) I wasn’t aware the top level files were compressed versions of the framework.
Olav says:
Yeah, if it wasn’t for the fact that they are compressed, I’d feel the same way. Prototype’s distributed file is uncompressed, but I don’t think that would work as well for Blueprint.
Paul Wib says:
Any reason why the buttons plug-in isn’t in SVN repository?
eemi says:
As Paul asked, what happened to the buttons plugin? The style was great, as the hole framework
Andy Gongea says:
I do not understand why does everyone separate the every css framework in specific files. Think that having more files (css) - means more http requests so - slow response time from the server
Jon Ronnenberg says:
@Andy Gongea: It’s true that you should avoid having too many http requests but it’s also true that you shouldn’t use css that you don’t need - think bandwidth and unnecessary cascading. You SHOULD use only the css you need and then compress it with a tool, e.i. YUI Compressor, to a single file. Disclaimer: This does NOT apply to browser specific style sheets, e.g. IE.
Jon Ronnenberg says:
@Andy Gongea: It’s true that you should avoid having too many http requests but it’s also true that you shouldn’t use css that you don’t need - think bandwidth and unnecessary cascading. You SHOULD use only the css you need and then compress it with a tool, e.i. YUI Compressor, to a single file. Disclaimer: This does NOT apply to browser specific style sheets, e.g. IE.
mpo says:
Some ideas (somewhat lengthy)
The issue is bigger then a the swiftness of a single (first) page-load IMHO
In HTTP 1.1 various files are typically loaded over the same connection. Given the fact that setting up a TCP/IP connection is taking far more time then using that connection to download stuff I shouldn’t worry too much about the fact that multiple requests will be needed. (The gain of flexibility and ‘appropriate sizing’ is far bigger IMHO)
Having said that however, I do think one should try to benefit from possible caching on the browser side: Setting up your http server to send out the css file with proper caching directives will be a lot more beneficial (the discussion is no longer about will there be 1 or 5 files downloaded to build up the page, but rather will those downloads happen once per page, per session, per visitor, ….) Given the numbers (for successful websites) there is a far bigger gain to be made here in both strain on the server and faster rendering on the browser.
In that respect some ideas could be taken from yui’s strategy:
I find the double appearance of files too very confusing. It’s probably my programming background (Java) but the ‘less surprising’ strategy IMHO would be to only maintain the actual source files in svn, and introduce some mechanism for ‘building’ a trunk-based release out of that. (I think the higher effort on blueprint developers of this approach will easily be gained back by the easier way of working for all the users)
Typical svn structure then becomes: src / : here comes whatever actual structure to keep the different css and plugins nicely separate
build / : (in stead of ‘build’ one can call it ‘target’ or ‘compressed’) here comes the same structure but post-processed by some build-script thinking about the previous remark this might introduce a parent folder holding the current release number: build/0.7-dev/ Most important thing is that this folder is added to the svn:ignore (thus not checked in)
build-release.txt : a simple text file containing the release number. in trunk that would be 0.7-dev when making an official release, this should be “fixed” to a non-suffixed version before making the svn-tag. i.e “0.7” and then switched back into 0.8-dev before committing into svn. The script described below will use this:
scripts/build.rb : a well written build script that ‘creates’ the build-folder this might include validation, compression, maybe even aggregation (for those that still think single css files are really needed) it should be a small effort to let this also bundle up the zip for a real release.
Another thing this would bring is the ability to easily switch my ongoing project development versus different (even trunk) versions of blueprint.
Since the ‘built/released’ structure would exactly match the source structure (bar being compressed, but that is not an issue for testing) one can easily switch (adapting a shortcut/symbolic link e.g. named ‘latest’) between bp versions.
This ability will allow people to
Me too is wondering what happened - or better - will happen to those in the future?
mpo says:
Some ideas (somewhat lengthy)
The issue is bigger then a the swiftness of a single (first) page-load IMHO
In HTTP 1.1 various files are typically loaded over the same connection. Given the fact that setting up a TCP/IP connection is taking far more time then using that connection to download stuff I shouldn’t worry too much about the fact that multiple requests will be needed. (The gain of flexibility and ‘appropriate sizing’ is far bigger IMHO)
Having said that however, I do think one should try to benefit from possible caching on the browser side: Setting up your http server to send out the css file with proper caching directives will be a lot more beneficial (the discussion is no longer about will there be 1 or 5 files downloaded to build up the page, but rather will those downloads happen once per page, per session, per visitor, ….) Given the numbers (for successful websites) there is a far bigger gain to be made here in both strain on the server and faster rendering on the browser.
In that respect some ideas could be taken from yui’s strategy:
I find the double appearance of files too very confusing. It’s probably my programming background (Java) but the ‘less surprising’ strategy IMHO would be to only maintain the actual source files in svn, and introduce some mechanism for ‘building’ a trunk-based release out of that. (I think the higher effort on blueprint developers of this approach will easily be gained back by the easier way of working for all the users)
Typical svn structure then becomes: src / : here comes whatever actual structure to keep the different css and plugins nicely separate
build / : (in stead of ‘build’ one can call it ‘target’ or ‘compressed’) here comes the same structure but post-processed by some build-script thinking about the previous remark this might introduce a parent folder holding the current release number: build/0.7-dev/ Most important thing is that this folder is added to the svn:ignore (thus not checked in)
build-release.txt : a simple text file containing the release number. in trunk that would be 0.7-dev when making an official release, this should be “fixed” to a non-suffixed version before making the svn-tag. i.e “0.7” and then switched back into 0.8-dev before committing into svn. The script described below will use this:
scripts/build.rb : a well written build script that ‘creates’ the build-folder this might include validation, compression, maybe even aggregation (for those that still think single css files are really needed) it should be a small effort to let this also bundle up the zip for a real release.
Another thing this would bring is the ability to easily switch my ongoing project development versus different (even trunk) versions of blueprint.
Since the ‘built/released’ structure would exactly match the source structure (bar being compressed, but that is not an issue for testing) one can easily switch (adapting a shortcut/symbolic link e.g. named ‘latest’) between bp versions.
This ability will allow people to
Me too is wondering what happened - or better - will happen to those in the future?
financieeladvies says:
I really like the drawing for the blueprint new directory structure. Now it is very clear that the print.css and ie.css files in the src directory are the uncompressed versions of the top-level files with the same names.
dış cephe says:
thanks friends.
hekimboard says:
teşekürler arkadaşlar.
fibercement says:
I was suggesting you could leave the 3 top level files out of the framework.
turksiding says:
thanks a lot.