From 0ae162e3cbea380099ff6725a8052fa5746fb748 Mon Sep 17 00:00:00 2001 From: Bert Hajee Date: Mon, 29 Jul 2013 22:46:22 +0200 Subject: [PATCH] Changed README and updated the example --- README.md | 249 ++---------------------------------------------------- example | 2 +- 2 files changed, 10 insertions(+), 241 deletions(-) diff --git a/README.md b/README.md index 5558603..abda28e 100644 --- a/README.md +++ b/README.md @@ -1,247 +1,18 @@ [![Gem Version](https://badge.fury.io/rb/page_record.png)](http://badge.fury.io/rb/page_record)[![Code Climate](https://codeclimate.com/github/appdrones/page_record.png)](https://codeclimate.com/github/appdrones/page_record) [![Build Status](https://travis-ci.org/appdrones/page_record.png)](https://travis-ci.org/appdrones/page_record) [![Dependency Status](https://gemnasium.com/appdrones/page_record.png)](https://gemnasium.com/appdrones/page_record) [![Coverage Status](https://coveralls.io/repos/appdrones/page_record/badge.png)](https://coveralls.io/r/appdrones/page_record) -# PageRecord - +#Intro You've probably been there. You're building your killer Web Application. You, being a responsible developer, your code is thoroughly tested. You are using the likes of cucumber and Rspec to do so. Besides your unit-tests, you also have integration tests doing a full stack test. You are using Capybara to read, parse and test the rendered pages. You use all kinds of selectors to select different parts of the page. Slowly but surely your test code becomes less and less readable. -## PageRecord can help. -There are a lot of ways you can do this. PageRecord is one of these ways. PageRecord is an ActiveRecord like abstraction for information on the HTML page. You can use `TeamRecord.find(1)` and `TeamRecord.find_by_name('Barcelona')` like functions to find a record on an HTML page. When you've found the record you need, you can use easy accessors to access the attributes. `TeamRecord.find(1).name` returns the name of the team. - -###Adding a record using a form - -With the PageRecord api you can fill all form fields press the save button. - -```ruby -When(/^I add a team$/) do - visit new_team_path - team = TeamPage.find - team.name = "Ajax" - team.competition = @competition - team.save -end -``` - -###Checking if an error is displayed. - -With the PageRecord api you can check for errors. No need to checkout what css you need to select the right DOM element. PageRecord takes care of that. - -```ruby -Then(/^I should see error "can't be blank" on field "competition"$/) do - team = TeamPage.find - expect(team.errors['competition']).to eq ['can't be blank'] -end -``` - -###How to get the right HTML? -PageRecord contains form builders that make it extremely easy to build the right forms. When you use Formtastic. You don't have to do anything. PageRecord add's the right attributes to the right DOM elements. When you use barebone Rails, you van use the `record_form_for` form builder. See the example for more information. - -##Documentation -Look at [the yard documentation](http://rubydoc.info/github/appdrones/page_record/PageRecord) for details. Check [Changes](https://github.com/appdrones/page_record/blob/master/CHANGES.md) for (breaking) changes per version. - -##Markup -For [PageRecord](http://rubydoc.info/github/appdrones/page_record/PageRecord) to recognise the data on the page, the page __must__ follow certain `html` formatting guidelines. - -__Every__ record on the page __must__ have a `data-type-id='x'` attribute. - -```html - -... - -``` -Where `1` is the `id` of the record and `type` is the type of record. See [PageRecord::Base.type](http://rubydoc.info/github/appdrones/page_record/PageRecord/Base#type-class_method) for information regarding the `type`. - -__Every__ attribute of a record, __must__ have a `data-attribute-for='name'` attribute. This tag __must__ be contained inside a tag contaning the `data-type-id='x'` - -```html - - Ajax -... - -``` - -Where `attr` is the name of the attribute. - -##attributes - -###reading the attributes -With [PageRecord](http://rubydoc.info/github/appdrones/page_record/PageRecord), you can easily access the attributes of a record on the page. After you've got a valid instance of [PageRecord::Base](http://rubydoc.info/github/appdrones/page_record/PageRecord/Base), you can access all attributes in a normal ruby-like way. - -```ruby - champion = TeamPage.find(1) - expect(champion.name).to eq('Ajax') -``` -###setting the attributes -Not only can you access the attributes for reading, you can also set the attributes. This only works if the attribute is modifiable, like in an `INPUT` or a `TEXTFIELD` tag. - -```ruby - champion = TeamPage.find(1) - champion.name = 'Ajax' -``` - -###specifying the attributes -When you define you page class as a subclass of [PageRecord::Base](http://rubydoc.info/github/appdrones/page_record/PageRecord/Base), it automagicaly looks for a host class. To get the name of your host class, PageRecord removes the `Page` part of you class name and tries to use that class as a host class. - -Example: - -```ruby -class TeamPage < PageRecord::Base -end -``` - -will result in a host class of `Team` - -####what is the host class -The host class is a class who's attributes are mirrored by PageRecord. At this point in time PageRecord only has support for `ActiveRecord` host classes. To be more specific: To be used as a host class, the class must support the method `attribute_names` to return an [Array](http://ruby-doc.org/core-2.0/Array.html) of [String](http://ruby-doc.org/core-2.0/String.html) of [Symbol](http://ruby-doc.org/core-2.0/Symbol.html). - -Example: - -Given the following host class and PageRecord class - -```ruby -class Team < ActiveRecord::Base -# The database defines the following records -# name, position, points -# -end - -class TeamPage < PageRecord::Base -end -``` - -Then a record from the TeamPage responds to the attributes: `name`, `position`, `points` - -####what is the host class -If you want to use a totaly different class name, you can use the `host_class` macro to specify what should be the host class. - -Example: - -```ruby -class JustSomeClass - host_class Team -end -``` - -This creates class `JustSomeClass` with the same capabilities as the `TeamPage` class in the previous example. - -###Adding some attributes -If you have a full_name on a page that isn't available in the host_class, you can add that attribute. - -```ruby -class TeamPage < PageRecord::Base - add_attributes ['full_name'] -end -``` - -###Setting all attributes -Sometimes it is easier to not have a host class, but just set the attributes your self. You can do this withe the attributes macro. - -```ruby -class JustSomePage < PageRecord::Base - attributes ['first_name', 'last_name', 'full_name'] -end -``` - - -##actions -PageRecord support record actions and page actions. - -###record actions -A record action is an action that is found within a `data-type-id=` tag. To define an action, you can use the `data-action-for='create'` tag. - -An example: - -```html -
- Name: - Position: - -
-``` - -with this markup on your page, you can use the following ruby code: - -```ruby -team = TeamPage.find(1) -team.name = 'Ajax' -team.position = 1 -team.save -``` - -When you call an action method, PageRecord automagicaly clicks the specified HTML element. - -Sometimes you don't want to click the element. PageRecord supports this by calling the action routine with a `?`. This returns the [Capybara Result](http://rubydoc.info/github/jnicklas/capybara/master/Capybara/Result). You can do with this element whatever you can do with this element what you want. - -```ruby -TeamPage.save? -``` - -###page actions -Sometimes you need to have an action that is not related to a record. An example is the creation of a new record. But in fact, any `data-action-for` tag, outside of a record, can be called as a page action. - -An example: - -```html -
- Name: - Position: -
-``` - -```ruby -TeamPage.create -``` - -When you call an action method, PageRecord automagicaly clicks the specfied HTML element. - -Sometimes you don't want to click the element. PageRecord supports this by calling the action routine with a `?`. This returns the Capybara Element. You can do with this element whatever you can do with this element what you want. - -```ruby -TeamPage.save? -``` - -##Using PageRecord together with Rspec -To use [PageRecord](http://rubydoc.info/github/appdrones/page_record/PageRecord) with Rspec, you need to require it in your `spec_helper.rb` file. To make it work, it needs to be required __after__ capybara. - -```ruby -require 'capybara' -require 'page_record/rspec' -``` - -Also, you need te make sure your page definitions are included. A good place to store them would be in your support directory. - -##Using PageRecord together with Cucumber -To use [PageRecord](http://rubydoc.info/github/appdrones/page_record/PageRecord) with Cucumber, you need to require it in your `env.rb` file. To make it work, it needs to be required __after__ capybara. - -```ruby -require 'capybara' -require 'page_record/cucumber' -``` -Also, you need te make sure your page definitions are included. A good place to store them would be in your support directory. - -##Using PageRecord standalone -If you are using [PageRecord](http://rubydoc.info/github/appdrones/page_record/PageRecord) outside of Rspec or Cucumber, you also need to require the right files. - -```ruby -require 'capybara' -require 'page_record/rspec' -``` - -You also need te make sure, you set the page variable before you start. - -```ruby -PageRecord::Base.page = session -``` - -Also, you need te make sure your page definitions are included. +##[PageRecord](http://rubydoc.info/github/appdrones/page_record/PageRecord) can help. +There are a lot of ways you can do this. [PageRecord](http://rubydoc.info/github/appdrones/page_record/PageRecord) is one of these ways. [PageRecord](http://rubydoc.info/github/appdrones/page_record/PageRecord) is an ActiveRecord like abstraction for information on the HTML page. +Check the [wiki](https://github.com/appdrones/page_record/wiki) for usage. See the [example](https://github.com/appdrones/page_record_example) for more details. Check [Changes](https://github.com/appdrones/page_record/blob/master/CHANGES.md) for (breaking) changes per version. ## Installation Add this line to your application's Gemfile: - gem 'page_record', :require => false + gem 'page_record' And then execute: @@ -251,13 +22,9 @@ Or install it yourself as: $ gem install page_record -## Usage - -TODO explain how to use it - -## Example +##Documentation +Look at [the yard documentation](http://rubydoc.info/github/appdrones/page_record/PageRecord) for details. -TODO show an example ## Contributing @@ -266,3 +33,5 @@ TODO show an example 3. Commit your changes (`git commit -am 'Add some feature'`) 4. Push to the branch (`git push origin my-new-feature`) 5. Create new Pull Request + + diff --git a/example b/example index 2b10030..76cac7c 160000 --- a/example +++ b/example @@ -1 +1 @@ -Subproject commit 2b10030c7105062e6f9f284d47e1bb4b99ce8f28 +Subproject commit 76cac7c22ea54d90a447d056943e1fb2aa29ec8d