HolyMeekrob/trello-yello

语言: JavaScript

git: https://github.com/HolyMeekrob/trello-yello

面向对象的节点包,用于与Trello交互。
An object-oriented node package for interacting with Trello.
README.md (中文)

Trello Yello

Build status

介绍

Trello Yello是Trello API的高级面向对象包装器。它极大地简化了与Trello公共API交互的过程,并允许您以易于学习,易于使用的方式编写几乎所有可通过其API执行的操作。

目录

  • 什么是Trello?
  • 为什么要使用Trello Yello?
  • 安装
  • 怪癖
  • 入门
  • 使用Trello Yello
  • 检索数据
  • 设置数据
  • 删除数据
  • 查询trello
  • 更多例子
  • 建立自己的查询
  • 这个名字怎么了?
  • 特约
  • 等等
  • 执照
  • 完整的文档

什么是Trello?

Trello是一个免费的Web应用程序,可以帮助项目组织,简单的待办事项列表,记事本等。您可以在这里参观。

为什么要使用Trello Yello?

虽然Trello的API提供了大量的实用程序和功能,但使用它有点笨拙。构建复杂的HTTP查询和解析大型JSON对象需要花费大量精力。 Trello Yello为您处理所有这些,并允许您处理直接映射到您习惯的Trello元素的对象和操作。

安装

npm install trello-yello

怪癖

Trello Yello有几个值得一提的怪癖。 - 大多数功能都是异步的,因为它们需要与Trello API进行网络通信。这些函数将返回Promise,并且还将接受可选的回调函数(error-first)。 - Trello Yello将智能地建立网络连接,尽可能地减少网络连接。但对于可能导致网络操作的任何操作,返回类型仍然是Promise。它可能只是一个立即解决的承诺。 - 使用Object.freeze()(引用)冻结Trello Yello返回的所有对象。这使得API保持完整,通过无意的覆盖防止潜在的错误,并使Trello Yello与其他人不太可能导致混淆。这个想法来自Douglas Crockford的演讲Javascript:The Better Parts(视频)。 - 由于上述原因,你永远不会在Trello Yello中新建一个物体。 - 所有Trello Yello功能都可以使用零个或一个参数。如果可以传入多个值,则该参数将是一个以参数作为其属性的对象,包括回调。有关所有功能的详细信息,请参阅完整文档。

入门

Trello Yello需要应用程序密钥和用户令牌。以下是如何获取这些内容的说明:

  1. 您需要从Trello生成应用程序密钥。你可以在这里这样做。更多信息可以在Trello这里找到。
  2. 您还需要Trello的令牌。令牌绑定到用户,该用户可以是或可以不是与应用程序密钥相同的用户。应用程序密钥只是让您访问API。令牌为您提供了对用户帐户的特定权限。请参阅此处的示例和此处的文档。
  3. Trello的入门指南可以在这里找到

获取具有所有权限且永不过期的令牌的示例URL(不用担心,您可以稍后从您的设置或甚至通过Trello Yello删除它):

https://trello.com/1/authorize?key=YourKeyHere&name=Trello Yello&expiration=never&response_type=token&scope=read,write,account

使用Trello Yello

获取模块的参考:

var trello = require('trello-yello');

现在,您需要实例化trello服务。

var trelloService = trello({key: 'yourKey', token: 'yourToken'});

检索数据

大!现在你的手指上有(Trello)世界。你需要做的第一件事是获得一个Trello对象。例如,假设您要重命名一张卡片,并且您知道它的ID。

trelloService.getCard(id).then(function (card) {
  card.setName({ name: 'newName' });
}).catch(function (err) {
  // handle err
});

很多时候你不会知道id。假设您想要检索用户所属的板,但您知道的就是名称。

var myBoard;
var myBoards;
trelloService.getCurrentUser().getBoards().then(function (boards) {
  myBoards = boards;
  // Return a Promise that resolves to an array of board names in order
  return Promise.all(boards.map(function (board) { return board.getName(); }))
}).then(function (boardNames) {
  var index = boardNames.indexOf('myBoardName');
  myBoard = myBoards[index];
  // Do something with myBoard
}).catch(function (err) {
  // handle err
});

