We've put together a small javascript library to make it easier to interact with Trello's API in your applications. It provides a global Trello object that includes helper methods for common actions in Trello's API. You can find the full source code for client.js.
For a tutorial on using client.js
, check out Getting Started with client.js.
client.js
requires jQuery as a dependency.
By adding the following to your page, a global Trello object will be available with many useful methods. By specifying your API Key in the URL for client.js
, we will automatically use it when we make requests.
1 2<script src="https://trello.com/1/client.js?key=[key]"></script>
Call Trello.authorize(opts)
with the following options:
Key | Values | Description |
---|---|---|
type string | One of: redirect or popup Default: redirect | Whether authorization should be done in a new window, or by leaving the current page |
name string | Name of your application, which is displayed during the authorization process | |
persist boolean | Default: true | If true, the token will be saved to local storage. |
interactive boolean | Default: true | If false, don’t redirect or popup, only use the stored token. |
scope object | Default is read-only, i.e. { read: true, write: false, account: false } | Each permission is a boolean. { read: allowRead, write: allowWrite, account: allowAccount } |
expiration string | One of: 1hour , 1day , 30days , or never Default: 30days | When the token should expire. |
success function | Optional function to be called on success. | |
error function | Optional function to be called on error. If using type: redirect , the token will be returned to the current location.href . When it is returned, call authorize with interactive: false to get the token. |
You can use the API via a single call:
window.Trello.rest(method, path[, params], success, error)
Key | Values | Description |
---|---|---|
method string | One of: GET , POST , PUT , DELETE | HTTP method to use when making the request to the Trello API. |
path string | Valid Trello API path without prepended /1/ . | API path to use, such as "members/me" |
params object | Default: {} | Query parameters to the API path, such as { fields: "username,fullName" } |
success function | Optional function to be called on success. | |
error function | Optional function to be called on error |
There are also a number of convenience methods, with similar signatures. One for each HTTP method:
1 2Trello.get(path[, params], success, error) Trello.post(path[, params], success, error) Trello.put(path[, params], success, error) Trello.delete(path[, params], success, error)
An alias for delete:
Trello.del(path[, params], success, error)
And one for GET
ting on each collection:
1 2Trello.actions.get(id[, params], success, error) Trello.cards.get(id[, params], success, error) Trello.checklists.get(id[, params], success, error) Trello.boards.get(id[, params], success, error) Trello.lists.get(id[, params], success, error) Trello.members.get(id[, params], success, error) Trello.organizations.get(id[, params], success, error)
Another capability of the client.js
library is the ability to create cards directly into a Trello member's account without needing to authenticate. This functions similarly to Facebook's support for sharing URLs. When using this capability, you do not get access to the user's account, and no authorization step is required.
This method takes a required Options object, and an optional callback URL. If no callback URL is provided, the method will attempt to return a promise, if supported by the current browser.
Option | Description |
---|---|
url | Required URL you would like to share |
mode | Currently only "popup" is supported |
source | The originating URL of your request |
name | The name that you want to give the card |
idList | The ID of the List where you want to add the new card |
idBoard | The ID of the Board where you want to add the new card |
width | The width in pixels of the popup |
height | The height in pixels of the popup |
left | The distance from the left edge of the user's screen in pixels for the popup |
top | The distance from the top edge of the user's screen in pixels for the popup |
Once you have included client.js
on your page, you can call:
window.Trello.addCard({url:'http://example.com'});
This will create a popup that will share the specified URL.
You can also achieve this functionality directly via its URL. By taking a member to a specially constructed URL, the Trello member will be able to make a choice regarding his or her boards and lists, and be able to decide where to store the new card and URL that is being shared.
The URL looks like this:
Key | Description |
---|---|
source | The originating URL of your request. |
name | The name that you want to give the card |
idList | The ID of the List where you want to add the new card |
idBoard | The ID of the Board where you want to add the new card |
Rate this page: