Giter VIP home page Giter VIP logo

ruby-trello's Introduction

Ruby Trello API

Stories in Ready Build Status Dependency Status Code Climate

This library implements the Trello API.

Trello is an awesome tool for organization. Not just aimed at developers, but everybody. Seriously, check it out.

Full API documentation.

Installation

# gem install ruby-trello

Full Disclosure: This library is mostly complete, if you do find anything missing or not functioning as you expect it to, please let us know.

Supports Ruby 2.1.0 or newer.

Use version 1.3.0 or earlier for Ruby 1.9.3 support. Use version 1.4.x or earlier for Ruby 2.0.0 support.

Configuration

Basic authorization:

  1. Get your API public key from Trello via the irb console:
$ gem install ruby-trello
$ irb -rubygems
irb> require 'trello'
irb> Trello.open_public_key_url                         # copy your public key
irb> Trello.open_authorization_url key: 'yourpublickey' # copy your member token
  1. You can now use the public key and member token in your app code:
require 'trello'

Trello.configure do |config|
  config.developer_public_key = TRELLO_DEVELOPER_PUBLIC_KEY # The "key" from step 1
  config.member_token = TRELLO_MEMBER_TOKEN # The token from step 2.
end

2-legged OAuth authorization

Trello.configure do |config|
  config.consumer_key = TRELLO_CONSUMER_KEY
  config.consumer_secret = TRELLO_CONSUMER_SECRET
  config.oauth_token = TRELLO_OAUTH_TOKEN
  config.oauth_token_secret = TRELLO_OAUTH_TOKEN_SECRET
end

3-legged OAuth authorization

Trello.configure do |config|
  config.consumer_key    = TRELLO_CONSUMER_KEY
  config.consumer_secret = TRELLO_CONSUMER_SECRET
  config.return_url      = "http://your.site.com/path/to/receive/post"
  config.callback        = lambda { |request_token| DB.save(request_token.key, request_token.secret) }
end

All the calls this library makes to Trello require authentication using these keys. Be sure to protect them.

Usage

So let's say you want to get information about the user bobtester. We can do something like this:

bob = Trello::Member.find("bobtester")

# Print out his name
puts bob.full_name # "Bob Tester"

# Print his bio
puts bob.bio # A wonderfully delightful test user

# How about a list of his boards?
bob.boards

# And then to read the lists of the first board do : 
bob.boards.first.lists
Accessing specific items

There is no find by name method in the trello API, to access a specific item, you have to know it's ID. The best way is to pretty print the elements and then find the id of the element you are looking for.

# With bob
pp bob.boards # Will pretty print all boards, allowing us to find our board id

# We can now access it's lists
pp Trello::Board.find( board_id ).lists # will pretty print all lists. Let's get the list id

# We can now access the cards of the list
pp Trello::List.find( list_id ).cards

# We can now access the checklists of the card
pp Trello::Card.find( card_id ).checklists

# and so on ...
Changing a checkbox state
# First get your checklist id 
checklist = Trello::Checklist.find( checklist_id )

# At this point, there is no more ids. To get your checklist item, 
# you have to know it's position (same as in the trello interface).
# Let's take the first
checklist_item = checklist.items.first

# Then we can read the status
checklist_item.state # return 'complete' or 'incomplete'

# We can update it (note we call update_item_state from checklist, not from checklist_item)
checklist.update_item_state( checklist_item.id, 'complete' ) # or 'incomplete'

# You can also use true or false instead of 'complete' or 'incomplete'
checklist.update_item_state( checklist_item.id, true ) # or false

Multiple Users

Applications that make requests on behalf of multiple Trello users have an alternative to global configuration. For each user's access token/secret pair, instantiate a Trello::Client:

@client_bob = Trello::Client.new(
  :consumer_key => YOUR_CONSUMER_KEY,
  :consumer_secret => YOUR_CONSUMER_SECRET,
  :oauth_token => "Bob's access token",
  :oauth_token_secret => "Bob's access secret"
)

@client_alice = Trello::Client.new(
  :consumer_key => YOUR_CONSUMER_KEY,
  :consumer_secret => YOUR_CONSUMER_SECRET,
  :oauth_token => "Alice's access token",
  :oauth_token_secret => "Alice's access secret"
)

You can now make threadsafe requests as the authenticated user:

Thread.new do
  @client_bob.find(:members, "bobtester")
  @client_bob.find(:boards, "bobs_board_id")
end
Thread.new do
  @client_alice.find(:members, "alicetester")
  @client_alice.find(:boards, "alices_board_id")
end

Special thanks

A special thanks goes out to Ben Biddington who has contributed a significant amount of refactoring and functionality to be deserving of a beer and this special thanks.

Contributing

Several ways you can contribute. Documentation, code, tests, feature requests, bug reports.

If you submit a pull request that's accepted, you'll be given commit access to this repository.

Please see the CONTRIBUTING.md file for more information.

ruby-trello's People

Contributors

jeremytregunna avatar ben-biddington avatar rossta avatar ownadi avatar eraserhd avatar larusso avatar george-carlin avatar xpepper avatar imhide avatar brycemcd avatar danmcp avatar wildfalcon avatar adambird avatar christoshrousis avatar czuger avatar semanticart avatar set5think avatar francois2metz avatar cl3m avatar djo avatar cbartlett avatar wdjungst avatar dlackty avatar ssaunier avatar stacyvlasits avatar wesgibbs avatar codyolsen avatar dobbymoodge avatar tkowark avatar ksamc avatar

Watchers

Kayla avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.