class Trello::Card

A Card is a container that can house checklists and comments; it resides inside a List.

@!attribute [r] id

@return [String]

@!attribute [r] short_id

@return [Fixnum]

@!attribute [rw] name

@return [String]

@!attribute [rw] desc

@return [String]

@!attribute [rw] due

@return [Datetime]

@!attribute [rw] closed

@return [Boolean]

@!attribute [r] url

@return [String]

@!attribute [r] short_url

@return [String]

@!attribute [rw] board_id

@return [String] A 24-character hex string

@!attribute [rw] member_ids

@return [Array<String>] An Array of 24-character hex strings

@!attribute [rw] list_id

@return [String] A 24-character hex string

@!attribute [rw] pos

@return [Float]

@!attribute [r] last_activity_date

@return [Dateime]

@!attribute [rw] card_labels

@return [Array<Hash>]

@!attribute [rw] labels

@return [Array<Trello::Labels>]

@!attribute [rw] cover_image_id

@return [String] A 24-character hex string

@!attribute [r] badges

@return [Hash]

@!attribute [r] card_members

@return [Object]

@!attribute [rw] source_card_id

@return [String] A 24-character hex string

@!attribute [rw] source_card_properties

@return [Array<String>] Array of strings

Constants

SYMBOL_TO_STRING

Public Class Methods

create(options) click to toggle source

Create a new card and save it on Trello.

If using source_card_id to duplicate a card, make sure to save the source card to Trello before calling this method to assure the correct data is used in the duplication.

@param [Hash] options @option options [String] :name The name of the new card. @option options [String] :list_id ID of the list that the card should

be added to.

@option options [String] :desc A string with a

length from 0 to 16384.

@option options [String] :member_ids A comma-separated list of

objectIds (24-character hex strings).

@option options [String] :card_labels A comma-separated list of

objectIds (24-character hex strings).

@option options [Date] :due A date, or `nil`. @option options [String] :pos A position. `“top”`, `“bottom”`, or a

positive number. Defaults to `"bottom"`.

@option options [String] :source_card_id ID of the card to copy @option options [String] :source_card_properties A single, or array of,

string properties to copy from source card.
`"all"`, `"checklists"`, `"due"`, `"members"`, or `nil`.
Defaults to `"all"`.

@raise [Trello::Error] if the card could not be created.

@return [Trello::Card]

# File lib/trello/card.rb, line 118
def create(options)
  client.create(:card,
    'name' => options[:name],
    'idList' => options[:list_id],
    'desc'   => options[:desc],
    'idMembers' => options[:member_ids],
    'idLabels' => options[:card_labels],
    'due' => options[:due],
    'due_complete' => options[:due_complete] || false,
    'pos' => options[:pos],
    'idCardSource' => options[:source_card_id],
    'keepFromSource' => options.key?(:source_card_properties) ? options[:source_card_properties] : 'all'
  )
end
find(id, params = {}) click to toggle source

Find a specific card by its id.

@raise [Trello::Error] if the card could not be found.

@return [Trello::Card]

# File lib/trello/card.rb, line 86
def find(id, params = {})
  client.find(:card, id, params)
end

Public Instance Methods

add_attachment(attachment, name = '') click to toggle source

Add an attachment to this card

# File lib/trello/card.rb, line 409
def add_attachment(attachment, name = '')
  # Is it a file object or a string (url)?
  if attachment.respond_to?(:path) && attachment.respond_to?(:read)
    client.post("/cards/#{id}/attachments", {
        file: attachment,
        name: name
      })
  else
    client.post("/cards/#{id}/attachments", {
        url: attachment,
        name: name
      })
  end
end
add_checklist(checklist) click to toggle source

Add a checklist to this card

# File lib/trello/card.rb, line 324
def add_checklist(checklist)
  client.post("/cards/#{id}/checklists", {
    value: checklist.id
  })
end
add_comment(text) click to toggle source

Add a comment with the supplied text.

# File lib/trello/card.rb, line 319
def add_comment(text)
  client.post("/cards/#{id}/actions/comments", text: text)
end
add_label(label) click to toggle source

Add a label

# File lib/trello/card.rb, line 391
def add_label(label)
  unless label.valid?
    errors.add(:label, "is not valid.")
    return Trello.logger.warn "Label is not valid." unless label.valid?
  end
  client.post("/cards/#{id}/idLabels", {value: label.id})
end
add_member(member) click to toggle source

Add a member to this card

# File lib/trello/card.rb, line 355
def add_member(member)
  client.post("/cards/#{id}/members", {
    value: member.id
  })