从这里,您可以更改电路板,或访问电路板上的对象,如卡片,列表,标签或电路板组织,并对其执行操作。

设置数据

如果您想更改列表名称怎么办?

list.setName({ name: 'My new list name' });

删除数据

也许你有一个你不再使用的webhook

webhook.del();

或者您可以删除对象的属性。也许你想从卡片上删除标签。

card.removeLabelByColor({ color: orange });

查询Trello

您可以轻松地在Trello上运行搜索。

trelloService.search({query: 'taco'}).then(function (response) {
  console.log(response);
}).catch(function (err) {
  // handle err
});

更多例子

// Setting the name of the green label for a board:
trelloService.getBoard(boardId).setLabelName({ color: 'green', name: 'new name'});

// Archiving all the cards in a list
trelloService.getList(listId).archiveAllCards();

// Adding a comment to a card
trelloService.getCard(cardId).addComment({ comment: 'The comment to add.' });

// Getting all of the user's unread notifications
var allNotifications;
var unreadNotifications;
trelloService.getCurrentUser().getNotifications().then(function (notifications) {
  allNotifications = notifications;
  return Promise.all(notifications.map(function (n) {
        return n.isUnread();
    }));
}).then(function (unreadArray) {
  unreadNotifications = allNotifications.filter(function (notification, index) {
    return unreadArray[index];
  });
  // Do something with unreadNotifications
}).catch(function (err) {
  // handle err
});

// Deleting a checklist item
trelloService.getChecklist(checklistId).removeChecklistItem({ checklistItemId: 'id' });

// Deleting a label
trelloService.getLabel(labelId).del();

建立自己的查询

大多数Trello API操作都具有与正在操作的对象类型相关联的特定功能。但是,对于有经验的用户,您可以构建自己的Trello查询。

// Performing a GET operation on the Trello API. Trello object is an object such as a card or a list
var property = trelloObject.get({ propName: 'propertyName' });

// Performing a PUT or POST operation on the Trello API
trelloObject.set({
  propName: 'query/path/to/propertyName',
  values: { valueType: newValue },
  preferNonIdempotence: false // Optional. If true, and if Trello supports a POST and a PUT for the given property, Trello Yello will perform a POST. If there's only one type of update operation, then this value is ignored
});

// Here's a specific example for updating an organization's description
organization.set({ propName: 'desc', values: { value: 'new description' } });

// Update a member's saved search
member.set({ propName: 'savedSearches/' + savedSearchId, values: { name: 'newName', query: 'newQuery', position: 'newPosition' }});

Trello Yello将在内部检查您的查询是否是有效的API调用。这可以防止在应用程序知道它将失败时创建网络连接。但是,Trello Yello可能有时过时,或者不支持您尝试执行的特定操作。在这种情况下,将parameters属性skipValidation设置为true。因此上面的例子将成为:

member.set({ propName: 'savedSearches/' + savedSearchId , values: { name: 'newName', query: 'newQuery', position: 'newPosition' }, skipValidation: true });

这个名字怎么了?

好吧,除了明显的押韵,以及Mello Yello饮料的参考,使用Trello Yello应该是令人耳目一新的。像炎热的夏日冰冷的柑橘饮料。我不知道。这是一个名字。你还想要我什么?

特约

欢迎任何人贡献!请遵循推荐的GitHub步骤。

等等

  • 代码:https://github.com/HolyMeekrob/trello-yello/
  • npm:https://www.npmjs.com/package/trello-yello/
  • Trello:https://www.trello.com

执照

根据MIT许可证发布。

本文使用googletrans自动翻译,仅供参考, 原文来自github.com

en_README.md

Trello Yello

Build status

Introduction

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?

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.

Installation

npm install trello-yello

