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 420
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 325
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 320
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 402
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 366
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 436
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 213
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 305
def close
  self.closed = true
end
close!() click to toggle source
# File lib/trello/card.rb, line 309
def close!
  close
  save
end
closed?() click to toggle source

Check if the card is not active anymore.

# File lib/trello/card.rb, line 292
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 332
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 287
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 224
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 357
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 337
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
move_to_list_on_any_board(list_id) click to toggle source

Moves this card to the given list no matter which board it is on

# File lib/trello/card.rb, line 347
def move_to_list_on_any_board(list_id)
  list = List.find(list_id)
  if board.id == list.board_id
    move_to_list(list_id)
  else
    move_to_board(Board.find(list.board_id), list)
  end
end
remove_attachment(attachment) click to toggle source

Remove an attachment from this card

# File lib/trello/card.rb, line 442
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 411
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 373
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 391
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 247
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 275
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[:id]
  attributes[:short_id]               = fields[SYMBOL_TO_STRING[:short_id]] || attributes[:short_id]
  attributes[:name]                   = fields[SYMBOL_TO_STRING[:name]] || fields[:name] || attributes[:name]
  attributes[:desc]                   = fields[SYMBOL_TO_STRING[:desc]] || fields[:desc] || attributes[:desc]
  attributes[:due]                    = Time.iso8601(fields[SYMBOL_TO_STRING[:due]]) rescue nil if fields.has_key?(SYMBOL_TO_STRING[:due])
  attributes[:due]                    = fields[:due] if fields.has_key?(:due)
  attributes[:due_complete]           = fields[SYMBOL_TO_STRING[:due_complete]] if fields.has_key?(SYMBOL_TO_STRING[:due_complete])
  attributes[:due_complete]           ||= false
  attributes[:closed]                 = fields[SYMBOL_TO_STRING[:closed]] if fields.has_key?(SYMBOL_TO_STRING[:closed])
  attributes[:url]                    = fields[SYMBOL_TO_STRING[:url]] || attributes[:url]
  attributes[:short_url]              = fields[SYMBOL_TO_STRING[:short_url]] || attributes[:short_url]
  attributes[:board_id]               = fields[SYMBOL_TO_STRING[:board_id]] || attributes[:board_id]
  attributes[:member_ids]             = fields[SYMBOL_TO_STRING[:member_ids]] || fields[:member_ids] || attributes[:member_ids]
  attributes[:list_id]                = fields[SYMBOL_TO_STRING[:list_id]] || fields[:list_id] || attributes[:list_id]
  attributes[:pos]                    = fields[SYMBOL_TO_STRING[:pos]] || fields[:pos] || attributes[:pos]
  attributes[:labels]                 = (fields[SYMBOL_TO_STRING[:labels]] || []).map { |lbl| Trello::Label.new(lbl) }.presence || attributes[:labels].presence || []
  attributes[:card_labels]            = fields[SYMBOL_TO_STRING[:card_labels]] || fields[:card_labels] || attributes[:card_labels]
  attributes[:last_activity_date]     = Time.iso8601(fields[SYMBOL_TO_STRING[:last_activity_date]]) rescue nil if fields.has_key?(SYMBOL_TO_STRING[:last_activity_date])
  attributes[:cover_image_id]         = fields[SYMBOL_TO_STRING[:cover_image_id]] || attributes[:cover_image_id]
  attributes[:badges]                 = fields[SYMBOL_TO_STRING[:badges]] || attributes[:badges]
  attributes[:card_members]           = fields[SYMBOL_TO_STRING[:card_members]] || attributes[:card_members]
  attributes[:source_card_id]         = fields[SYMBOL_TO_STRING[:source_card_id]] || fields[:source_card_id] || attributes[:source_card_id]
  attributes[:source_card_properties] = fields[SYMBOL_TO_STRING[:source_card_properties]] || fields[:source_card_properties] || attributes[:source_card_properties]
  self
end
upvote() click to toggle source

Current authenticated user upvotes a card

# File lib/trello/card.rb, line 378
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 315
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 237
def voters
  Member.from_response client.get("/cards/#{id}/membersVoted")
end