{"id":13631779,"url":"https://github.com/excid3/simple_calendar","last_synced_at":"2025-05-12T13:18:17.995Z","repository":{"id":2386471,"uuid":"3352214","full_name":"excid3/simple_calendar","owner":"excid3","description":"A wonderfully simple calendar gem for Rails","archived":false,"fork":false,"pushed_at":"2025-05-08T15:18:34.000Z","size":491,"stargazers_count":1633,"open_issues_count":4,"forks_count":269,"subscribers_count":43,"default_branch":"main","last_synced_at":"2025-05-12T13:18:06.501Z","etag":null,"topics":["calendar","custom-calendar","meeting","month","ruby","week-calendar"],"latest_commit_sha":null,"homepage":"http://excid3.github.io/simple_calendar","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/excid3.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["excid3"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2012-02-04T11:06:01.000Z","updated_at":"2025-05-06T19:34:15.000Z","dependencies_parsed_at":"2024-06-18T12:44:51.521Z","dependency_job_id":"a0523e59-cacf-4d34-8e19-4d7523a7274e","html_url":"https://github.com/excid3/simple_calendar","commit_stats":{"total_commits":278,"total_committers":67,"mean_commits":4.149253731343284,"dds":"0.46402877697841727","last_synced_commit":"c801520ee840d792a5d000b103c58c454c1cc0fb"},"previous_names":[],"tags_count":64,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/excid3%2Fsimple_calendar","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/excid3%2Fsimple_calendar/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/excid3%2Fsimple_calendar/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/excid3%2Fsimple_calendar/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/excid3","download_url":"https://codeload.github.com/excid3/simple_calendar/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253745196,"owners_count":21957319,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["calendar","custom-calendar","meeting","month","ruby","week-calendar"],"created_at":"2024-08-01T22:02:38.011Z","updated_at":"2025-05-12T13:18:17.945Z","avatar_url":"https://github.com/excid3.png","language":"Ruby","funding_links":["https://github.com/sponsors/excid3"],"categories":["Ruby"],"sub_categories":[],"readme":"# Simple Calendar\n\n### 📆 A calendar for your Ruby on Rails app.\n\n[![Build Status](https://github.com/excid3/simple_calendar/workflows/Tests/badge.svg)](https://github.com/excid3/simple_calendar/actions) [![Gem Version](https://badge.fury.io/rb/simple_calendar.svg)](https://badge.fury.io/rb/simple_calendar)\n\nSimple Calendar is designed to do one thing really really well: render a calendar.\n\nIt lets you render a calendar of any size. Maybe you want a\nday view, a 4 day agenda, a week view, a month view, or a 6 week\ncalendar. You can do all of that with the new gem, just give it a range\nof dates to render.\n\nIt doesn't depend on any ORM so you're free to use it with ActiveRecord, Mongoid, any other ORM, or pure Ruby objects.\n\nThanks to all contributors for your wonderful help!\n\n![calendar](https://s3.amazonaws.com/f.cl.ly/items/1T0t1s0W212d28282V2M/Screen%20Shot%202013-03-28%20at%209.44.49%20AM.png)\n\nInstallation\n------------\n\nJust add this into your Gemfile followed by a bundle install:\n```ruby\ngem \"simple_calendar\"\n```\n\nIf you're using Bootstrap, the calendar should already have a border and\nnice spacing for days.\n\nOptionally, you can include the default stylesheet for the calendar in\nyour `app/assets/stylesheets/application.css` file:\n\n```scss\n*= require simple_calendar\n```\n\nor in your SCSS `app/assets/stylesheets/application.scss` file:\n\n```scss\n@import \"simple_calendar\";\n```\n\n\nUsage\n-----\n\nGenerating calendars is extremely simple with simple_calendar.\n\nThe first parameter is a symbol that looks up the current date in\n`params`. If no date is found, it will use the current date.\n\nIn these examples, we're using `:start_date` which is the default.\n\n### Month Calendar\n\nYou can generate a calendar for the month with the `month_calendar`\nmethod.\n\n```erb\n\u003c%= month_calendar do |date| %\u003e\n  \u003c%= date %\u003e\n\u003c% end %\u003e\n```\n\nTo show the day of the month instead of the date, use `\u003c%= date.day %\u003e`\n\n### Week Calendar\n\nYou can generate a week calendar with the `week_calendar` method.\n\n```erb\n\u003c%= week_calendar(number_of_weeks: 2) do |date| %\u003e\n  \u003c%= date %\u003e\n\u003c% end %\u003e\n```\n\nSetting `number_of_weeks` is optional and defaults to 1.\n\n### Custom Length Calendar\n\nYou can generate calendars of any length by passing in the number of days you want to render.\n\n```erb\n\u003c%= calendar(number_of_days: 4) do |date| %\u003e\n  \u003c%= date %\u003e\n\u003c% end %\u003e\n```\n\nSetting `number_of_days` is optional and defaults to 4.\n\n### Custom Parameter Name\n\nYou can pass in `start_date_param` to change the name of the parameter\nin the URL for the current calendar view.\n\n```erb\n\u003c%= calendar(start_date_param: :my_date) do |date| %\u003e\n  \u003c%= date %\u003e\n\u003c% end %\u003e\n```\n\n### Custom Partial\n\nYou can set a different partial name for calendars by passing the partial path.\n\n```erb\n\u003c%= calendar(partial: 'products/calendar') do |date| %\u003e\n  \u003c%= date %\u003e\n\u003c% end %\u003e\n```\n\n### Internationalization (I18n)\n\nThe default views are prepared to do translation lookups for month names and weekdays.\n\nTo profit from that, you can take advantage of the [`rails-i18n`](https://github.com/svenfuchs/rails-i18n/) gem which comes with translations for many languages already.\n\nIn a Rails 6 app, the configuration could look like the following:\n\n  * Add `gem 'rails-i18n'` to your `Gemfile` and run `bundle`.\n  * Define the available and default locale e.g. in `config/application.rb`:\n```ruby\n# config/application.rb\nconfig.i18n.available_locales = [:en, :de, :fr]\nconfig.i18n.default_locale = :en\n```\n  * Define the following translation keys:\n```yaml\n# e.g. config/locales/de.yml\nde:\n  simple_calendar:\n    previous: \"\u003c\u003c\"\n    next: \"\u003e\u003e\"\n    week: Woche\n```\n\nSee the [Rails I18n Guide](https://guides.rubyonrails.org/i18n.html) for further information.\n\n## Rendering Events\n\nWhat's a calendar without events in it? There are two simple steps for creating\ncalendars with events.\n\nThe first step is to add the following to your model. We'll be using a\nmodel called Meeting, but you can add this to any model or Ruby object.\n\nHere's an example model:\n\n```bash\n# single day events\n$ rails g scaffold Meeting name start_time:datetime\n\n# multi-day events\n$ rails g scaffold Meeting name start_time:datetime end_time:datetime\n```\n\nBy default it uses `start_time` as the attribute name.\n**If you'd like to use another attribute other than start_time, just\npass it in as the `attribute`**\n\n```erb\n\u003c%= month_calendar(attribute: :starts_at) do |date| %\u003e\n  \u003c%= date %\u003e\n\u003c% end %\u003e\n```\n\nOptionally the `end_time` attribute can be used which enables multi-day event rendering.\n\n**Just pass in the `attribute` and `end_attribute` options respectively**\n\n```erb\n\u003c%= month_calendar(attribute: :start_date, end_attribute: :end_date) do |date| %\u003e\n  \u003c%= date %\u003e\n\u003c% end %\u003e\n```\n\n**If you already have a model with a start time attribute called something other than `start_time` or accesses it through a relationship, you can alias the attribute by defining a `start_time` method in the my_model.rb file and not have to specify it separately as in the above example**\n```ruby\nclass MyModel\n    ## Other code related to your model lives here\n\n    def start_time\n        self.my_related_model.start ##Where 'start' is a attribute of type 'Date' accessible through MyModel's relationship\n    end\nend\n```\n\nIn your controller, query for these meetings and store them in an instance\nvariable. Normally you'll want to search for the ones that only show up\ninside the calendar view (for example, you may only want to grab the events for\nthe current month).\n\nWe'll just load up all the meetings for this example.\n\n```ruby\ndef index\n  # Scope your query to the dates being shown:\n  start_date = params.fetch(:start_date, Date.today).to_date\n  @meetings = Meeting.where(starts_at: start_date.beginning_of_month.beginning_of_week..start_date.end_of_month.end_of_week)\nend\n```\n\nThen in your view, you can pass in the `events` option to render. The\nmeetings will automatically be filtered out by day for you.\n\n```erb\n\u003c%= month_calendar(events: @meetings) do |date, meetings| %\u003e\n  \u003c%= date %\u003e\n\n  \u003c% meetings.each do |meeting| %\u003e\n    \u003cdiv\u003e\n      \u003c%= meeting.name %\u003e\n    \u003c/div\u003e\n  \u003c% end %\u003e\n\u003c% end %\u003e\n```\n\nIf you pass in objects that don't respond to the attribute method (like\nstarts_at), then all the meetings will be yielded each day. This lets you\ndo custom filtering however you want.\n\n## Customizing The Calendar\n\nThere are a handful of configuration options that you can use in\nsimple_calendar.\n\n### Customizing Views\n\nYou can customize the layouts for each of the calendars by running the\ngenerators for simple_calendar:\n\n```bash\n$ rails g simple_calendar:views\n```\n\nThis will generate a folder in app/views called simple_calendar that you\nedit to your heart's desire.\n\n### Time Zones\n\nSetting `Time.zone` will make sure the calendar start days are correctly computed\nin the right timezone. You can set this globally in your `application.rb` file or\nif you have a User model with a time_zone attribute, you can set it on every request by using\na before_action like the following example.\n\nThis code example uses [Devise](https://github.com/plataformatec/devise)'s\n`current_user` and `user_signed_in?` methods to retrieve the user's timezone and set it for the duration of the request.\nMake sure to change the `:user_signed_in?` and `current_user` methods if you are\nusing some other method of authentication.\n\n```ruby\nclass ApplicationController \u003c ActionController::Base\n  before_action :set_time_zone, if: :user_signed_in?\n\n  private\n\n    def set_time_zone\n      Time.zone = current_user.time_zone\n    end\nend\n```\n\nIf you want to set the time zone globally, you can set the following in\n`config/application.rb`:\n\n```ruby\nconfig.time_zone = 'Central Time (US \u0026 Canada)'\n```\n\n### Beginning Of Week\n\nYou can also change the beginning day of the week by setting\n`Date.beginning_of_week` in a `before_action` just like in the previous\nexample. If you want to set this globally, you can put this line in\n`config/application.rb`:\n\n```ruby\nconfig.beginning_of_week = :sunday\n```\n\n### Custom CSS Classes\n\nSetting classes on the table and elements are pretty easy.\n\nsimple_calendar comes with a handful of useful classes for each day in\nthe calendar that you can use:\n\n```scss\n.simple-calendar {\n  .day {}\n\n  .wday-0 {}\n  .wday-1 {}\n  .wday-2 {}\n  .wday-3 {}\n  .wday-4 {}\n  .wday-5 {}\n  .wday-6 {}\n\n  .today {}\n  .past {}\n  .future {}\n\n  .start-date {}\n\n  .prev-month {}\n  .next-month { }\n  .current-month {}\n\n  .has-events {}\n}\n```\n\nJust paste this into a CSS file and add your styles and they will be\napplied to the calendar. All of these classes are inside of the\nsimple-calendar class so you can scope your own classes with similar\nnames.\n\n### Custom Header Title And Links\n\nHeader and title links are easily adjusted by generating views and\nmodifying them inside your application.\n\nFor example, if you'd like to use abbreviated month names, you can modify\nthe views from this:\n\n```erb\n\u003c%= t('date.month_names')[start_date.month] %\u003e \u003c%= start_date.year %\u003e\n```\n\nTo\n\n```erb\n\u003c%= t('date.abbr_month_names')[start_date.month] %\u003e \u003c%= start_date.year %\u003e\n```\n\nYour calendar will now display \"Sep 2015\" instead of \"September 2015\" at\nthe top! :)\n\n### AJAX Calendars\n\nRendering calendars that update with AJAX is pretty simple. You'll need\nto follow these steps.\n\n- Run `rails g simple_calendar:views` to generate the views.\n- Add an ID to the calendar view's outer div. `\u003cdiv id=\"calendar\" class=\"simple-calendar\"\u003e`\n- Add `remote: true` option to the next \u0026 preview links like [this](https://github.com/excid3/simple_calendar-ajax-example/blob/ac8a1dc933d5933608421f8b53a5f5cf756b942f/app/views/simple_calendar/_month_calendar.html.erb#L3).\n- Create `js.erb` file to respond to JS requests, render the new calendar, and replace the calendar on the page by ID like [this](https://github.com/excid3/simple_calendar-ajax-example/blob/master/app/views/events/index.js.erb).\n\nThe response can simply replace\nthe HTML of the div with the newly rendered calendar.\n\nTake a look at **[excid3/simple_calendar-ajax-example](https://github.com/excid3/simple_calendar-ajax-example)** to see how it is done.\n\nIf you are using [Hotwire](https://hotwired.dev/), just wrap in a Turbo Frame.\nLike this:\n\n```erb\n\u003c%= turbo_frame_tag 'calendar' do %\u003e\n  \u003c%= month_calendar do |date| %\u003e\n    \u003c%= date.day %\u003e\n  \u003c% end %\u003e\n\u003c% end %\u003e\n```\n\n\n## Custom Calendars\n\nThe three main calendars available should take care of most of your\nneeds, but simple_calendar makes it easy to create completely custom\ncalendars (like maybe you only want business weeks).\n\nIf you'd like to make a completely custom calendar, you can create a new\nclass that inherits from `SimpleCalendar::Calendar`. The name you give\nit will correspond to the name of the template it will try to render.\n\n\nThe main method you'll need to implement is the `date_range` so that\nyour calendar can have a custom length.\n\n```ruby\nclass SimpleCalendar::BusinessWeekCalendar \u003c SimpleCalendar::Calendar\n  private\n\n    def date_range\n      beginning = start_date.beginning_of_week + 1.day\n      ending    = start_date.end_of_week - 1.day\n      (beginning..ending).to_a\n    end\nend\n```\n\nTo render this in the view, you can do:\n\n```erb\n\u003c%= render SimpleCalendar::BusinessWeekCalendar.new(self, events: meetings) do |date| %\u003e\n  \u003c%= date %\u003e\n\u003c% end %\u003e\n```\n\nAnd this will render the\n`app/views/simple_calendar/_business_week_calendar.html.erb` partial.\n\nYou can copy one of the existing templates to use for the partial for\nyour new calendar.\n\n## View Specs and Tests\n\nIf you're running view specs against views with calendars, you may run into route generation errors like the following:\n\n```\nFailure/Error: render\nActionView::Template::Error:\n  No route matches {:action=\u003e\"show\", :controller=\u003e\"controller_name\", :start_date=\u003eSun, 29 Mar 2015}\n```\n\nIf so, you can stub out the appropriate method like so (rspec 3 and up):\n\n```\nexpect_any_instance_of(SimpleCalendar::Calendar).to receive(:link_to).at_least(:once).and_return(\"\")\n```\n\nWith modifications as appropriate.\n\n## Author\n\nChris Oliver \u003cchris@gorails.com\u003e\n\n[https://gorails.com](https://gorails.com)\n\n[@excid3](https://twitter.com/excid3)\n\n## License\n\nSimple Calendar is licensed under the [MIT License](LICENSE.txt).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexcid3%2Fsimple_calendar","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fexcid3%2Fsimple_calendar","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexcid3%2Fsimple_calendar/lists"}