├── README.markdown └── dir-structure.markdown /README.markdown: -------------------------------------------------------------------------------- 1 | # README 2 | 3 | This document is not yet complete. It's a draft and it's under heavy development. To help, please go into [Issues](https://github.com/kuroir/AVA-Pattern/issues) and take part into the open available issues. Your opinions are really useful! 4 | 5 | 6 | # Arrangement for View Assets Pattern 7 | 8 | - [Introduction to the AVA Pattern](#introduction) 9 | - [Why do we need the AVA Pattern](#) 10 | - [What do I get from the AVA Pattern, besides consistency?](#) 11 | - [/images/ Directory Convention](#images) 12 | - [Grouping Rules](#images/grouping-rules) 13 | - [Naming Rules](#images/naming-rules) 14 | - [Examples](#images/examples) 15 | - [/javascripts/ Directory Convention](#javascripts) 16 | 17 | 18 | 19 | ## Introduction to the AVA Pattern 20 | 21 | In the recent years, we’ve been seeing a lot of improvements on the organizational procedures for web applications. More specifically, the MVC Pattern, which greatly improved development speeds by imposing a well structured architecture. This allowed developers to feel at home with any application that uses the pattern. 22 | 23 | The Model-View-Controller (MVC) Pattern is oriented to the back-end. There’s a specification about where to store your interface related code, the View, but there’s no real specification regarding how and where you should store your assets. This is where the Arrangement for View Assets (AVA) Pattern shines. 24 | 25 | The AVA Pattern works side by side with the MVC Pattern. Both are framework and language agnostic, and independent of each other, but together you can achieve a better organization which will improve productivity, especially during advanced stages of the application. 26 | 27 | Take this with a grain of salt and remember that you should always use what your team is accustomed to; these conventions may be modified to fit your project, however, try to follow the general idea about the structure. 28 | 29 | For instance, you may want use snake_case over the dash-case naming pattern; these types of modifications are a matter of preference. 30 | 31 | ### Why do we need the AVA Pattern? 32 | 33 | You may think that there's a steep learning curve involved with the AVA Pattern however, this is not the case. The main objective of the AVA Pattern is to provide written documentation for you, and your team, to consult when in doubt about how to store your assets. 34 | 35 | ### What do I get from the AVA Pattern, besides consistency? 36 | 37 | The main plus you'll get from the AVA Pattern is consistency. And, that alone is something that is worth your time. Consistency is not something you should only want to achieve when you're working on a team, but it's something you should aim for, for your own sake. 38 | 39 | Think of the following use cases: 40 | 41 | - As a Freelancer 42 | - The odds are that you're going to work alone on a project. You complete the project and months later you might need to get back in and support or change something. Chances are you completely forgot about the file structure and file names of the project. You'll spend some time trying to figure out your own code. 43 | - As a member of a Development Team 44 | - You're part of a team that has another front-end Engineer besides you. Everything is fine and dandy till he begins naming files under a completely different directory than the one you set. After some time you can notice who made what just by how it's stored. 45 | - As a Team Leader 46 | - You can instill some sort of structure for assets when working on multiple projects. This will allow assignment of team members to different projects, as needed, without having to worry about a team member learning a wildly different asset structure. 47 | - As an Outsourcer 48 | - Having different developers coming in and working on a code base on a contracted basis can create much confusion when it comes to the way that assets are handled. The AVA pattern will give a common way for different developers to save assets, and give you, the outsourcer, that much more control over your code. 49 | 50 | ## Overview of the Structure. 51 | 52 | Need to write some stuff here.. 53 | 54 | /stylesheets/ # Documented? Soon. 55 | style.css 56 | handheld.css 57 | /images/ # Documented? ✓ 58 | /javascripts/ # Documented? (needs more examples) 59 | tests/ 60 | qunit/ 61 | index.html 62 | tests.js 63 | libs/ 64 | jquery-1.5.1.min.js 65 | jquery-1.5.1.js 66 | modernizr-1.7.min.js 67 | dd-belatedpng.js 68 | plugins.js 69 | script.js 70 | 71 | 72 | ## /images/ Directory Convention 73 | 74 | Conventions save you from having to figure out how the project is structured. The following conventions are the result of testing and polishing rules on production environment over the years. 75 | 76 | 77 | ### Grouping Rules 78 | 79 | Grouping is important; especially when you're working with projects that have many assets. The following rule proposes a way to organize these files into an easy to navigate way. 80 | 81 | RULE 82 | IF images FROM same GROUP > 5 83 | store in new directory 84 | repeat RULE 85 | else 86 | store in root 87 | 88 | This rule may loop a max of 3 times. Having too many levels is not advised since it may make everything more complex to mantain in the long run and will make your css file bigger. 89 | 90 | 91 | ### Naming Rules 92 | 93 | Names for individual files should always be **singular**, even if they're sprites that contains several elements. This is, by convention, a good practice that is taken from other web related frameworks. 94 | 95 | Sub-Directories a.k.a. Groups should be named in their **plural** form when possible. Remember, this only applies to directories. For files, use the singular variant. 96 | 97 | This whole plural/singular paradigm is to follow web frameworks and database naming conventions; think of it as a general recomendation. 98 | 99 | 100 | background files: 101 | bg(-group)?(-name) 102 | sprites: 103 | sp(-group)?(-name) 104 | buttons: 105 | bt(-group)?(-name) 106 | icons: 107 | ic(-group)?(-name) 108 | other: 109 | (group-)?(name) 110 | 111 | When the file is going to have several variants, it's a good practice to append the change in type or dimension using the following pattern. 112 | 113 | (name)((-WIDTHx)(HEIGHT)?)? 114 | 115 | Please note 116 | 117 | logo-300x.jpg 118 | logo-500x250.jpg 119 | logo-500x300.jpg 120 | logo-300x-grayscale.jpg 121 | 122 | Notice that you're not forced to add the height when there's no variation to that file. The `x` is still left in place to denote that we're talking about width and not height: 123 | 124 | 50x <- 50 width 125 | x50 <- 50 height 126 | 127 | 128 | ### Examples 129 | 130 | Need to document this further. 131 | 132 | /bg-body.jpg 133 | /bg-content.jpg 134 | /bg-content-light.jpg 135 | /sp-main.jpg 136 | /ic-form-submit.jpg 137 | /placeholders/ 138 | content-big.jpg 139 | content-small.jpg 140 | content-medium.jpg 141 | user-display-100x.jpg 142 | user-display-200x.jpg 143 | video-medium.jpg 144 | 145 | 146 | ## /javascripts/ Directory Convention 147 | 148 | Previously /scripts/ - scripts was thought too general. 149 | 150 | * DHH voted for javascripts. 151 | * It maches rails conventions. 152 | * It's better than `js`. 153 | 154 | ## Credits 155 | 156 | Original Paper and Idea by [Mario Ricalde](http://mario.ricalde.mx). With the help of many people including: 157 | 158 | - [David Heinemeier Hansson](http://www.loudthinking.com/) 159 | - [Paul Irish](http://paulirish.com/) 160 | - [Chris Eppstein](http://twitter.com/chriseppstein) 161 | - [Armando Canals](http://twitter.com/armandocanals) 162 | - [Daniel Fischer](http://www.danielfischer.com/) 163 | -------------------------------------------------------------------------------- /dir-structure.markdown: -------------------------------------------------------------------------------- 1 | 2 | Splitting the code: 3 | 4 | - Global (Site Context) 5 | - Goes in the bootstrapper file. 6 | - Page Context (Specific to current page) 7 | - Layouts 8 | - Stores general dimentions. 9 | - Pages 10 | - Homepage 11 | - Tour 12 | - Subscriptions 13 | - Course Builder 14 | - Objects (General Purpose classes and ids) & Interaction States 15 | - Shared 16 | - Contents 17 | - Headers 18 | 19 | 20 | 21 | 22 | /stylesheets/ 23 | vendor/ 24 | survival-kit/ # Has custom dir and partials. 25 | ... 26 | jquery-ui/ # Has custom dir and partials. 27 | ... 28 | 29 | app/ # Type 30 | _forums.scss # Include files, define resource variables and global classes (for @extension) 31 | _posts.scss # Include files, define resource variables and global classes (for @extension) 32 | _comments.scss   # Include files, define resource variables and global classes (for @extension) 33 | forums/ 34 | _index.scss 35 | _show.scss 36 | _new.scss 37 | _edit.scss 38 | posts/ 39 | _index.scss 40 | _show.scss 41 | _new.scss 42 | _edit.scss 43 | comments/ 44 | _index.scss 45 | _show.scss 46 | _new.scss 47 | _edit.scss 48 | layouts/ # Where all Layout information is stored. 49 | _application.scss # The base. 50 | _forums.scss # Layout for the forums. 51 | _blog.scss # "Inhertis" application layout and modifies it. 52 | shared/ # Shared information would be stored here. 53 | _headers.scss # Header 54 | _footers.scss 55 | _contents.scss 56 | mobile/ # Type 57 | _forums.scss # Include files, define resource variables and global classes (for @extension) 58 | _posts.scss # Include files, define resource variables and global classes (for @extension) 59 | _comments.scss   # Include files, define resource variables and global classes (for @extension) 60 | forums/ 61 | _index.scss 62 | _show.scss 63 | _new.scss 64 | _edit.scss 65 | posts/ 66 | _index.scss 67 | _show.scss 68 | _new.scss 69 | _edit.scss 70 | comments/ 71 | _index.scss 72 | _show.scss 73 | _new.scss 74 | _edit.scss 75 | shared/ 76 | _headers.scss 77 | _footers.scss 78 | _contents.scss 79 | 80 | mobile.scss # Include files, define resource variables and global classes (for @extension) 81 | app.scss # Include files, define resource variables and global classes (for @extension) 82 | 83 | /images/ 84 | vendor/ # Images related to a vendor library. 85 | survival-kit/ 86 | ... 87 | jquery-ui/ 88 | ... 89 | app/ # Images related to the 'app' version of the site. 90 | bg-header.png 91 | bg-content.png 92 | sp-user-interface.png 93 | mobile/ # Images related to the 'mobile' version of the site. 94 | bg-header.png 95 | bg-content.png 96 | sp-user-interface.png 97 | 98 | /javascripts/ 99 | tests/ # Tests. 100 | .. 101 | vendor/ 102 | survival-kit/ 103 | .. 104 | jquery-ui/ 105 | .. 106 | app/ # JS Files for 'mobile' 107 | forums.coffee # Rails way, one file per controller. 108 | posts.coffee 109 | comments.coffee 110 | shared/ 111 | functionality-1.coffee 112 | functionality-2.coffee 113 | mobile/ # JS Files for 'mobile' 114 | forums.coffee 115 | posts.coffee 116 | comments.coffee 117 | shared/ 118 | functionality-1.coffee 119 | functionality-2.coffee 120 | mobile.js # Includes all mobile/ js files 121 | app.js # Include all app/ js files --------------------------------------------------------------------------------