Trello Yello is a high-level object-oriented wrapper for the Trello API. It greatly simplifies the process of interacting with the Trello public API and allows you to script nearly every action available through their API in an easy-to-learn, easy-to-use manner.
Table of contents
- What is Trello?
- Why use Trello Yello?
- Getting Started
- Using Trello Yello
- Retrieving data
- Setting data
- Deleting data
- Querying trello
- More examples
- Build your own query
- What's up with the name?
- Full documentation
What is Trello?
Trello is a free web application that helps with project organization, simple to-do lists, notetaking, etc. You can take a tour here.
Why use Trello Yello?
While Trello's API provides a great deal of utility and power, it is a bit unwieldy to work with. A good deal of effort is spent building complex HTTP queries and parsing large JSON objects. Trello Yello handles all of that for you, and lets you work with objects and operations that map directly to the Trello elements that you're used to.
npm install trello-yello
Trello Yello has several quirks that are worth mentioning.
- Most functions are asynchronous as they require network communication with the Trello API. These functions will return a
Promiseand will also accept an optional callback function (error-first).
- Trello Yello will be intelligent about making network connections, reducing them as much as it is able. But for any operation that may result in a network operation, the return type is still a
Promise. It may just be a
Promisethat is resolved immediately.
- All objects returned by Trello Yello are frozen using
- Because of the above, you will never
newan object in Trello Yello.
- All Trello Yello functions take exactly zero or one parameters. If multiple values can be passed in, that parameter will be an object with arguments as its properties, including callbacks. Please refer to the full documentation for details on all functions.
Trello Yello requires both an application key and a user token. Here are instructions on how to get those:
- You will need to generate your application key from Trello. You can do so here. More information can be found from Trello here.
- You will also need a token from Trello. A token is tied to a user which may or may not be the same user as the application key. The application key simply gives you access to the API. The token gives you specific permissions to a user account. See the examples here and the documentation here.
- Trello's full guide to getting started can be found here
An example URL for getting a token that has all permissions and never expires (don't worry, you can delete it later from your settings or even through Trello Yello):
Using Trello Yello
Getting a reference to the module:
var trello = ;
Now you will need to instantiate the trello service.
var trelloService = ;
Great! Now you have the (Trello) world at your fingers. The first thing you need to do is get a Trello Object. For example, let's say you want to rename a Card and you know its id.
A lot of the time you won't know the id. Let's say you want to retrieve a board that the user belongs to, but all you know is the name.
var myBoard;var myBoards;trelloService;
From here you can make changes to the board, or access objects on the board such as cards, lists, labels, or the board's organization, and perform actions on those.
What if you want to change the name of your list?
Maybe you have a webhook that you're not using anymore
Or you can delete properties on an object. Maybe you want to remove a label from a card.
You can run searches on Trello easily.
// Setting the name of the green label for a board:trelloService;// Archiving all the cards in a listtrelloService;// Adding a comment to a cardtrelloService;// Getting all of the user's unread notificationsvar allNotifications;var unreadNotifications;trelloService;// Deleting a checklist itemtrelloService;// Deleting a labeltrelloService;
Build your own query
Most Trello API operations have specific functions associated with the type of object being operated on. However, for experienced users, you can build your own Trello query.
// Performing a GET operation on the Trello API. Trello object is an object such as a card or a listvar property = trelloObject;// Performing a PUT or POST operation on the Trello APItrelloObject;// Here's a specific example for updating an organization's descriptionorganization;// Update a member's saved searchmember;
Trello Yello will check internally if the query you have is a valid API call. This prevents creating a network connection when the application knows it will fail. However, there may be times where Trello Yello is either out of date, or doesn't support the specific operation you are trying to perform. In this case, set the parameters property
true. The above example would thus become:
What's up with the name?
Well, aside from the obvious rhyme, and the reference to the beverage Mello Yello, using Trello Yello should be refreshing. Like an ice cold citrus drink on a hot summer day. I don't know. It's a name. What more do you want from me?
Anyone is welcome to contribute! Please follow the recommended GitHub steps.
- Code: https://github.com/HolyMeekrob/trello-yello/
- npm: https://www.npmjs.com/package/trello-yello/
- Trello: https://www.trello.com
Released under the MIT license.