doc/index.html
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>
File: README
— Documentation by YARD 0.9.25
</title>
<link rel="stylesheet" href="css/style.css" type="text/css" />
<link rel="stylesheet" href="css/common.css" type="text/css" />
<script type="text/javascript">
pathId = "README";
relpath = '';
</script>
<script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
<script type="text/javascript" charset="utf-8" src="js/app.js"></script>
</head>
<body>
<div class="nav_wrap">
<iframe id="nav" src="class_list.html?1"></iframe>
<div id="resizer"></div>
</div>
<div id="main" tabindex="-1">
<div id="header">
<div id="menu">
<a href="_index.html">Index</a> »
<span class="title">File: README</span>
</div>
<div id="search">
<a class="full_list_link" id="class_list_link"
href="class_list.html">
<svg width="24" height="24">
<rect x="0" y="4" width="24" height="4" rx="1" ry="1"></rect>
<rect x="0" y="12" width="24" height="4" rx="1" ry="1"></rect>
<rect x="0" y="20" width="24" height="4" rx="1" ry="1"></rect>
</svg>
</a>
</div>
<div class="clear"></div>
</div>
<div id="content"><div id='filecontents'>
<h1 id="label-Ruby+Trello+API">Ruby Trello API</h1>
<p><a href="http://travis-ci.org/jeremytregunna/ruby-trello"><img src="https://secure.travis-ci.org/jeremytregunna/ruby-trello.svg"></a> <a href="https://hakiri.io/github/jeremytregunna/ruby-trello/master"><img src="https://hakiri.io/github/jeremytregunna/ruby-trello/master.svg"></a> <a href="https://codeclimate.com/github/jeremytregunna/ruby-trello"><img src="https://codeclimate.com/github/jeremytregunna/ruby-trello/badges/gpa.svg"></a></p>
<p>This library implements the <a href="http://www.trello.com/">Trello</a> <a href="https://developers.trello.com/">API</a>.</p>
<p>Trello is an awesome tool for organization. Not just aimed at developers, but everybody. Seriously, <a href="http://www.trello.com/">check it out</a>.</p>
<p><a href="http://www.rubydoc.info/gems/ruby-trello">Full API documentation</a>.</p>
<p>Full Disclosure: This library is mostly complete, if you do find anything missing or not functioning as you expect it to, please just <a href="https://github.com/jeremytregunna/ruby-trello/issues/new">create an issue</a>.</p>
<h2 id="label-Requirements">Requirements</h2>
<p>Use the newest version for Ruby 2.5.0 or newer support. Use version 2.2.1 or earlier for Ruby 2.1 ~ 2.4 support. 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.</p>
<h2 id="label-Installation">Installation</h2>
<pre class="code ruby"><code class="ruby"><span class='comment'># gem install ruby-trello
</span></code></pre>
<h2 id="label-Configuration">Configuration</h2>
<h4 id="label-Basic+authorization-3A">Basic authorization:</h4>
<ol><li>
<p>Get your API public key from Trello via <a href="https://trello.com/app-key/">trello.com/app-key/</a> or the irb console as follows:</p>
</li></ol>
<pre class="code ruby"><code class="ruby">$ 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
</code></pre>
<ol><li>
<p>You can now use the public key and member token in your app code:</p>
</li></ol>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_require'>require</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>trello</span><span class='tstring_end'>'</span></span>
<span class='const'><span class='object_link'><a href="Trello.html" title="Trello (module)">Trello</a></span></span><span class='period'>.</span><span class='id identifier rubyid_configure'><span class='object_link'><a href="Trello.html#configure-class_method" title="Trello.configure (method)">configure</a></span></span> <span class='kw'>do</span> <span class='op'>|</span><span class='id identifier rubyid_config'>config</span><span class='op'>|</span>
<span class='id identifier rubyid_config'>config</span><span class='period'>.</span><span class='id identifier rubyid_developer_public_key'>developer_public_key</span> <span class='op'>=</span> <span class='const'>TRELLO_DEVELOPER_PUBLIC_KEY</span> <span class='comment'># The "key" from step 1
</span> <span class='id identifier rubyid_config'>config</span><span class='period'>.</span><span class='id identifier rubyid_member_token'>member_token</span> <span class='op'>=</span> <span class='const'>TRELLO_MEMBER_TOKEN</span> <span class='comment'># The token from step 2.
</span><span class='kw'>end</span>
</code></pre>
<h4 id="label-2-legged+OAuth+authorization">2-legged OAuth authorization</h4>
<pre class="code ruby"><code class="ruby"><span class='const'><span class='object_link'><a href="Trello.html" title="Trello (module)">Trello</a></span></span><span class='period'>.</span><span class='id identifier rubyid_configure'><span class='object_link'><a href="Trello.html#configure-class_method" title="Trello.configure (method)">configure</a></span></span> <span class='kw'>do</span> <span class='op'>|</span><span class='id identifier rubyid_config'>config</span><span class='op'>|</span>
<span class='id identifier rubyid_config'>config</span><span class='period'>.</span><span class='id identifier rubyid_consumer_key'>consumer_key</span> <span class='op'>=</span> <span class='const'>TRELLO_CONSUMER_KEY</span>
<span class='id identifier rubyid_config'>config</span><span class='period'>.</span><span class='id identifier rubyid_consumer_secret'>consumer_secret</span> <span class='op'>=</span> <span class='const'>TRELLO_CONSUMER_SECRET</span>
<span class='id identifier rubyid_config'>config</span><span class='period'>.</span><span class='id identifier rubyid_oauth_token'>oauth_token</span> <span class='op'>=</span> <span class='const'>TRELLO_OAUTH_TOKEN</span>
<span class='id identifier rubyid_config'>config</span><span class='period'>.</span><span class='id identifier rubyid_oauth_token_secret'>oauth_token_secret</span> <span class='op'>=</span> <span class='const'>TRELLO_OAUTH_TOKEN_SECRET</span>
<span class='kw'>end</span>
</code></pre>
<h4 id="label-3-legged+OAuth+authorization">3-legged OAuth authorization</h4>
<pre class="code ruby"><code class="ruby"><span class='const'><span class='object_link'><a href="Trello.html" title="Trello (module)">Trello</a></span></span><span class='period'>.</span><span class='id identifier rubyid_configure'><span class='object_link'><a href="Trello.html#configure-class_method" title="Trello.configure (method)">configure</a></span></span> <span class='kw'>do</span> <span class='op'>|</span><span class='id identifier rubyid_config'>config</span><span class='op'>|</span>
<span class='id identifier rubyid_config'>config</span><span class='period'>.</span><span class='id identifier rubyid_consumer_key'>consumer_key</span> <span class='op'>=</span> <span class='const'>TRELLO_CONSUMER_KEY</span>
<span class='id identifier rubyid_config'>config</span><span class='period'>.</span><span class='id identifier rubyid_consumer_secret'>consumer_secret</span> <span class='op'>=</span> <span class='const'>TRELLO_CONSUMER_SECRET</span>
<span class='id identifier rubyid_config'>config</span><span class='period'>.</span><span class='id identifier rubyid_return_url'>return_url</span> <span class='op'>=</span> <span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>http://your.site.com/path/to/receive/post</span><span class='tstring_end'>"</span></span>
<span class='id identifier rubyid_config'>config</span><span class='period'>.</span><span class='id identifier rubyid_callback'>callback</span> <span class='op'>=</span> <span class='id identifier rubyid_lambda'>lambda</span> <span class='lbrace'>{</span> <span class='op'>|</span><span class='id identifier rubyid_request_token'>request_token</span><span class='op'>|</span> <span class='const'>DB</span><span class='period'>.</span><span class='id identifier rubyid_save'>save</span><span class='lparen'>(</span><span class='id identifier rubyid_request_token'>request_token</span><span class='period'>.</span><span class='id identifier rubyid_key'>key</span><span class='comma'>,</span> <span class='id identifier rubyid_request_token'>request_token</span><span class='period'>.</span><span class='id identifier rubyid_secret'>secret</span><span class='rparen'>)</span> <span class='rbrace'>}</span>
<span class='kw'>end</span>
</code></pre>
<p>All the calls this library makes to Trello require authentication using these keys. Be sure to protect them.</p>
<h4 id="label-Usage">Usage</h4>
<p>So let's say you want to get information about the user <em>bobtester</em>. We can do something like this:</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_bob'>bob</span> <span class='op'>=</span> <span class='const'><span class='object_link'><a href="Trello.html" title="Trello (module)">Trello</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Trello/Member.html" title="Trello::Member (class)">Member</a></span></span><span class='period'>.</span><span class='id identifier rubyid_find'><span class='object_link'><a href="Trello/Member.html#find-class_method" title="Trello::Member.find (method)">find</a></span></span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>bobtester</span><span class='tstring_end'>"</span></span><span class='rparen'>)</span>
<span class='comment'># Print out his name
</span><span class='id identifier rubyid_puts'>puts</span> <span class='id identifier rubyid_bob'>bob</span><span class='period'>.</span><span class='id identifier rubyid_full_name'>full_name</span> <span class='comment'># "Bob Tester"
</span>
<span class='comment'># Print his bio
</span><span class='id identifier rubyid_puts'>puts</span> <span class='id identifier rubyid_bob'>bob</span><span class='period'>.</span><span class='id identifier rubyid_bio'>bio</span> <span class='comment'># A wonderfully delightful test user
</span>
<span class='comment'># How about a list of his boards?
</span><span class='id identifier rubyid_bob'>bob</span><span class='period'>.</span><span class='id identifier rubyid_boards'>boards</span>
<span class='comment'># And then to read the lists of the first board do :
</span><span class='id identifier rubyid_bob'>bob</span><span class='period'>.</span><span class='id identifier rubyid_boards'>boards</span><span class='period'>.</span><span class='id identifier rubyid_first'>first</span><span class='period'>.</span><span class='id identifier rubyid_lists'>lists</span>
</code></pre>
<h5 id="label-Accessing+specific+items">Accessing specific items</h5>
<p>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.</p>
<pre class="code ruby"><code class="ruby"><span class='comment'># With bob
</span><span class='id identifier rubyid_pp'>pp</span> <span class='id identifier rubyid_bob'>bob</span><span class='period'>.</span><span class='id identifier rubyid_boards'>boards</span> <span class='comment'># Will pretty print all boards, allowing us to find our board id
</span>
<span class='comment'># We can now access it's lists
</span><span class='id identifier rubyid_pp'>pp</span> <span class='const'><span class='object_link'><a href="Trello.html" title="Trello (module)">Trello</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Trello/Board.html" title="Trello::Board (class)">Board</a></span></span><span class='period'>.</span><span class='id identifier rubyid_find'><span class='object_link'><a href="Trello/BasicData.html#find-class_method" title="Trello::BasicData.find (method)">find</a></span></span><span class='lparen'>(</span> <span class='id identifier rubyid_board_id'>board_id</span> <span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_lists'>lists</span> <span class='comment'># will pretty print all lists. Let's get the list id
</span>
<span class='comment'># We can now access the cards of the list
</span><span class='id identifier rubyid_pp'>pp</span> <span class='const'><span class='object_link'><a href="Trello.html" title="Trello (module)">Trello</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Trello/List.html" title="Trello::List (class)">List</a></span></span><span class='period'>.</span><span class='id identifier rubyid_find'><span class='object_link'><a href="Trello/List.html#find-class_method" title="Trello::List.find (method)">find</a></span></span><span class='lparen'>(</span> <span class='id identifier rubyid_list_id'>list_id</span> <span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_cards'>cards</span>
<span class='comment'># We can now access the checklists of the card
</span><span class='id identifier rubyid_pp'>pp</span> <span class='const'><span class='object_link'><a href="Trello.html" title="Trello (module)">Trello</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Trello/Card.html" title="Trello::Card (class)">Card</a></span></span><span class='period'>.</span><span class='id identifier rubyid_find'><span class='object_link'><a href="Trello/BasicData.html#find-class_method" title="Trello::BasicData.find (method)">find</a></span></span><span class='lparen'>(</span> <span class='id identifier rubyid_card_id'>card_id</span> <span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_checklists'>checklists</span>
<span class='comment'># and so on ...
</span></code></pre>
<h5 id="label-Changing+a+checkbox+state">Changing a checkbox state</h5>
<pre class="code ruby"><code class="ruby"><span class='comment'># First get your checklist id
</span><span class='id identifier rubyid_checklist'>checklist</span> <span class='op'>=</span> <span class='const'><span class='object_link'><a href="Trello.html" title="Trello (module)">Trello</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Trello/Checklist.html" title="Trello::Checklist (class)">Checklist</a></span></span><span class='period'>.</span><span class='id identifier rubyid_find'><span class='object_link'><a href="Trello/BasicData.html#find-class_method" title="Trello::BasicData.find (method)">find</a></span></span><span class='lparen'>(</span> <span class='id identifier rubyid_checklist_id'>checklist_id</span> <span class='rparen'>)</span>
<span class='comment'># At this point, there is no more ids. To get your checklist item,
</span><span class='comment'># you have to know it's position (same as in the trello interface).
</span><span class='comment'># Let's take the first
</span><span class='id identifier rubyid_checklist_item'>checklist_item</span> <span class='op'>=</span> <span class='id identifier rubyid_checklist'>checklist</span><span class='period'>.</span><span class='id identifier rubyid_items'>items</span><span class='period'>.</span><span class='id identifier rubyid_first'>first</span>
<span class='comment'># Then we can read the status
</span><span class='id identifier rubyid_checklist_item'>checklist_item</span><span class='period'>.</span><span class='id identifier rubyid_state'>state</span> <span class='comment'># return 'complete' or 'incomplete'
</span>
<span class='comment'># We can update it (note we call update_item_state from checklist, not from checklist_item)
</span><span class='id identifier rubyid_checklist'>checklist</span><span class='period'>.</span><span class='id identifier rubyid_update_item_state'>update_item_state</span><span class='lparen'>(</span> <span class='id identifier rubyid_checklist_item'>checklist_item</span><span class='period'>.</span><span class='id identifier rubyid_id'>id</span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>complete</span><span class='tstring_end'>'</span></span> <span class='rparen'>)</span> <span class='comment'># or 'incomplete'
</span>
<span class='comment'># You can also use true or false instead of 'complete' or 'incomplete'
</span><span class='id identifier rubyid_checklist'>checklist</span><span class='period'>.</span><span class='id identifier rubyid_update_item_state'>update_item_state</span><span class='lparen'>(</span> <span class='id identifier rubyid_checklist_item'>checklist_item</span><span class='period'>.</span><span class='id identifier rubyid_id'>id</span><span class='comma'>,</span> <span class='kw'>true</span> <span class='rparen'>)</span> <span class='comment'># or false
</span></code></pre>
<h4 id="label-Multiple+Users">Multiple Users</h4>
<p>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 <code>Trello::Client</code>:</p>
<pre class="code ruby"><code class="ruby"><span class='ivar'>@client_bob</span> <span class='op'>=</span> <span class='const'><span class='object_link'><a href="Trello.html" title="Trello (module)">Trello</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Trello/Client.html" title="Trello::Client (class)">Client</a></span></span><span class='period'>.</span><span class='id identifier rubyid_new'><span class='object_link'><a href="Trello/Client.html#initialize-instance_method" title="Trello::Client#initialize (method)">new</a></span></span><span class='lparen'>(</span>
<span class='symbol'>:consumer_key</span> <span class='op'>=></span> <span class='const'>YOUR_CONSUMER_KEY</span><span class='comma'>,</span>
<span class='symbol'>:consumer_secret</span> <span class='op'>=></span> <span class='const'>YOUR_CONSUMER_SECRET</span><span class='comma'>,</span>
<span class='symbol'>:oauth_token</span> <span class='op'>=></span> <span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>Bob's access token</span><span class='tstring_end'>"</span></span><span class='comma'>,</span>
<span class='symbol'>:oauth_token_secret</span> <span class='op'>=></span> <span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>Bob's access secret</span><span class='tstring_end'>"</span></span>
<span class='rparen'>)</span>
<span class='ivar'>@client_alice</span> <span class='op'>=</span> <span class='const'><span class='object_link'><a href="Trello.html" title="Trello (module)">Trello</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Trello/Client.html" title="Trello::Client (class)">Client</a></span></span><span class='period'>.</span><span class='id identifier rubyid_new'><span class='object_link'><a href="Trello/Client.html#initialize-instance_method" title="Trello::Client#initialize (method)">new</a></span></span><span class='lparen'>(</span>
<span class='symbol'>:consumer_key</span> <span class='op'>=></span> <span class='const'>YOUR_CONSUMER_KEY</span><span class='comma'>,</span>
<span class='symbol'>:consumer_secret</span> <span class='op'>=></span> <span class='const'>YOUR_CONSUMER_SECRET</span><span class='comma'>,</span>
<span class='symbol'>:oauth_token</span> <span class='op'>=></span> <span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>Alice's access token</span><span class='tstring_end'>"</span></span><span class='comma'>,</span>
<span class='symbol'>:oauth_token_secret</span> <span class='op'>=></span> <span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>Alice's access secret</span><span class='tstring_end'>"</span></span>
<span class='rparen'>)</span>
</code></pre>
<p>You can now make threadsafe requests as the authenticated user:</p>
<pre class="code ruby"><code class="ruby"><span class='const'>Thread</span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span> <span class='kw'>do</span>
<span class='ivar'>@client_bob</span><span class='period'>.</span><span class='id identifier rubyid_find'>find</span><span class='lparen'>(</span><span class='symbol'>:members</span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>bobtester</span><span class='tstring_end'>"</span></span><span class='rparen'>)</span>
<span class='ivar'>@client_bob</span><span class='period'>.</span><span class='id identifier rubyid_find'>find</span><span class='lparen'>(</span><span class='symbol'>:boards</span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>bobs_board_id</span><span class='tstring_end'>"</span></span><span class='rparen'>)</span>
<span class='kw'>end</span>
<span class='const'>Thread</span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span> <span class='kw'>do</span>
<span class='ivar'>@client_alice</span><span class='period'>.</span><span class='id identifier rubyid_find'>find</span><span class='lparen'>(</span><span class='symbol'>:members</span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>alicetester</span><span class='tstring_end'>"</span></span><span class='rparen'>)</span>
<span class='ivar'>@client_alice</span><span class='period'>.</span><span class='id identifier rubyid_find'>find</span><span class='lparen'>(</span><span class='symbol'>:boards</span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>alices_board_id</span><span class='tstring_end'>"</span></span><span class='rparen'>)</span>
<span class='kw'>end</span>
</code></pre>
<h2 id="label-Special+thanks">Special thanks</h2>
<p>A special thanks goes out to <a href="https://github.com/ben-biddington">Ben Biddington</a> who has contributed a significant amount of refactoring and functionality to be deserving of a beer and this special thanks.</p>
<h2 id="label-Contributing">Contributing</h2>
<p>Several ways you can contribute. Documentation, code, tests, feature requests, bug reports.</p>
<p>If you submit a pull request that's accepted, you'll be given commit access to this repository.</p>
<p>Please see the <code>CONTRIBUTING.md</code> file for more information.</p>
<h2 id="label-Local+Development">Local Development</h2>
<p>Init all Gemfile.lock.* files</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_make'>make</span> <span class='id identifier rubyid_init'>init</span>
</code></pre>
<p>Bundle install for all Ruby versions</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_make'>make</span> <span class='label'>bundle:</span><span class='id identifier rubyid_all'>all</span>
</code></pre>
<p>Run tests for all Ruby versions</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_make'>make</span> <span class='label'>test:</span><span class='id identifier rubyid_all'>all</span>
</code></pre>
<p>Run tests for each Ruby versions individual</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_make'>make</span> <span class='label'>test:</span><span class='id identifier rubyid_ruby_2_5'>ruby_2_5</span>
<span class='id identifier rubyid_make'>make</span> <span class='label'>test:</span><span class='id identifier rubyid_ruby_2_6'>ruby_2_6</span>
<span class='id identifier rubyid_make'>make</span> <span class='label'>test:</span><span class='id identifier rubyid_ruby_2_7'>ruby_2_7</span>
<span class='id identifier rubyid_make'>make</span> <span class='label'>test:</span><span class='id identifier rubyid_jruby_9_2'>jruby_9_2</span>
</code></pre>
<p>Do development for each Ruby versions individual</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_make'>make</span> <span class='label'>dev:</span><span class='id identifier rubyid_ruby_2_5'>ruby_2_5</span>
<span class='id identifier rubyid_make'>make</span> <span class='label'>dev:</span><span class='id identifier rubyid_ruby_2_6'>ruby_2_6</span>
<span class='id identifier rubyid_make'>make</span> <span class='label'>dev:</span><span class='id identifier rubyid_ruby_2_7'>ruby_2_7</span>
<span class='id identifier rubyid_make'>make</span> <span class='label'>dev:</span><span class='id identifier rubyid_jruby_9_2'>jruby_9_2</span>
</code></pre>
</div></div>
<div id="footer">
Generated on Tue Nov 10 16:31:45 2020 by
<a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
0.9.25 (ruby-2.6.6).
</div>
</div>
</body>
</html>