Quirks

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 Promise and 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 Promise that is resolved immediately.
- All objects returned by Trello Yello are frozen using Object.freeze() (reference). This keeps the API intact, prevents potential errors through inadvertent overrides, and makes communicating about Trello Yello with others less likely to lead to confusion. The idea was taken from Douglas Crockford's talk Javascript: The Better Parts (video).
- Because of the above, you will never new an 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.

Getting Started

Trello Yello requires both an application key and a user token. Here are instructions on how to get those:

  1. You will need to generate your application key from Trello. You can do so here. More information can be found from Trello here.
  2. 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.
  3. 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):

https://trello.com/1/authorize?key=YourKeyHere&name=Trello Yello&expiration=never&response_type=token&scope=read,write,account

Using Trello Yello

Getting a reference to the module:

var trello = require('trello-yello');

Now you will need to instantiate the trello service.

var trelloService = trello({key: 'yourKey', token: 'yourToken'});

Retrieving data

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.

trelloService.getCard(id).then(function (card) {
  card.setName({ name: 'newName' });
}).catch(function (err) {
  // handle err
});

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.getCurrentUser().getBoards().then(function (boards) {
  myBoards = boards;
  // Return a Promise that resolves to an array of board names in order
  return Promise.all(boards.map(function (board) { return board.getName(); }))
}).then(function (boardNames) {
  var index = boardNames.indexOf('myBoardName');
  myBoard = myBoards[index];
  // Do something with myBoard
}).catch(function (err) {
  // handle err
});

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.

Setting data

What if you want to change the name of your list?

list.setName({ name: 'My new list name' });

Deleting data

Maybe you have a webhook that you're not using anymore

webhook.del();

Or you can delete properties on an object. Maybe you want to remove a label from a card.

card.removeLabelByColor({ color: orange });

Querying Trello

You can run searches on Trello easily.

trelloService.search({query: 'taco'}).then(function (response) {
  console.log(response);
}).catch(function (err) {
  // handle err
});

More examples

// Setting the name of the green label for a board:
trelloService.getBoard(boardId).setLabelName({ color: 'green', name: 'new name'});

// Archiving all the cards in a list
trelloService.getList(listId).archiveAllCards();

// Adding a comment to a card
trelloService.getCard(cardId).addComment({ comment: 'The comment to add.' });

// Getting all of the user's unread notifications
var allNotifications;
var unreadNotifications;
trelloService.getCurrentUser().getNotifications().then(function (notifications) {
  allNotifications = notifications;
  return Promise.all(notifications.map(function (n) {
        return n.isUnread();
    }));
}).then(function (unreadArray) {
  unreadNotifications = allNotifications.filter(function (notification, index) {
    return unreadArray[index];
  });
  // Do something with unreadNotifications
}).catch(function (err) {
  // handle err
});

// Deleting a checklist item
trelloService.getChecklist(checklistId).removeChecklistItem({ checklistItemId: 'id' });

// Deleting a label
trelloService.getLabel(labelId).del();

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 list
var property = trelloObject.get({ propName: 'propertyName' });

// Performing a PUT or POST operation on the Trello API
trelloObject.set({
  propName: 'query/path/to/propertyName',
  values: { valueType: newValue },
  preferNonIdempotence: false // Optional. If true, and if Trello supports a POST and a PUT for the given property, Trello Yello will perform a POST. If there's only one type of update operation, then this value is ignored
});

// Here's a specific example for updating an organization's description
organization.set({ propName: 'desc', values: { value: 'new description' } });

// Update a member's saved search
member.set({ propName: 'savedSearches/' + savedSearchId, values: { name: 'newName', query: 'newQuery', position: 'newPosition' }});

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 skipValidation to true. The above example would thus become:

member.set({ propName: 'savedSearches/' + savedSearchId , values: { name: 'newName', query: 'newQuery', position: 'newPosition' }, skipValidation: true });

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?

Contributing

Anyone is welcome to contribute! Please follow the recommended GitHub steps.

Etc

License

Released under the MIT license.