inkwell_timelines

Inkwell Timelines

Inkwell Timelines provides simple way to create timelines with autoload content while scrolling with ability to transmit the additional parameters. It allows you to place timeline blocks on the pages - one block per page.

Each block can consist of several timelines (Blog and Favorite timelines on the screenshot).

Each timeline can consist of several types objects (Posts and Comments on the screenshot) with different templates to form them.

Timeline can consist of selectors ( category selector on the screenshot) to customize received data (for example, you can get timeline with only one category's items).

Timelines autoload next items when it is scrolled to the end.

Installation

Put in Gemfile:

gem 'inkwell_timelines', :git => 'https://github.com/salkar/inkwell_timelines.git'

After it do bundle install

Create inkwell_timelines.rb file in config/initializers and put in it your settings:

module InkwellTimelines
  class Engine < Rails::Engine
    # Pixels count between current scroll position and page's end at which the autoload start
    config.load_distance = 150 
    config.autoload_path = 'timeline/get/' # Autoload controller path
    # Optional. If defined all partials will be searched here
    config.partials_dir = 'your path to partials' 
    config.timeline_blocks = [ 
        { # First timelines block
            :id => 'timelines_block', # Block id
            :timelines => [ 
                {
                    :id => 'blogline', # First timeline id
                    :name => 'Blog', # First timeline displayed name
                    :active => true, # Defines which timeline is active at first load
                    :data_get => ->(options = {}) { # Lambda which get data for form this timeline
                      user = User.find options[:user_id]
                      # Function that return array of objects (for example - posts and comments in dummy app)
                      user.blogline options 
                    },
                    # Array of params (of options in :data_get) saved on client side and sent to server on autoload
                    :transferred_params => [:user_id], 
                    # Add selector to customize received data (sampling by Category on the screenshot)
                    :multi_selectors => [  
                        {
                            :id => 'category', # Selector id
                            :name => 'Category', # Selector displayed name (see screenshot)
                            :data_get => ->(options = {}) { # Lambda which get objects for form selector
                              Category.where(:owner_id => options[:user_id], :owner_type => 'u')
                            }

                        }
                    ]
                },
                {
                    :id => 'favoriteline', # Second timeline id
                    :name => 'Favorite', # Second timeline displayed name
                    :data_get => ->(options = {}) { # Lambda which get data for form this timeline
                      user = User.find options[:user_id]
                      user.favoriteline options
                    },
                    # Transferred through client params (timeline owner in this case)
                    :transferred_params => [:user_id] 
                }
            ]
        }
    ]
  end
end

Next, add //= require inkwell_timelines to your js assets (for example - to application.js) and *= require inkwell_timelines to your stylesheets assets (for example - to application.css).

Notice: if you want to modify CSS or JS you can add your modified files and not add default styles/js

Default partials are located inside the gem - here. You can change this directory to your adding config.partials_dir = 'your path to partials' parameter in your inkwell_timelines.rb file.

By default, there are 5 partials in this gem (you can change all of them):

_comment.html.erb # Partial for timeline item for comment object
_multi_selector.html.erb # Partial for selector
_multi_selector_items.html.erb # Support partial for selector
_post.html.erb # Partial for post item for comment object
_tab_menu.html.erb # Partial for timelines block menu

If there are other objects except posts and comments - add partials for them.

Usage

To form the timeline block for the first showing add into your view:

<%= inkwell_timelines_tag(block_id, options = {} %>

For example:

<%= inkwell_timelines_tag('timelines_block', 
                          :user_id => User.where(:nick => 'Pushkin').first.id, 
                          :for_user => current_user) %>

Notice: config for this block should be

To on autoload feature create controller for it, add it in the routes, add its route to timeline config. For example:

• add controllers/timeline_controller.rb

class TimelineController < ApplicationController
  def show
  end
end

• add route for it -

match "/timeline/get" => "timeline#show"

• add its route to timelines config:

config.autoload_path = 'timeline/get/'

Next, add to created controller:

@options = inkwell_timelines_get_params(request.body, :additional options => {})

inkwell_timelines_get_params forms options for autoload timeline part generation. Additional options needs to merge stored on the server with transferred from client options. You may want to save some options on the server for security reasons (for example - current_user should not be sent to the client because there it can be changed).

Here you can check the options that came with the client.

At the end of autoload controller method add

render :layout => false

Example:

class TimelineController < ApplicationController
  def show
    @options = inkwell_timelines_get_params(request.body, :for_user => current_user)

    #Here you can check came from js options. For exapmle:
    user = User.find @options[:user_id]
    raise "current user has no permissions to see #{user.nick} timeline" unless current_user.can_see_timeline user

    render :layout => false
  end
end

After it create view file for autoload method in controller (in our cases - views/timeline/show.html.erb) and add to it

<%= inkwell_timelines_autoload_tag(@options) %>

Sample

Sample located here. To run it:

$ cd inkwell_timelines/test/dummy
$ bundle install
$ rake db:create
$ rake db:migrate
$ rake db:seed
$ rails s

And go to http://0.0.0.0:3000/ in your browser after it.

License

Inkwell is Copyright © 2013 Sergey Sokolov. It is free software, and may be redistributed under the terms specified in the MIT-LICENSE file.