# r-reports-from-trello

# Overview

The goal of the Repello package is to obtain information from a Trello board and view the contents in a more user-friendly fashion. This package will allow a user to store the information from Trello cards, including card checklists and date of last modification. The package also allows two saved Trello objects to be compared to check for changes to the status and items of card checklist tasks.

# Installation

    install.packages("repello")

# Getting Started

## Loading supplementary packages

    suppressPackageStartupMessages(require(repello))
    #Note: you may want to also install the following packages for well-formatted report tables
    suppressPackageStartupMessages(require(knitr))
    suppressPackageStartupMessages(require(kableExtra))

## Setting the user token

Using this package requires you to have your own Trello account. This package obtains information from Trello boards using API calls. To access Trello information, you first need to obtain your unique user key and token. Access to these can be found by logging into Trello and visiting `https://trello.com/app-key`, then by clicking on “Manually generate a token”. Once you have generated your key and token, you can either save it into a text file somewhere on your computer or you may manually enter them when prompted. If you opt to save them as text files on your computer, be sure to set your working directory to the file location before you attempt to run the code.

Setting the user token is a critical first step for using this package. Always be sure to set the token prior to using any of the other functions in this package

    set_key_token(key_file="user_key.txt", token_file="user_token.txt")
    #Alternatively, you may leave the arguments blank and manually enter the key and token when prompted
    set_key_token()

# Viewing information for a specified Trello board

All you need to get started with the Repello package is the name of the board you want to view. This example will use the board “Repello - R Reports from Trello”. You can access this board on Trello for reference at https://trello.com/b/CMNHqjea/repello-r-reports-from-trello.

The cards_info function allows you to view the card information from a board.

    activity <- cards_info(get_board_id("Repello - R Reports from Trello"))
    head(activity) %>% kable(escape=F, align="cl") %>% trimws %>% kable_styling(c("striped","bordered"))

Card | ID | Date last modified | Trello List
--- | --- | --- | ---
Project A | 5f6a1f38e97e9c6baa6c6181 | 2020-09-24 | To-do List
Project B | 5f6a1f3bc677e234eb1697f0 | 2020-09-22 | To-do List
Project C | 5f6a1f40b72a5b53ecce371a | 2020-09-22 | To-do List
Project D | 5f6a3107975a8523081100ba | 2020-09-22 | To-do List
Project E | 5f6a33c3f011bd43bcab0b89 | 2020-09-22 | To-do List

## Checklists

The all_checklists function can be used to view all card information and accompanying checklists in a list format.

    trello_object <- all_checklists("Repello - R Reports from Trello", save=FALSE)
    #save can be set to 'TRUE' if you want to save the current Trello object for
    #later comparison
    trello_object[[4]]

    ## $name
    ## [1] "Project D"
    ##
    ## $ID
    ## [1] "5f6a3107975a8523081100ba"
    ##
    ## $date
    ## [1] "2020-09-22"
    ##
    ## $list
    ## [1] "To-do List"
    ##
    ## $item
    ## [1] "Item 1" "Item 2" "Item 3" "Item 4" "Item 5" "Item 6" "Item 7"
    ##
    ## $status
    ## [1] "complete"   "complete"   "incomplete" "complete"   "complete"
    ## [6] "incomplete" "incomplete"

Viewing a sample of one of the board’s cards, you can see that six different pieces of information are presented: the name of the card, the card ID, the date of last modification, the Trello list the card is on, and the items and their respective status on a card checklist. If no list is present, the only item will be "No checklist for this project.

    trello_object[[2]]

    ## $name
    ## [1] "Project B"
    ##
    ## $ID
    ## [1] "5f6a1f3bc677e234eb1697f0"
    ##
    ## $date
    ## [1] "2020-09-22"
    ##
    ## $list
    ## [1] "To-do List"
    ##
    ## $item
    ## [1] "No checklist for this project"
    ##
    ## $status
    ## [1] "No checklist for this project"

# Comparing two Trello objects

