diff options
| -rw-r--r-- | railties/guides/source/credits.html.erb | 4 | ||||
| -rw-r--r-- | railties/guides/source/glossary.textile | 424 |
2 files changed, 428 insertions, 0 deletions
diff --git a/railties/guides/source/credits.html.erb b/railties/guides/source/credits.html.erb index da6bd6acdf..00cf765b77 100644 --- a/railties/guides/source/credits.html.erb +++ b/railties/guides/source/credits.html.erb @@ -70,3 +70,7 @@ Ryan Bigg works as a consultant at <a href="http://rubyx.com">RubyX</a> and has <%= author('Heiko Webers', 'hawe') do %> Heiko Webers is the founder of <a href="http://www.bauland42.de">bauland42</a>, a German web application security consulting and development company focused on Ruby on Rails. He blogs at the <a href="http://www.rorsecurity.info">Ruby on Rails Security Project</a>. After 10 years of desktop application development, Heiko has rarely looked back. <% end %> + +<%= author('Adam Hawkins', 'adman65') do %> + Ruby developer and founder of <a href="http://threadedlabs.com">ThreadedLabs</a> a modern web shop. You can read his blog at <a href="http://broadcastingadam.com">Broadcasting Adam</a> +<% end %> diff --git a/railties/guides/source/glossary.textile b/railties/guides/source/glossary.textile new file mode 100644 index 0000000000..099a35bc52 --- /dev/null +++ b/railties/guides/source/glossary.textile @@ -0,0 +1,424 @@ +h2. Rails Glossary + +This is a beginner guide to common terms, projects, and things you will come across when +working with Rails. The glossary is here to provide you introductory material on each +topic so you can learn more. When you come across a topic you're not familiar with, +you can check here. + +endprologue. + +h3. Acceptance Testing + +Acceptancing testing is the act of testing use cases. Test cases are written +in a way that describes a use case. Then a test case is passing it can be +accepted. Cucumber is a good tool for acceptance testings. Work with your +stake holder to develop tests that represent use cases. When the test is +complete the feature should be accepted. Acceptance testing is focused +around people outside the code development accepting features. + +h3. Application Servers: Thin, Passenger, Unicorn + +These are all application servers. They interact with your Ruby code +and respond to requests. They are integrated with web servers like Nginx +or Apache to server you application on the internet. Some also serve +the application by itself. You can +rackup+ a rack app and serve it with +Thin right away. + +h3. Assets + +Assets are static files that are part of your application. They include: images, sytlesheets, scripts, or fonts. +Essentially, anything that needs to be server with your code for your app to run is +an asset. The asset pipeline gives you an easy way to manage all the different files. + +h3. Authentication + +Authentication is the process of matching credentials to a person and +verifying them. Authentication is purely about identifiying who the +user is–and not what they can do. +"Sorcery":https://github.com/NoamB/sorcery is an example of an authentication library. + +h3. Authorization + +Authorization is the process for determine what a specific user can do. +Authorization usually involves permission or role based systems. +"CanCan":https://github.com/ryanb/cancan is an example of an authorization library. + +h3. Behavior Driven Development (BDD) + +Is essentially the same as TDD except using a different set of tools +to express code in terms of user facing behavior. +"Rspec":https://github.com/rspec/rspec and "Cucumber":https://github.com/cucumber/cucumber are part of the BDD toolbox. + +h3. Bundler + +Bundler reads a Gemfile and calculates a set of version requirements +to make all the specified gems live happily together. It will prevent +version conflicts and infamous ‘gem already activated error’. It allows +you to install git gems or standard gems from rubygems.org. It does +not require libraries, it simply makes them available. It is up to you +require them in your programs. However, Rails will automatically setup bundler when your application boots. + +h3. Capistrano + +Capistrano is a tool for executing command one groups of remote +(or local) serves over SSH. It is primary used to deploy +Ruby (on Rails) applications. It has support for multistage environments. +Example, staging and production. You can easily write your own +tasks similar to writing rake task. It is the preferred way deploy Rails applications. + +h3. Capybara + +Capybara is a gem designed to provide an abstraction layer between +different browser drivers. It is primarily used in integration testing +to interact with the web server. It provides an API to navigate between +pages, click buttons, fill in forms, and other user interactions. It has +adapters for many different browser drivers. Notable drivers include +Selenium, rack-test and webrat. It is primary used in acceptance testing. + +h3. CoffeeScript + +CoffeeScript is a JavaScript superset. It aims to solves some problems +with JavaScript. It has some syntatical sugar around creating colsures and +objects. It supports for splat arguments. CoffeeScript files are compiled +into JavaScript files. CoffeeScript is usually called CS. You'll often see +CS/JS in reference to CoffeeScript and Javascript. + +h3. Compass + +Compass is a library built around SASS abstractions. It provides mixins +for many common things like styling buttons and forms. It is also easy +to extend and comes with many built in functions. The blueprint CSS +framework is bundled by default. + +h3. Cucumber + +Cucumber is a test framework for creating plain english acceptance +tests. The tests can be executed automatically. Cucumber is used for +integration testing web applications. The test suite is often used in CI +(Continuous Integration). Cucumber uses a language called Gherkin to +parse files into lines and match them against regular expressions. +Regular expressions are matched with code blocks. Your test code lives +in these blocks. + +Cucumber tests are divided up into "Feature" files. Each feature has +many "scenarios." Features are like use cases. Scenarios are different +permutations of that use case. Here is an example Feature file: + +<pre> +Feature: Make Widthdrawls from Accounts + As an account holder + I want to use my money + In order to use it buy thing + + Background: + Given I have account under "RubyX" + And my account is activated + + Scenario: There is enough money in my account + Given my account has "$1,000" + And I'm at the bank + When I widthdraw "$500" + Then my account should have "$500" + + Scenario: There is not enough money in my account + Given my account has "$1,000" + And I'm at the bank + When I widthdraw "$500" + Then the teller should reject my transaction +</pre> + +Here is an example step definition: + +<ruby> +Given /I'm at the bank/ do + # set up pre conditions +end + +Then /the teller should reject my transaction/ do + # assert on things +end +</ruby> + +h3. DSL + +DSL stands for Domain Specific Language. They are crafted to solve one +or more problems very eloquently and nothing more. For example, a DSL +created to declare work order would be horrible suited for writing +Photoshop. DSLs are usually wrappers around more complicated methods +that make it easier to express the intent of the underlying code from +a programmer's perspective. You may have used a DSL before and +not realized it. Here is an example from Sunspot's search +functionality. It's designed for describing a search and nothing more: + +<ruby> +Post.search do + fulltext 'best pizza' + with :blog_id, 1 + with(:published_at).less_than Time.now + order_by :published_at, :desc + paginate :page => 2, :per_page => 15 + facet :category_ids, :author_id +end +</ruby> + +h3. ERB + +ERB is Embedded Ruby. ERB is built into the Ruby core. It allows to to +place Ruby inside other files. For example, placing Ruby inside HTML. +Here is an example: + +<erb> +<div class="<%= @ticket.state %>" + <p><%= @ticket.message %></p> +</div> +</erb> + +h3. Factories - FactoryGirl & Fabrication + +These are two popular libraries for creating object factories. They are +usually used in test suites and population scripts. They provide a +default set of attributes and allow programmers to specify the +attributes they care about at creation time. Factories are commonly used +to replace fixtures. + +h3. Fixtures + +Fixtures are static objects used in test cases. You may have a fixtures for specific +test cases to build up needed preconditions. Fixtures are commonly used to represent +data in a table. Fixtures are stored in YML and are loaded by a test library. +Fixtures become hard to main at scale. They are often replaced with Factories because +it's easier to generate an object at runtime then maintain a static file with its +attributes. + +h3. Gem + +A gem is a resuable library of Ruby code. Gems are hosted on "RubyGems":http://rubygems.org. +They are managed with the +gem+ command or with bundler. Rails is +distributed as a gem. + +h3. Git + +Git is a distributed version control system. Each user has a complete +copy of the repository. Changes can be pushed back to the remote +repositories for others to pull or push from. Linus Torvalds created Git +because he was unsatisfied with other version control systems like CVS +or SVN. Do not get GitHub confused with Git. GitHub is simply a service +for hosting the main Git repository. You can use git independent of +github, however most Ruby developers use github exclusively. + +h3. HAML + +HAML is an HTML abstraction language. It's great for structuring +documents and horrible to content. It will autoclose tags and lets you +specify attributes as a hash. You can also include ruby code inside +the templates. Here is an example: + +<pre> +.post#post_5 + .content= simple_format(@post.content) +</pre> + +h3. Heroku + +Ruby PaaS (Platform as a Service). They provide free cloud hosting for +Rack applications with paid plans for increased resources. It is a very +easy way to deploy your first application. Beware, they are easily owned +by Amazon's AWS failure. + +h3. Integration Testing + +Integration testing referes testing different modules of code in concert. +Ingration testing tests that all the parts of your system are working correctly. +It is different than unit testing because it involves more than one component +at at time. Integration tests for rails apps usually mean submitting web requests +and see how they are handled. You can take this a step further and move into +acceptance testing which simulates a user in front of your application. +Integration tests are written "outside in" meaning they only focus on +the outward functions of your system. + +h3. Less + +Less is a library for writing stylesheets. It enables you to do things +like use variables and other handy things. Less files are compiled into +vanilla CSS files. It is similar to SCSS/SASS. Twitter Bootstrap is written in Less. + +h3. Metaprogramming + +Metaprogramming is a term for dynamically generating code at runtime. +Metaprogramming is why Rails feel the way it does. ActiveRecord +associations to dynamically add methods to your classed based on how to +declare them. Metaprogramming is possible in Ruby because it's a dynamic +language interpreted at run time. + +h3. Nonrelational Databases (NoSQL) + +Nonrelational databases are the oppposte of relational databases. They +are usually more free form and don't have defined schemas (like tables.) +There is no such thing as SQL for non relational databases because each +one uses it's own langauge to inster and retreive data. MonogDB is +the most popular nonrelationable database. + +h3. Open Classes & Monkey Patching + +Ruby has open classes. This means you can simply declare methods insides +a class that's already been defined. ActiveSupport uses open classes to +add all those nice methods to core Ruby objects. This is how you can add +a method to the `String` class: + +<ruby> +class String + def lulz + puts "lulz " * self.length + end +end + +"Hey".lulz +</ruby> + +h3. ORM - Object Relational Mapping + +ORM's provide a way to map one object into some sort of persistent storage. +ActiveRecord is a well known ORM that implements that Active Record pattern. +ActiveRecord allows you persist objects into a relational database. ActiveRecord +is not the only ORM. Datamapper and Sequel are also popular for relational databases. +Mongoid is popular for MongoDB (a nonrelational database.) + +h3. Relational Databases + +Relational databases store data into tables with columns. Each column has a +type of data. For example: numbers, text, or dates. Data is retrieved +using SQL. ORM's are commonly used to make it easier to work with data +in retional databases. PostreSQL and MySQL are examples of popular +realtional databases to use with Rails. + +h3. Rack + +Rack is a standard interface for writing web applications in Ruby. +Rails as of version 3 is a Rack app. Rack defines things like HTTP requests +and how your code is called. Rack applications are easily served by application +servers such as Thin. + +h3. Rake + +Rake is like the Ruby version of make. You can create custom tasks that +can be executed from the command line. `rake db:migrate` is a classic +example. You can create as many tasks as you want. They can have +prerequisites. They can also be in namespaces. A ':' designates tasks in +different namespace. `db:migrate` means 'db' namespace, 'migrate' task. +Multiple tasks can be executed in one go like so: `rake db:create +schema:load`. They will be executed in the order they are listed. Rake +was originally designed to be like make, but is often used to execute +arbitrary code outside an application context. A cron job is a perfect +example. + +h3. RSpec + +Rspec is a unit testing framework. It is based around the idea that test +should describe behavior of classes in an english like way. Test files +are called "specs". Spec files are divided into "examples." Examples +contain matchers. Spec files can share examples. Here is an example +spec_file: + +<ruby> +require 'spec_helper' + +describe Post do + it { should have_many(:comments) } + + describe "Post#out_dated?" do + subject { Post.new :created_at => 2.months.ago } + + it { should be_outdated } + end +end +</ruby> + +h3. RVM + +Rvm stands for Ruby Version Manager. It is a set of bash script designed +to allow you switch out Ruby interpreters on the fly. It manages +installed ruby interpreters and makes is very easy to install different +implementations. It also manages Gemsets. Gemsets are groups of gemsets +that are distinct from other groups (except the global gemset which +shares gems between different ruby interpreters). + +h3. Rbenv + +Rbenv was created to address some flaws in RVM. It does the same thing +as RVM in a different way. It allows you manage different Ruby versions +and switch between them. + +h3. SASS & SCSS + +SASS and SCSS are CSS abstraction languages. They are compiled down to +CSS. They allow you use variables, modules and include other files. +In short, they make it much easier to write and main large amounts of +CSS. + +h3. SQL - Structured Query Language + +SQL is the standard language for talking to relational database. It's sole +purpose is to describe what to get from the db, and now how to get it. +SQL is based on simple concepts like selects and joins. You select columns +from tables that you want back. You can define conditions to further refine +your query or use joins to connect more than one table together. + +h3. Selenium + +Selenium is a library that simulates user interaction with a browser. It +runs the full browser. Selenium works best in FireFox, but can work in +Chrome and other browsers. Commands are sent across as JavaScript which +the browser evaluates to complete each action. Selenium is the most +complete solution for simulating a user for your web application. + +h3. Unit Testing + +Unit testing refers to testing small units of code insolation. This +makes it easier to determine if individual modules of code are functioning +directly. You can do unit testing with many different libraries. +Test::Unit+ +is the Rails default. + +h3. Test Driven Development (TDD) + +The practice of writing a failing test first then completing the +implementation. This makes the developer spend more time thinking about +the code upfront while providing a solid test suite for the entire +application. You can use Test::Unit for TDD in Ruby. + +h3. Test::Unit + +Test::Unit is a unit test framework built into Ruby 1.8. It is known as +MiniTest in 1.9. It provides functionality for writing test cases with +standard setup and tear down. Rails generates test files built in +Test::Unit by default. It provides basic assertions. It's similar to +jUnit or any member of the xUnit family. Here is an example: + +<ruby> +require 'test_helper' + +class PostTest < Test::Unit::TestCase + + def test_out_dated? do + post = Post.new :created_at => 2.months.ago + assertTrue(post.out_dated?) + end +end +</ruby> + +h3. UJS (Unobstrusive JavaScript) + +Unobtrusive JavaScript means separating JavaScript from the HTML. +Specifying an `onClick` attribute in HTML is consider obtrusive because +it obfuscates the markup. It is also hard to maintain because your +javascript is harder to maintain. You can do the same thing +unobtrusively by using jQuery to find the element by a class name and +applying a click handler. Essentially UJS means keep JavaScript in .js +files and HTML in .html files. Separation of church and state if you +will. + +h3. Webrat + +Webrat is the original headless browser. It's similar to selenium, but +much more implemented. It does not execute JavaScript and does not +execute in a GUI. It is the most basic driver and is perfect for +interacting with simple websites. |