diff options
Diffstat (limited to 'railties/guides')
| -rw-r--r-- | railties/guides/source/active_support_instrumentation.textile | 39 | ||||
| -rw-r--r-- | railties/guides/source/asset_pipeline.textile | 2 | ||||
| -rw-r--r-- | railties/guides/source/credits.html.erb | 4 | ||||
| -rw-r--r-- | railties/guides/source/glossary.textile | 424 |
4 files changed, 468 insertions, 1 deletions
diff --git a/railties/guides/source/active_support_instrumentation.textile b/railties/guides/source/active_support_instrumentation.textile new file mode 100644 index 0000000000..f9452400ad --- /dev/null +++ b/railties/guides/source/active_support_instrumentation.textile @@ -0,0 +1,39 @@ +h2. Active Support Instrumentation + +Active Support is a part of core Rails that provides Ruby language extensions, utilities and other things. One of the things it includes is an instrumentation API that can be used inside an application to measure certain actions that occur within Ruby code, such as that inside a Rails application or the framework itself. It is not limited to Rails, however. It can be used independently in other Ruby scripts if it is so desired. + +In this guide, you will learn how to use the instrumentation API inside of ActiveSupport to measure events inside of Rails and other Ruby code. We cover: + +* What instrumentation can provide +* The hooks inside the Rails framework for instrumentation +* Adding a subscriber to a hook +* Building a custom instrumentation implementation + +endprologue. + +h3. Introduction to instrumentation + +The instrumentation API provided by ActiveSupport allows developers to provide hooks which other developers may hook into. There are several of these within the Rails framework, as described below in <TODO: link to section detailing each hook point>. With this API, developers can choose to be notified when certain events occur inside their application or another piece of Ruby code. + +For example, there is a hook provided within Active Record that is called every time Active Record uses a SQL query on a database. This hook could be *subscribed* to, and used to track the number of queries during a certain action. There's another hook around the processing of an action of a controller. This could be used, for instance, to track how long a specific action has taken. + +You are even able to create your own events inside your application which you can later subscribe to. + +h3. Rails framework hooks + +h4. Action Mailer + +h4. Action Controller + +h4. Action View + +h4. Active Record + +h4. Active Resource + +h4. Active Support + +h3. Subscribing to an event + +h3. Creating custom events + diff --git a/railties/guides/source/asset_pipeline.textile b/railties/guides/source/asset_pipeline.textile index a061c1fc16..b1b1d21c2d 100644 --- a/railties/guides/source/asset_pipeline.textile +++ b/railties/guides/source/asset_pipeline.textile @@ -128,7 +128,7 @@ For example, these files: <plain> app/assets/javascripts/home.js lib/assets/javascripts/moovinator.js -vendor/assets/javascript/slider.js +vendor/assets/javascripts/slider.js </plain> would be referenced in a manifest like this: 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. |