One of the main goals of this package is to compare the Trello board at two different time points to check for changes made to the checklists. The trello_updates function can locate any new tasks or status changes made to the Trello cards, and can also determine if any new cards have been added since the last saved object.

    report <- trello_updates("Repello - R Reports from Trello", prior="old_object.rds", save=FALSE)
    #Note: If 'prior' is not specified, the function will automatically find the most recent saved
    #Trello object to compare to the current rendition.  The function can also accept a 'recent'
    #argument if you want to compare two lists from different time points.

    report[[4]]

    ## $name
    ## [1] "Project D"
    ##
    ## $ID
    ## [1] "5f6a3107975a8523081100ba"
    ##
    ## $card_status
    ## [1] "Existing Card"
    ##
    ## $contains_list
    ## [1] "List Available"
    ##
    ## $list_diff
    ##     item       history               status
    ## 1 Item 1 Existing Item      Newly Completed
    ## 2 Item 2 Existing Item Previously Completed
    ## 3 Item 3 Existing Item           Incomplete
    ## 4 Item 4 Existing Item      Newly Completed
    ## 5 Item 5 Existing Item      Newly Completed
    ## 6 Item 6      New Item           Incomplete
    ## 7 Item 7      New Item           Incomplete

If a card appears on the newest Trello object, but was absent from the prior rendition, it will be marked as a new card and all checklist items will be considered new items.

    report[[5]]

    ## $name
    ## [1] "Project E"
    ##
    ## $ID
    ## [1] "5f6a33c3f011bd43bcab0b89"
    ##
    ## $card_status
    ## [1] "New Card"
    ##
    ## $contains_list
    ## [1] "List Available"
    ##
    ## $list_diff
    ##     item  history          status
    ## 1 Item 1 New Item Newly Completed
    ## 2 Item 2 New Item Newly Completed
    ## 3 Item 3 New Item      Incomplete

Some cards do not have checklists. If this happens, repello will leave the list_diff element empty for the card.

    report[[2]]

    ## $name
    ## [1] "Project B"
    ##
    ## $ID
    ## [1] "5f6a1f3bc677e234eb1697f0"
    ##
    ## $card_status
    ## [1] "Existing Card"
    ##
    ## $contains_list
    ## [1] "No List Available"
    ##
    ## $list_diff
    ## [1] item    history status
    ## <0 rows> (or 0-length row.names)

# Creating a Trello Report

The following code is used to create a kable-formatted report of the tasks and status of items for each checklist on a recent Trello object compared to a prior Trello list from the same board. The functions used above are utilized here.

    set_token("user_token.txt")
    report <- trello_updates("Repello - R Reports from Trello", prior="old_object.rds", save=FALSE)

    new_sticker <- "<div class='sticker'>NEW</div>"
    new_headersticker <- "<div class='header-sticker'>NEW</div>"
    checkmark <- "<span class='checkmark'><div class='checkmark_stem'></div><div class='checkmark_kick'></div></span>"

    for (i in 1:length(report)){
      if (report[[i]]$contains_list=="List Available" & ("New Item" %in% (report[[i]]$list_diff)$history | "Newly Completed" %in% (report[[i]]$list_diff)$status)){
        if (report[[i]]$card_status=="New Card"){
          cat("<h2>", new_headersticker, report[[i]]$name, "</h2>", sep = " ")
        } else {
          cat("## ", report[[i]]$name, "\n\n")
        }
        temp <- report[[i]]$list_diff %>% filter(history=="New Item" | status=="Newly Completed")
        for (j in 1:nrow(temp)){
          if (temp$history[j]=="New Item"){
            temp$item[j] <- paste0(new_sticker, temp$item[j])
          }
        }
        for (k in 1:nrow(temp)){
          if (temp$status[k]=="Newly Completed"){
            temp$complete[k] <- checkmark
          } else {
            temp$complete[k] <- " "
          }
        }
        temp <- temp %>% select(complete, item)
        colnames(temp) <- c("", "Item")
        temp %>% kable(escape=F, align="cl") %>% trimws %>% kable_styling(c("striped","bordered")) %>% column_spec(1, "30px") %>% cat
        cat("  \n")
      }
    }

## Project A

| Item
--- | ---
| Item 1

## Project D

| Item
--- | ---
| Item 1
| Item 4
| Item 5
| NEW Item 6
| NEW Item 7

##
NEW
Project E

| Item
--- | ---
| NEW Item 1
| NEW Item 2
| NEW Item 3