Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/aldesantis/timeful
A Ruby on Rails engine for building timelines.
https://github.com/aldesantis/timeful
activity-streams engine feed rails ruby timeline
Last synced: 21 days ago
JSON representation
A Ruby on Rails engine for building timelines.
- Host: GitHub
- URL: https://github.com/aldesantis/timeful
- Owner: aldesantis
- License: mit
- Created: 2016-09-27T12:54:30.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2021-04-29T21:00:24.000Z (over 3 years ago)
- Last Synced: 2024-04-24T16:46:51.461Z (9 months ago)
- Topics: activity-streams, engine, feed, rails, ruby, timeline
- Language: Ruby
- Homepage:
- Size: 61.5 KB
- Stars: 1
- Watchers: 0
- Forks: 2
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: MIT-LICENSE
Awesome Lists containing this project
README
# Timeful
[](https://badge.fury.io/rb/timeful)
[](https://travis-ci.org/aldesantis/timeful)
[](https://codeclimate.com/github/aldesantis/timeful/maintainability)
Timeful is a Ruby on Rails engine for building timelines (aka "activity streams").
## Why another gem?
There are battle-tested activity stream builders out there already (the most known being
[PublicActivity][public_activity], [TimelineFu][timeline_fu] and [Social Stream][social_stream].
However, these gems do not really create a feed for each user, but simply record a list of global
activities and leave you to deal with the retrieval.
Timeful is different: it takes a simple approach at building user feeds and allows you to obtain
an ordered list of feed items for each user.
Also, Timeful does not handle presentation: you will have to build your own views and controllers to
expose feeds. This keeps the codebase smaller and allows you to easily integrate Timeful in JSON
APIs.
[public_activity]: https://github.com/chaps-io/public_activity
[timeline_fu]: https://github.com/jamesgolick/timeline_fu
[social_stream]: https://github.com/ging/social_stream
## Installation
Add this line to your application's Gemfile:
```ruby
gem 'timeful'
```
And then execute:
```console
$ bundle
```
Or install it yourself as:
```console
$ gem install timeful
```
Then, run the installer generator:
```console
$ rails g timeful:install
$ rake db:migrate
```
Finally, add the following to the model that will have a feed and publish activities (this is
usually your `User` model, but you can use two different models):
```ruby
class User < ActiveRecord::Base
include Timeful::Model::Actor
include Timeful::Model::Subscriber
end
```
## Usage
Timeful revolves around three core concepts:
- **Activity**: An _action_ taken by an _actor_ on an _target_. _Metadata_ can also be attached to
activities. An example would be "John Doe (actor) wrote (action) a comment (target)."
- **Feed**: A collection of activities that should be accessible by a specific user.
- **Feed item**: The instance of an activity in a user's feed.
Each activity action (or "type") has its own class. This is required because Timeful has to know
which feeds the activity should be added to.
To avoid polluting `app/models`, it is recommended to put your activities in the `app/activities`
directory.
Here's an example activity:
```ruby
class CommentActivity < Timeful::Activity
def subscribers
[target.post.author]
end
end
```
Now, you can publish the `comment` activity:
```ruby
user.publish_activity :comment, target: comment
```
You can also attach metadata to the activity:
```ruby
user.publish_activity :comment, target: comment, meta: { foo: 'bar' }
```
This will create an `Activity` and link it to the author's feed through a `FeedItem`:
```ruby
author = comment.post.author
author.feed_items.count # => 1
```
## Performance
TODO: Write performance considerations
## Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/alessandro1997/timeful.
## License
The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).