@@ -1,9 +1,255 @@ -# Can Touch This +# by_* -Can Touch This is a permissions system extracted from rboard. -## How can I touch this? +by_* (byStar) is a plugin that allows you to find ActiveRecord objects given certain date objects. This was originally crafted for only finding objects within a given month, but now has extended out to much more. It now supports finding objects for: -You need to `include CanTouchThis` in the model you want to have permissions on (in rboard, this is the User model). +* A given year +* A given month +* A given fortnight +* A given week +* A given weekend +* A given day +* Between certain times +* As of a certain time +* Up to a certain time -You'll also need to create two tables: `groups` and `group_(your model's pluralized name)` (in rboard, group_users). Here's the schema until I can find a nicer way. \ No newline at end of file + +It also allows you to do nested finds on the records returned which I personally think is the coolest feature of the whole plugin: + + Post.by_month(1) do + { :include => "tags", :conditions => ["tags.name = ?", 'ruby'] } + end + +If you're not using the standard `created_at` field: don't worry! I've covered that scenario too. + + +## By Year + +To find records based on a year you can pass it a two or four digit number: + + Post.by_year(09) + +This will return all posts in 2009, whereas: + + Post.by_year(99) + +will return all the posts in the year 1999. + +## By Month + +If you know the number of the month you want: + + Post.by_month(1) + +This will return all posts in the first month (January) of the current year. + +If you like being verbose: + + Post.by_month("January") + +This will return all posts created in January of the current year. + +If you want to find all posts in January of last year just do + + Post.by_month(1, :year => 2007) + +or + + Post.by_month("January", :year => 2007) + +This will perform a find using the column you've specified. + +If you have a Time object you can use it to find the posts: + + Post.by_month(Time.local(2008, 11, 24)) + +This will find all the posts in November 2008. + +## By Fortnight + +Fortnight numbering starts at 0. + +To find records from the current fortnight: + + Post.by_fortnight + +To find records based on a fortnight, you can pass in a number (representing the fortnight number) or a time object: + + Post.by_fortnight(18) + +This will return all posts in the 18th fortnight of the current year. + + Post.by_fortnight(18, :year => 2008) + +This will return all posts in the 18th fortnight week of 2008. + + Post.by_fortnight(Time.local(2008,1,1)) + +This will return all posts from the first fortnight of 2008. + +## By Week + +Week numbering starts at 0. + +To find records from the current week: + + Post.by_week + +To find records based on a week, you can pass in a number (representing the week number) or a time object: + + Post.by_week(36) + +This will return all posts in the 36th week of the current year. + + Post.by_week(36, :year => 2008) + +This will return all posts in the 36th week of 2008. + + Post.by_week(Time.local(2008,1,1)) + +This will return all posts from the first week of 2008. + +## By Weekend + +If the time passed in (or the time now is a weekend) it will return posts from 12am Saturday to 11:59:59PM Sunday. If the time is a week day, it will show all posts for the coming weekend. + + Post.by_weekend(Time.now) + +## By Day + +To find records for today: + + Post.by_day + Post.today + +To find records for a certain day: + + Post.by_day(Time.local(2008, 1, 1)) + +You can also pass a string: + + Post.by_day("next tuesday") + +This will return all posts for the given day. + + +## Tomorrow + +To find all posts from the day after the current date: + + Post.tomorrow + +To find all posts after a given Date or Time object: + + Post.tomorrow(Date.today + 2) + Post.tomorrow(Time.now + 5.days) + +You can also pass a string: + + Post.tomorrow("next tuesday") + +## Yesterday + +To find all posts from the day before the current date: + + Post.yesterday + +To find all posts before a given Date or Time object: + + Post.yesterday(Date.today + 2) + Post.yesterday(Time.now + 5.days) + +You can also pass a string: + + Post.yesterday("next tuesday") + +## Past + +To find all posts before the current time: + + Post.past + +To find all posts before certain time or date: + + Post.past(Date.today + 2) + Post.past(Time.now + 5.days) + +You can also pass a string: + + Post.past("next tuesday") + +## Future + +To find all posts after the current time: + + Post.future + +To find all posts after certain time or date: + + Post.future(Date.today + 2) + Post.future(Time.now + 5.days) + +You can also pass a string: + + Post.future("next tuesday") + +## Between + +To find records between two times: + + Post.between(time1, time2) + +Also works with dates: + + Post.between(date1, date2) + +And with strings: + + Post.between("last tuesday", "next wednesday") + +## As of + +To find records as of a certain date up until the current time: + + Post.as_of_2_weeks_ago + +This uses the Chronic "human mind reading" (read: it's really good at determining what time you mean using written English) library to work it out. + +## Up to + +To find records up to a certain time from the current time: + + Post.up_to_6_weeks_from_now + +## Not using created_at? No worries! + +If your database uses something other than `created_at` for storing a timestamp, you can specify the field option like this: + + Post.by_month("January", :field => :something_else) + +All methods support this extra option. + +## Scoping the find + +All the `by_*` methods takes a block which will then scope the find based on the options passed into it. The supported options are the same options that are supported by `ActiveRecord::Base.find`: + + Post.by_month(1) do + { :include => "tags", :conditions => ["tags.name = ?", 'ruby'] } + end +## "Chronicable string" + +This means a string that can be parsed with the Chronic gem. + +## Collaborators + +Unfortunately I forget who exactly prompted me to write the plugin, but I would like to thank #rubyonrails for their support and the following people: + +* Mislav Marohnic +* August Lilleas (leethal) +* gte351s +* Thomase Sinclair (anathematic) +* The dude(s) & gal(s) who created Chronic + +## Suggestions? + +If you have suggestions, please contact me at radarlistener@gmail.com \ No newline at end of file README.markdown @@ -1,11 +1,10 @@ -# encoding: utf-8 desc "generates .gemspec file" task :gemspec => "version:read" do spec = Gem::Specification.new do |gem| - gem.name = "can_touch_this" + gem.name = "by_star" gem.summary = "ActiveRecord extension for easier date scopes and time ranges" gem.email = "mislav.marohnic@gmail.com" - gem.homepage = "http://github.com/mislav/can_touch_this" + gem.homepage = "http://github.com/mislav/by_star" gem.authors = ["Mislav Marohnić", "Ryan Bigg"] gem.has_rdoc = true @@ -47,10 +46,10 @@ Spec::Rake::SpecTask.new do |t| t.ruby_opts << "-rubygems" end -desc 'Generate documentation for the can_touch_this plugin.' +desc 'Generate documentation for the by_star plugin.' Rake::RDocTask.new(:rdoc) do |rdoc| rdoc.rdoc_dir = 'rdoc' - rdoc.title = 'Can Touch This' + rdoc.title = 'ByStar' rdoc.options << '--line-numbers' << '--inline-source' rdoc.rdoc_files.include('README') rdoc.rdoc_files.include('lib/**/*.rb') Rakefile @@ -1,13 +1,2 @@ -require 'can_touch_this' -# Thanks to those who have worked on nested_has_many_through -# Without this, it wouldn't be possible! -require 'nested_has_many_through' - -ActiveRecord::Associations::HasManyThroughAssociation.send :include, NestedHasManyThrough::Association - -# BC -if defined?(ActiveRecord::Reflection::ThroughReflection) - ActiveRecord::Reflection::ThroughReflection.send :include, NestedHasManyThrough::Reflection -else - ActiveRecord::Reflection::AssociationReflection.send :include, NestedHasManyThrough::Reflection -end \ No newline at end of file +require 'by_star' +ActiveRecord::Base.send :include, ByStar \ No newline at end of file rails/init.rb @@ -1,58 +1,70 @@ +class Post < ActiveRecord::Base + default_scope :order => "#{quoted_table_name}.created_at ASC" + has_and_belongs_to_many :tags + + def self.factory(text, created_at = nil) + create!(:text => text, :created_at => created_at) + end +end -require 'app/models/group' +class Tag < ActiveRecord::Base + has_and_belongs_to_many :posts +end -class GroupUser < ActiveRecord::Base - belongs_to :group - belongs_to :user +class Event < ActiveRecord::Base + named_scope :private, :conditions => { :public => false } end -require 'app/models/permission' +## seed data: -class Permission < ActiveRecord::Base - belongs_to :thing - belongs_to :category -end +year = Time.zone.now.year -class Thing < ActiveRecord::Base - has_many :permissions - has_many :groups, :through => :permissions - has_many :users, :through => :groups - - belongs_to :category - - acts_as_tree +1.upto(12) do |month| + month.times do |n| + Post.factory "post #{n}", Time.local(year, month, 1) + end end -class Category < ActiveRecord::Base - has_many :things -end +Post.factory "Today's post", Time.zone.now +Post.factory "Yesterday's post", Time.zone.now - 1.day +Post.factory "Tomorrow's post", Time.zone.now + 1.day -class User < ActiveRecord::Base - include CanTouchThis -end +Post.factory "That's it!", Time.zone.now.end_of_year + +# For by_weekend scoped test +post = Post.factory "Weekend of May", "16-05-2009".to_time +post.tags.create(:name => "weekend") + +# For by_day scoped test +post = Post.factory "Today", Time.zone.now +post.tags.create(:name => "today") -thing = Thing.create!(:name => "it") -sub_thing = Thing.create!(:name => "subby", :parent => thing) +# For yesterday scoped test +post = Post.factory "Yesterday", Time.zone.now.yesterday +post.tags.create(:name => "yesterday") -mc_hammer = Category.create!(:name => "MC Hammer") -the_song = mc_hammer.things.create!(:name => "Can't Touch This") +# For tomorrow scoped test +post = Post.factory "Tomorrow's Another Day", Time.zone.now.tomorrow +post.tags.create(:name => "tomorrow") -user = User.create!(:login => "radar", :password => "sekret") +post = Post.factory "Last year", Time.local(year - 1, 1, 1) +post.tags.create(:name => "ruby") -group = Group.create!(:name => "Users") -group.users << user -group.permissions.create!(:can_touch_this => true) -group.permissions.create!(:can_touch_this => false, :thing => thing) +post = Post.factory "The 'Current' Fortnight", Time.local(year, 5, 15) +post.tags.create(:name => "may") -user2 = User.create!(:login => "you", :password => "people") +post = Post.factory "The 'Current' Week", Time.local(year, 5, 15) +post.tags.create(:name => "may2") -other_group = Group.create!(:name => "Others") -other_group.users << user2 -other_group.permissions.create!(:can_touch_this => true) -other_group.permissions.create!(:can_touch_this => false, :thing => thing) -other_group.permissions.create!(:can_touch_this => true, :thing => sub_thing) -other_group.permissions.create!(:can_touch_this => false, :category => mc_hammer) -other_group.permissions.create!(:can_touch_this => true, :thing => the_song) +Event.create(:name => "Ryan's birthday!", :start_time => "04-12-#{Time.zone.now.year}".to_time) +Event.create(:name => "Dad's birthday!", :start_time => "05-07-#{Time.zone.now.year}".to_time) +Event.create(:name => "Mum's birthday!", :start_time => "17-11-#{Time.zone.now.year}".to_time) +Event.create(:name => "Today", :start_time => Time.zone.now) +Event.create(:name => "Yesterday", :start_time => Time.zone.now - 1.day) +Event.create(:name => "Tomorrow", :start_time => Time.zone.now + 1.day) +# For by_weekend test +Event.create(:name => "1st of August", :start_time => "01-08-#{Time.zone.now.year}".to_time) +Event.create(:name => "FBI meeting", :start_time => "02-03-#{Time.zone.now.year}".to_time, :public => false) \ No newline at end of file spec/fixtures/models.rb @@ -1,38 +1,24 @@ ActiveRecord::Schema.define do self.verbose = false - create_table "categories", :force => true do |t| - t.string "name" + create_table :posts, :force => true do |t| + t.string :text + t.timestamps end - create_table "groups", :force => true do |t| - t.string "name" - t.integer "owner_id" + create_table :posts_tags, :force => true do |t| + t.integer :post_id, :tag_id end - create_table "group_users", :force => true do |t| - t.integer "group_id" - t.integer "user_id" + create_table :tags, :force => true do |t| + t.string :name + t.timestamps end - create_table "permissions", :force => true do |t| - t.boolean "can_touch_this", :default => false - t.boolean "can_stop_hammer_time", :default => false - t.boolean "can_has_back", :default => false - t.integer "group_id" - t.integer "thing_id" - t.integer "category_id" + create_table :events, :force => true do |t| + t.datetime :start_time, :end_time + t.string :name + t.boolean :public, :default => true end - create_table "things" do |t| - t.string "name" - t.integer "parent_id" - t.integer "category_id" - end - - create_table "users", :force => true do |t| - t.string "login" - t.string "password" - end - end \ No newline at end of file spec/fixtures/schema.rb @@ -1,7 +1,5 @@ require 'rubygems' require 'activerecord' -require 'acts_as_tree' -ActiveRecord::Base.send :include, ActsAsTree ActiveRecord::Base.establish_connection( :adapter => "sqlite3", @@ -10,7 +8,7 @@ ActiveRecord::Base.establish_connection( $:.unshift(File.join(File.dirname(__FILE__), "../lib")) require 'activesupport' -require 'can_touch_this' +require 'by_star' require 'spec' # Define time zone before loading test_helper spec/spec_helper.rb app/models/group.rb app/models/permission.rb can_touch_this.gemspec lib/can_touch_this.rb lib/nested_has_many_through.rb spec/acts_as_tree.rb spec/can_touch_this_spec.rb f9e4513e0057056c5f21f887b003e46cf69d1898 Ryan Bigg radarlistener@gmail.com http://github.com/radar/by_star/commit/5b14da70a2d19260ffc6de03964c59662592aed3 5b14da70a2d19260ffc6de03964c59662592aed3 2009-07-10T23:06:55-07:00 2009-07-10T23:06:55-07:00 Whoops, forgot to rm the .git directory. Revert "first commit" This reverts commit f9e4513e0057056c5f21f887b003e46cf69d1898. 278212916476c23108a30e75f939dde774634d72 Ryan Bigg radarlistener@gmail.com