Permalink
Browse files

Merge branch 'master' of git://github.com/sproutcore/sproutguides int…

…o records
  • Loading branch information...
2 parents 969bcf4 + 04f130f commit 394b8c5612aab3977650789cee4751bed7e47ee4 Florian Kugler committed Feb 7, 2011
Showing with 459 additions and 8 deletions.
  1. +16 −8 Gemfile.lock
  2. +7 −0 guides.yml
  3. +384 −0 source/chance.textile
  4. +7 −0 source/getting_started.textile
  5. +45 −0 source/install.textile
View
24 Gemfile.lock
@@ -1,3 +1,15 @@
+PATH
+ remote: /Users/peterwagenet/Programming/Ruby/guides
+ specs:
+ guides (0.6.5)
+ RedCloth (~> 4.1.1)
+ actionpack (~> 3.0.0)
+ activesupport (~> 3.0.0)
+ maruku (~> 0.6.0)
+ rack (~> 1.2.1)
+ thin (~> 1.2.7)
+ thor (~> 0.14.6)
+
GEM
remote: http://rubygems.org/
specs:
@@ -23,19 +35,15 @@ GEM
erubis (2.6.6)
abstract (>= 1.0.0)
eventmachine (0.12.10)
- guides (0.6.5)
- RedCloth (~> 4.1.1)
- actionpack (~> 3.0.0)
- activesupport (~> 3.0.0)
- rack (~> 1.2.1)
- thin (~> 1.2.7)
- thor (~> 0.14.6)
i18n (0.5.0)
+ maruku (0.6.0)
+ syntax (>= 1.0.0)
rack (1.2.1)
rack-mount (0.6.13)
rack (>= 1.0.0)
rack-test (0.5.7)
rack (>= 1.0)
+ syntax (1.0.0)
thin (1.2.7)
daemons (>= 1.0.9)
eventmachine (>= 0.12.6)
@@ -47,4 +55,4 @@ PLATFORMS
ruby
DEPENDENCIES
- guides (~> 0.6.5)
+ guides!
View
7 guides.yml
@@ -14,9 +14,16 @@ authors:
- name: Jason Zimdars
nick: jz
description: Jason Zimdars is an experienced creative director and web designer who has lead UI and UX design for numerous websites and web applications. You can see more of his design and writing at <a href="http://www.thinkcage.com/">Thinkcage.com</a> or follow him on <a href="http://twitter.com/JZ">Twitter</a>
+ Contributors:
+ - name: Shawn Morel
+ nick: shawnmorel
+ description: Shawn Morel is a software generalist with lots of experience building user interfaces in Cocoa, Flex, and bare-bones HTML.
index:
Start Here:
+ - title: Install
+ url: install
+ text: "In this guide we'll walk you through installing SproutCore."
- title: Getting Started
url: getting_started
text: "Jump start your SproutCore development by playing along as we build a fully functional Todo List application."
View
384 source/chance.textile
@@ -0,0 +1,384 @@
+h2. Using Chance
+
+This guide covers using Chance, SproutCore's CSS framework. You'll
+learn to:
+
+* Use SCSS syntax to reduce code and keep it clean.
+* Use +$theme+ to simplify rules.
+* Use the +@include slice+ directive to include images.
+* Use the +@include slices+ directive for multi-slice scaling.
+
+endprologue.
+
+h3. What Is Chance?
+
+Chance is SproutCore's CSS preprocessor. All CSS in your app goes through Chance.
+
+In addition to having its own CSS extensions, Chance includes "*_SCSS_*":http://sass-lang.com/.
+Even with all of these extensions, Chance is a superset of CSS. This means that
+all normal CSS will still "just work."
+
+WARNING: Chance expects to work with a SproutCore theme. Recent releases of the SproutCore build tools will set everything up for you, but if your app doesn't have a +theme.js+ file, you need to follow the directions in "Theming Your App: Giving Your App a Theme":theming_app.html#giving-your-app-a-theme
+
+h3. SCSS
+
+As much as we'd like to take credit for SCSS, we cannot: it does not stand
+for "SproutCore Stylesheets." It actually stands for "Sassy CSS" because it
+is part of "Sass:" "Syntactically Awesome Stylesheets":http://sass-lang.com/.
+
+NOTE: Although Sass's own build tool only sends files with the extension +.scss+ through the SCSS processor, SproutCore sends _all_ CSS, including +.css+ files, through SCSS. Give your files the +.css+ extension.
+
+SCSS has many features. We'll cover the ones most useful for theming SproutCore.
+For full reference, refer to the official SCSS documentation.
+
+h4. Nesting
+
+You know those dolls that fit one inside the other? Nesting looks a little like that:
+
+<css>
+.yo-dawg {
+ color: blue;
+
+ .i-put-a-rule-in-your-rule {
+ color: red;
+
+ .so-you-can-style-while-you-style {
+ color: green;
+ }
+ }
+}
+</css>
+
+But what does it mean? Well, CSS should roughly map to HTML. So, what might some "nested" HTML look like?
+
+<html>
+<div class = 'yo-dawg'>
+ <div class = 'i-put-a-rule-in-your-rule'>
+ <span class = 'im-not-typing-that-long-class----ohwait'></span>
+ </div>
+</div>
+</html>
+
+Aside from the +class-that-shall-not-be-typed+, the above HTML is what our example
+CSS is meant to match. The nesting gets converted:
+
+<css>
+.you-dawg {
+ color: blue;
+}
+
+.yo-dawg .i-put-a-rule-in-your-rule {
+ color: red;
+}
+
+.yo-dawg .i-put-a-rule-in-your-rule .you-know-what {
+ color: green;
+}
+</css>
+
+Nesting helps you reduce repetition of class names. The nesting in your CSS matches
+your nesting of HTML elements: if rule B is inside rule A, it will match descendants
+of elements that match rule A.
+
+h4. &amp;.another-rule
+
+Nesting is nice to match elements inside of each other, but what about when you
+want to use nesting to match a single element?
+
+For instance, a SproutCore button has normal, active, selected, and active
+selected states. The normal state doesn't have a class name; the others have
+class names +active+, +sel+, and +active sel+.
+
+Without nesting, this looks like:
+
+<css>
+$theme.button {
+ ...
+}
+
+$theme.button.active {
+ ...
+}
+
+$theme.button.sel {
+ ...
+}
+
+$theme.button.active.sel {
+ ...
+}
+</css>
+
+But nesting won't work: We can't nest +active+ inside +button+ because it needs to
+match the same element!
+
+&amp;. SCSS provides &amp;. And it basically does exactly what we want, continuing
+the parent selector:
+
+<css>
+$theme.button{
+ ...
+
+ &.active {
+ ...
+ }
+
+ &.sel {
+ ...
+
+ &.active {
+ ...
+ }
+ }
+}
+</css>
+
+h4. Variables
+
+You can define variables:
+
+<css>
+$width: 5px;
+
+.my-thingy {
+ width: $width;
+}
+</css>
+
+If you want to share your variable between files, you have to make sure they are loaded
+in the right order. The +sc_require()+ function does this:
+
+<css>
+// file1.css
+$width: 5px;
+
+// file2.css
+// call sc_require to make sure file1 loads first:
+sc_require("file1.css");
+
+.my-thingy {
+ width: $width;
+}
+</css>
+
+
+
+h3. +$theme+ Variable
+
+Chance has a special "variable":#variables: +$theme+. It contains your theme's
+class names. Using +$theme+, you can write just +$theme.button { ... }+ to style
+a button.
+
++$theme+ gets its initial value from the +:css_theme+ property in your app's '+Buildfile+:
+
+<ruby>
+config :my_app, ... :css_theme => "ace.my-app"
+</ruby>
+
+h4. +@theme+ Directive
+
+Let's say you created MyAwesomeTheme. But you need a red variation for all of your
+app's error windows, error toolbars, etc. Creating a brand new theme
+doesn't make sense: it will still be MyAwesomeTheme, just a version for errors.
+
+As described in "Theming Your App":theming_app.html, you'll make a _child theme_:
+
+<javascript>
+MyAwesomeTheme.Error = MyAwesomeTheme.subtheme('error');
+</javascript>
+
+Now, any time one of your windows, toolbars, or controls sets +themeName+ to +error+:
+<javascript>
+MyErrorWindow = SC.Pane.design({
+ themeName: 'error',
+ ...
+})
+</javascript>
+
+It and all of its children will automatically use your +MyAwesomeTheme.Error+ theme,
+and will get class names like +ace my-awesome-theme error+.
+
++MyAwesomeTheme.Error+ is *_nested inside_* +MyAwesomeTheme+. Just like how
+SCSS's nesting matches DOM structure, Chance has a tool to match this SproutCore
+theme structure:
+
+<javascript>
+$theme.button { /* normal styles here */ }
+
+@theme(error) {
+ $theme.button { /* error styles here */ }
+}
+</javascript>
+
+The +@theme(theme name)+ directive adds the theme name provided to the current
+theme names stored in +$theme+. All rules inside the +{+ and +}+ will be part
+of your subtheme.
+
+h3. +@include slice()+
+
+The +@include slice()+ directive lets you include an image in your CSS. You can
+include the whole image, or select a portion to extract.
+Chance will handle details like spriting or embedding as data: urls.
+
+To include an image, just pass the image name:
+
+<css>
+.my-image {
+ @include slice("my-image.png");
+}
+</css>
+
+That puts the image as the background. It doesn't do any "slicing," however.
+Where does the name come from?
+
+h4. Slicing
+
+Slicing in Photoshop can be annoying and difficult.
+
+Chance lets you slice your images directly in your CSS. To include a
+section of the image rather than the whole thing, pass arguments
+identifying a rectangle:
+
+<css>
+.my-image {
+ @include slice("my-image.png", $left: 3, $width: 3);
+}
+</css>
+
+You don't have to specify all parameters. For instance, if you only specify
+a left, the rectangle will go from there to the right edge. If you only
+specify a right, it will go from there to the left edge.
+
+The possible rectangle arguments are: +$left, $top, $right, $bottom, $width, $height+.
+
+h4. Repeating
+
+Rather than using +background-repeat+ for slices, you should use the +$repeat+ argument:
+
+<css>
+.my-image {
+ @include slice("my-image.png", $left: 3, $width: 1, $repeat: repeat-x);
+}
+</css>
+
+This lets Chance know that the image repeats, which can impact how it deals with the image.
+For instance, if Chance were to sprite the image, it would create separate sprites
+for each +repeat-x, repeat-y, and repeat-both+.
+
+h4. Offsetting
+
++@include slice+ and the +background-position+ property are incompatible. If you need
+to offset the position of a background image, you must use Chance's +$offset+ argument.
+
++$offset+ takes two numbers: an x offset and a y offset. For example:
+
+<css>
+.my-image {
+ @include slice("my-image.png", $width: 3, $offset: -1 0);
+}
+</css>
+
+This will move the background to the left by 1px.
+
+h3. +@include slices()+
+
+The plural of +slice+ is +slices+; as such, where +@include slice+ includes a
+slice as a background image, you might expect +@include slices+ to include
+_multiple_ slices as background images.
+
+You would be correct. +@include slices+ automatically generates CSS for
+multi-slice scalable backgrounds.
+
+Controls that support multi-sliced backgrounds all generate some HTML to support it.
+The HTML they generate follows a standard form that +@include slices+ matches.
+
+For instance, the controls may write:
+
+<html>
+<div class = 'left'></div>
+<div class = 'middle'></div>
+<div class = 'right'></div>
+</html>
+
+If you use +@include slices+ like this:
+
+<css>
+$theme.button {
+ @include slices("button.png", $left: 3, $right: 3);
+}
+</css>
+
+The generated CSS may look like this:
+
+<css>
+.ace.my-app.button .left {
+ background: ...
+}
+
+.ace.my-app.button .middle {
+ background: ...;
+ background-repeat: repeat-x;
+}
+
+.ace.my-app.button .right {
+ background: ...;
+}
+</css>
+
+h4. Slicing
+
+You pass the "middle rectangle" to +@include slices+. It will make slices at
+each side, generating up to nine slices: +top-left, top, top-right,
+left, middle, right, bottom-left, bottom, bottom-right+. Only slices that
+actually have content will be generated.
+
+For instance, the above example defines the following rectangle:
+
+!images/theming/button_slice.jpg!
+
+You may only use four arguments to specify the rectangle:
++$left, $top, $right, and $bottom+.
+
+Unlike +@include slice()+, +$width+ and
++$height+ are not valid.
+
+h4. +$fill+
+
+In a button, the +repeat-x+ segment usually only needs to be one pixel wide. But
+if you specify the middle rectangle as in the diagram above, it would repeat
+a much wider section! This would be very inefficient.
+
+Because the +repeat-x+ slices usually just need to repeat one pixel horizontally,
+Chance will by default only take one pixel. The setting that controls this behavior
+is called +$fill+.
+
+The default +$fill+ is +1 0+, which tells chance to grab only one pixel horizontally,
+but all the vertical pixels. If you wanted all the horizontal pixels as well, you
+could set +$fill: 0 0+. If you wanted to repeat a 15-pixel segment
+horizontally, you would specify +$fill: 15 0+:
+
+<css>
+$theme.button {
+ @include slices("button-capsule", $left: 3, $right: 3, $fill: 15 0);
+}
+</css>
+
+h4. +$skip+
+
+Sometimes you don't want to include all slices. For instance, let's say you
+want to theme a capsule-style button. You only need to override the images for
+the left and right sides: the design for the middle is unchanged.
+
+To avoid needlessly including the same data twice, skip the middle slice:
+
+<css>
+@theme(capsule) {
+ $theme.button {
+ @include slices("button-capsule", $left: 3, $right: 3, $skip: middle);
+ }
+}
+</css>
+
+You can supply a space-separated list of slices to skip. The possible slice
+names are +top-left+, +top+, +top-right+, +left+, +middle+, +right+,
++bottom-left+, +bottom+, and +bottom-right+.
View
7 source/getting_started.textile
@@ -0,0 +1,7 @@
+h2. Getting Started
+
+Here we'll step you through writing your first SproutCore app.
+
+TODO: fill this in
+
+endprologue.
View
45 source/install.textile
@@ -0,0 +1,45 @@
+h2. Install
+
+This guide covers installing SproutCore. By referring to this guide you will be able to:
+
+* Install a bundled version of SproutCore to build your desktop-class web app.
+
+endprologue.
+
+
+h3. Prerequisites
+
+You should already have Ruby 1.9 or later running on your system. If you need help installing Ruby please refer to the "RVM setup instructions":http://rvm.beginrescueend.com/
+
+NOTE: SproutCore will also run on Ruby 1.8.7 though Ruby 1.9 is recommended.
+
+h3. Installing
+
+The easiest way to install the pre-released version of SproutCore 1.5 is as a Ruby Gem:
+
+<shell>
+$ gem install --pre sproutcore
+</shell>
+
+Alternatively, if you want to use the latest stable release simply install the Gem as follows:
+
+<shell>
+$ gem install sproutcore
+</shell>
+
+The rest of these guides refer to SproutCore 1.5
+
+h3. Testing your Install
+
+To make sure that your system is configured correctly enter the following command:
+<shell>
+$ sproutcore help
+</shell>
+
+h3. Next Steps
+
+Great, you're good to go. You'll probably want to continue with the "Getting Started":getting_started.html guide.
+
+h3. Changelog
+
+* February 1, 2011: first pass at the user install docs by "Shawn Morel":credits.html#shawnmorel

0 comments on commit 394b8c5

Please sign in to comment.