README.md in simple_calendar-0.1.11 vs README.md in simple_calendar-1.0.0
- old
+ new
@@ -1,158 +1,172 @@
Simple Calendar
===============
-This is a small Rails 3.2 gem for creating a quick and clean table calendar.
-Theming is up to you, but it works nicely with Twitter Bootstrap. It's
-compatible with pure Ruby classes, ActiveRecord, Mongoid, and any other
-ORM.
+Simple Calendar is design to do one thing really really well: render a
+calendar. It lets you render a calendar of any size. Maybe you want a
+day view, a 4 day agenda, a week view, a month view, or a 6 week
+calendar. You can do all of that with the new gem, just give it a range
+of dates to render.
-Thanks to all of the awesome contributors!
+It doesn't depend on any ORM so you're free to use it with ActiveRecord,
+Mongoid, any other ORM, or pure Ruby objects.
+Thanks to all contributors for your wonderful help!
+
Installation
------------
Just add this into your Gemfile followed by a bundle install:
- gem "simple_calendar", "~> 0.1.10"
+ gem "simple_calendar", "~> 1.0.0"
Usage
-----
-#### Model
+Generating calendars is extremely simple with simple_calendar in version 1.0.
-SimpleCalendar will look for a method on your model called `start_time`.
-This is used to determine the day and time of the event. This should be
-a `DateTime` object or at least respond similarly.
+The first parameter is a symbol that looks up the current date in
+`params`. If no date is found, it will use the current date.
-The simplest way to use SimpleCalendar is to have an attribute on your
-model called `start_time` and you won't need to make any changes to your
-model at all. For example, I used `rails g model Event name:string
-start_time:datetime` to generate this class:
+In these examples, we're using `:start_date` which is the default.
-```ruby
-class Event < ActiveRecord::Base
- attr_accessible :name, :start_time
-end
-```
+### Month Calendar
-If you don't have an attribute called `start_time` on your model, you
-can simply delegate like so:
+You can generate a calendar for the month with the `month_calendar`
+method.
+This will use `params[:start_date]` to render the calendar.
-```ruby
-class Event < ActiveRecord::Base
- attr_accessible :name, :event_start_time
-
- def start_time
- event_start_time
- end
-end
+```erb
+<%= month_calendar :start_date do |day| %>
+ <%= day %>
+<% end %>
```
-As long as `start_time` returns a `DateTime` object, you're good to go.
-This means SimpleCalendar is now compatible with any class, whether it's
-ORM backed like ActiveRecord, Mongoid, or it's just a pure Ruby class.
-(Yay!)
+### Week Calendar
-##### Querying
+You can generate a week calendar with the `week_calendar` method.
+This will use `params[:start_date]` to render the calendar.
-SimpleCalendar uses `params[:month]` and `params[:year]` to determine
-which month of the calendar to render. You can use these to make your
-database queries more efficient.
+```erb
+<%= week_calendar :start_date, number_of_weeks: 2 do |day| %>
+ <%= day %>
+<% end %>
+```
-#### Views
+Setting `number_of_weeks` is optional and defaults to 1.
-SimpleCalendar just accepts an array of events and a block. The block
-will be executed for each event so you can provide your own logic for
-displaying the events.
+### Custom Length Calendar
-Here's an example that uses SimpleCalendar to simply render a link to
-each event on its own line inside the table. You would simply query for
-the `@events` as discussed above in the querying section.
+You can generate calendars of any length by passing in the number of days you want to render.
+This will use `params[:start_date]` to render the calendar.
```erb
-<%= calendar @events do |event| %>
- <div><%= link_to event.title, event %></div>
+<%= calendar :start_date, number_of_days: 4 do |day| %>
+ <%= day %>
<% end %>
```
-When the calendar is rendering, it yields to the block to allow you to
-render whatever you like for the item. In this example, I use the title
-attribute on the event with a link to the event.
+Setting `number_of_days` is optional and defaults to 4.
-You may even pass options to calendar renderer to customize it's behavior
+## Customizing The Calendar
-```erb
-<%= calendar @events, {:prev_text=>"prev", :next_text=>"next"} do |event| %>
- <div><%= link_to event.title, event %></div>
-<% end %>
+You can change a couple of global options that will affect how the
+calendars are generated:
+
+```ruby
+Time.zone = "Central Time (US & Canada)"
```
-This time calendar will use prev and next as labels for previous and next month
-links (which are normally set to &laquo; («) and &raquo; (»)
+Setting `Time.zone` will make sure the calendar start days are correctly computed
+in the right timezone. You can set this globally in your `application.rb` file or
+if you have a User model with a time_zone attribute, you can set it on every request by using
+a before_filter like the following example.
-Possible options:
+This code example uses [Devise](https://github.com/plataformatec/devise)'s
+`current_user` and `user_signed_in?` methods to retrieve the user's timezone and set it for the duration of the request.
+Make sure to change the `:user_signed_in?` and `current_user` methods if you are
+using some other method of authentication.
- :year # current year, default: from params or current year
- :month # current month, default: from params or current month
- :prev_text # previous month link text, default: «
- :next_text # next month link text, default: »
- :start_day # starting day of week, default: :sunday
- :empty_date # block called when a date is empty
- :class # HTML class attribute for the calendar
- :params # Any extra params you'd like in the URL (automatically includes month and year)
- :dont_display_year #Set to true to remove the year in the table header
+```ruby
+class ApplicationController < ActionController::Base
+ before_filter :set_time_zone, if: :user_signed_in?
-If you wish to have Monday as the first day of the week, you'll need to
-change a couple things. First, when rendering the calendar, use the
-`:start_day => :monday` option like so:
+ private
-```erb
-<%= calendar @events, :start_day => :monday do |event| %>
- <%= link_to event.title, event %>
-<% end %>
+ def set_time_zone
+ Time.zone = current_user.time_zone
+ end
+end
```
-And the second step is to make sure you've set your `I18n.locale` to the
-correct one. There is a lot of information here regarding use of locales in Rails:
-https://github.com/svenfuchs/rails-i18n
+You can also change the beginning day of the week. If you want to set
+this globally, you can put this line in
+`config/initializers/simple_calendar.rb`:
-The `empty_date` option accepts a block that will be called when a day
-in the calendar is empty. It will be called with the date object that
-represents the day that has no events.
-
-```erb
- <%= calendar @events, empty_date: lambda{ |date| "hello from #{date}" } do |event| %>
- <%= event.name %>
- <% end %>
+```ruby
+Date.beginning_of_week = :sunday
```
-The `not_empty_date` option accepts a block that will be called when a day
-in the calendar has at least one event. It will be called with the date object that
-represents the day that has some events.
-```erb
- <%= calendar @events, not_empty_date: lambda{ |date| "hello from #{date}" } do |event| %>
- <%= event.name %>
- <% end %>
+Setting classes on the table and elements are pretty:
+
+```ruby
+
+<%= calendar :start_date,
+ table: {class: "table table-bordered"},
+ tr: {class: "row"},
+ td: {class: "day"}, do |day| %>
+<% end %>
```
+This will set the class of `table table-bordered` on the `table` HTML
+element.
-CSS
----
+Each of the `table`, `tr`, and `td`, options are passed directly to the
+the `content_tag` method so each of them **must** be a hash.
-You will probably want to customize the height of the calendar so that
-all the rows are the same heights and widths. You can do this by adding
-the following line to your css:
+### Custom Header Links
-```css
-.calendar td { height: 100px; width: 14.28%; }
+Each of the calendar methods will generate a header with links to the
+previous and next views. The `month_calendar` also includes a header
+that tells you the current month and year that you are viewing.
+
+To change these, you can pass in the `prev_link`, `header`, and
+`next_link` options into the calendar methods.
+
+The default `month_calendar` look like this:
+
+```erb
+<%= month_calendar :start_date,
+ prev_link: ->(range) { link_to raw("«"), param_name => range.first - 1.day },
+ header: ->{ content_tag :span, "#{I18n.t("date.month_names")[start_date.month]} #{start_date.year}", class: "calendar-header" },
+ next_link: ->(range) { link_to raw("»"), param_name => range.last + 1.day } do |day| %>
+
+<% end %>
```
-By default simple_calendar will set the calendar to use .table
-.table-bordered .table-striped and .calendar classes.
+The `prev_link` option is a standard `link_to` that is a left arrow and
+with the current url having `?start_date=2014-04-30` appended to it as
+a date in the previous view of the calendar.
-You can also override the class by passing in the `class` option.
+The `next_link` option is a standard `link_to` that is a right arrow and
+with the current url having `?start_date=2014-06-01` appended to it as
+a date in the next view of the calendar.
+The `header` option is just a simple span tag with the month and year
+inside of it.
+
+If you wish to disable any of these partsof the header, just pass in
+`false` and that will hide it:
+
```erb
- <%= calendar @events, class: "simple-calendar" do |event| %>
- <% end %>
+<%= month_calendar :start_date, header: false do |day| %>
+<% end %>
```
+
+
+## Author
+
+Chris Oliver <chris@gorails.com>
+
+[https://gorails.com](https://gorails.com)
+
+[@excid3](https://twitter.com/excid3)