end
attachments() click to toggle source

Retrieve a list of attachments

# File lib/trello/card.rb, line 425
def attachments
  attachments = Attachment.from_response client.get("/cards/#{id}/attachments")
  MultiAssociation.new(self, attachments).proxy
end
check_item_states() click to toggle source
# File lib/trello/card.rb, line 212
def check_item_states
  states = CheckItemState.from_response client.get("/cards/#{self.id}/checkItemStates")
  MultiAssociation.new(self, states).proxy
end
close() click to toggle source

Close the card.

This only marks your local copy card as closed. Use `close!` if you want to close the card and persist the change to the Trello API.

@return [Boolean] always returns true

@return [String] The JSON representation of the closed card returned by

the Trello API.
# File lib/trello/card.rb, line 304
def close
  self.closed = true
end
close!() click to toggle source
# File lib/trello/card.rb, line 308
def close!
  close
  save
end
closed?() click to toggle source

Check if the card is not active anymore.

# File lib/trello/card.rb, line 291
def closed?
  closed
end
create_new_checklist(name) click to toggle source

create a new checklist and add it to this card

# File lib/trello/card.rb, line 331
def create_new_checklist(name)
  client.post("/cards/#{id}/checklists", { name: name })
end
delete() click to toggle source

Delete this card

@return [String] the JSON response from the Trello API

# File lib/trello/card.rb, line 286
def delete
  client.delete("/cards/#{id}")
end
members() click to toggle source

Returns a list of members who are assigned to this card.

@return [Array<Trello::Member>]

# File lib/trello/card.rb, line 223
def members
  members = member_ids.map do |member_id|
    Member.from_response client.get("/members/#{member_id}")
  end
  MultiAssociation.new(self, members).proxy
end
move_to_board(new_board, new_list = nil) click to toggle source

Move this card to the given board (and optional list on this board)

# File lib/trello/card.rb, line 346
def move_to_board(new_board, new_list = nil)
  unless board_id == new_board.id
    payload = { value: new_board.id }
    payload[:idList] = new_list.id if new_list
    client.put("/cards/#{id}/idBoard", payload)
  end
end
move_to_list(list) click to toggle source

Move this card to the given list

# File lib/trello/card.rb, line 336
def move_to_list(list)
  list_number = list.is_a?(String) ? list : list.id
  unless list_id == list_number
    client.put("/cards/#{id}/idList", {
      value: list_number
    })
  end
end
remove_attachment(attachment) click to toggle source

Remove an attachment from this card

# File lib/trello/card.rb, line 431
def remove_attachment(attachment)
  client.delete("/cards/#{id}/attachments/#{attachment.id}")
end
remove_label(label) click to toggle source

Remove a label

# File lib/trello/card.rb, line 400
def remove_label(label)
  unless label.valid?
    errors.add(:label, "is not valid.")
    return Trello.logger.warn "Label is not valid." unless label.valid?
  end
  client.delete("/cards/#{id}/idLabels/#{label.id}")
end
remove_member(member) click to toggle source

Remove a member from this card

# File lib/trello/card.rb, line 362
def remove_member(member)
  client.delete("/cards/#{id}/members/#{member.id}")
end
remove_upvote() click to toggle source

Recind upvote. Noop if authenticated user hasn't previously voted

# File lib/trello/card.rb, line 380
def remove_upvote
  begin
    client.delete("/cards/#{id}/membersVoted/#{me.id}")
  rescue Trello::Error => e
    fail e unless e.message =~ /has not voted/i
  end

  self
end
save() click to toggle source

Saves a record.

@raise [Trello::Error] if the card could not be saved

@return [String] The JSON representation of the saved card returned by

the Trello API.
# File lib/trello/card.rb, line 246
def save
  # If we have an id, just update our fields.
  return update! if id

  from_response client.post("/cards", {
    name:   name,
    desc:   desc,
    idList: list_id,
    idMembers: member_ids,
    idLabels: card_labels,
    pos: pos,
    due: due,
    dueComplete: due_complete,
    idCardSource: source_card_id,
    keepFromSource: source_card_properties
  })
end
update!() click to toggle source

Update an existing record.

Warning: this updates all fields using values already in memory. If an external resource has updated these fields, you should refresh! this object before making your changes, and before updating the record.

@raise [Trello::Error] if the card could not be updated.

@return [String] The JSON representation of the updated card returned by

the Trello API.
# File lib/trello/card.rb, line 274
def update!
  @previously_changed = changes
  # extract only new values to build payload
  payload = Hash[changes.map { |key, values| [SYMBOL_TO_STRING[key.to_sym].to_sym, values[1]] }]
  @changed_attributes.clear

  client.put("/cards/#{id}", payload)
end
update_fields(fields) click to toggle source

Update the fields of a card.

Supply a hash of string keyed data retrieved from the Trello API representing a card.

Note that this this method does not save anything new to the Trello API, it just assigns the input attributes to your local object. If you use this method to assign attributes, call `save` or `update!` afterwards if you want to persist your changes to Trello.

@param [Hash] fields @option fields [String] :id @option fields [String] :short_id @option fields [String] :name The new name of the card. @option fields [String] :desc A string with a length from 0 to

16384

@option fields [Date] :due A date, or `nil`. @option fields [Boolean] :due_complete @option fields [Boolean] :closed @option fields [String] :url @option fields [String] :short_url @option fields [String] :board_id @option fields [String] :member_ids A comma-separated list of objectIds

(24-character hex strings).

@option fields [String] :pos A position. `“top”`, `“bottom”`, or a

positive number. Defaults to `"bottom"`.

@option fields [Array] :labels An Array of Trello::Label objects

derived from the JSON response

@option fields [String] :card_labels A comma-separated list of

objectIds (24-character hex strings).

@option fields [Object] :cover_image_id @option fields [Object] :badges @option fields [Object] :card_members @option fields [String] :source_card_id @option fields [Array] :source_card_properties

@return [Trello::Card] self

# File lib/trello/card.rb, line 171
def update_fields(fields)
  attributes[:id]                     = fields[SYMBOL_TO_STRING[:id]]
  attributes[:short_id]               = fields[SYMBOL_TO_STRING[:short_id]]
  attributes[:name]                   = fields[SYMBOL_TO_STRING[:name]] || fields[:name]
  attributes[:desc]                   = fields[SYMBOL_TO_STRING[:desc]] || fields[:desc]
  attributes[:due]                    = Time.iso8601(fields[SYMBOL_TO_STRING[:due]]) rescue nil
  attributes[:due]                    ||= fields[:due]
  attributes[:due_complete]           = fields[SYMBOL_TO_STRING[:due_complete]] || false
  attributes[:closed]                 = fields[SYMBOL_TO_STRING[:closed]]
  attributes[:url]                    = fields[SYMBOL_TO_STRING[:url]]
  attributes[:short_url]              = fields[SYMBOL_TO_STRING[:short_url]]
  attributes[:board_id]               = fields[SYMBOL_TO_STRING[:board_id]]
  attributes[:member_ids]             = fields[SYMBOL_TO_STRING[:member_ids]] || fields[:member_ids]
  attributes[:list_id]                = fields[SYMBOL_TO_STRING[:list_id]] || fields[:list_id]
  attributes[:pos]                    = fields[SYMBOL_TO_STRING[:pos]] || fields[:pos]
  attributes[:labels]                 = (fields[SYMBOL_TO_STRING[:labels]] || []).map { |lbl| Trello::Label.new(lbl) }
  attributes[:card_labels]            = fields[SYMBOL_TO_STRING[:card_labels]] || fields[:card_labels]
  attributes[:last_activity_date]     = Time.iso8601(fields[SYMBOL_TO_STRING[:last_activity_date]]) rescue nil
  attributes[:cover_image_id]         = fields[SYMBOL_TO_STRING[:cover_image_id]]
  attributes[:badges]                 = fields[SYMBOL_TO_STRING[:badges]]
  attributes[:card_members]           = fields[SYMBOL_TO_STRING[:card_members]]
  attributes[:source_card_id]         = fields[SYMBOL_TO_STRING[:source_card_id]] || fields[:source_card_id]
  attributes[:source_card_properties] = fields[SYMBOL_TO_STRING[:source_card_properties]] || fields[:source_card_properties]
  self
end
upvote() click to toggle source

Current authenticated user upvotes a card

# File lib/trello/card.rb, line 367
def upvote
  begin
    client.post("/cards/#{id}/membersVoted", {
      value: me.id
    })
  rescue Trello::Error => e
    fail e unless e.message =~ /has already voted/i
  end

  self
end
valid?() click to toggle source

Is the record valid?

# File lib/trello/card.rb, line 314
def valid?
  name && list_id
end
voters() click to toggle source

Returns a list of members who have upvoted this card NOTE: this fetches a list each time it's called to avoid case where card is voted (or vote is removed) after card is fetched. Optimizing accuracy over network performance

@return [Array<Trello::Member>]

# File lib/trello/card.rb, line 236
def voters
  Member.from_response client.get("/cards/#{id}/membersVoted")
end