Class: Trello::Card

Inherits:
BasicData show all
Includes:
HasActions
Defined in:
lib/trello/card.rb

Overview

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

Constant Summary collapse

SYMBOL_TO_STRING = 
{
  id: 'id',
  short_id: 'idShort',
  name: 'name',
  desc: 'desc',
  due: 'due',
  closed: 'closed',
  url: 'url',
  short_url: 'shortUrl',
  board_id: 'idBoard',
  member_ids: 'idMembers',
  cover_image_id: 'idAttachmentCover',
  list_id: 'idList',
  pos: 'pos',
  last_activity_date: 'dateLastActivity',
  card_labels: 'labels',
  badges: 'badges',
  card_members: 'members'
}

Instance Attribute Summary

Attributes inherited from BasicData

#client

Class Method Summary collapse

Instance Method Summary collapse

Methods included from HasActions

#actions

Methods inherited from BasicData

#==, client, #initialize, many, one, parse, parse_many, path_name, #refresh!, register_attributes, save

Constructor Details

This class inherits a constructor from Trello::BasicData

Class Method Details

.create(options) ⇒ Object

Create a new card and save it on Trello.



41
42
43
44
45
46
47
48
49
 
# File 'lib/trello/card.rb', line 41

def create(options)
  client.create(:card,
    'name' => options[:name],
    'idList' => options[:list_id],
    'desc'   => options[:desc],
    'idMembers' => options[:member_ids],
    'labels' => options[:card_labels]
  )
end

.find(id, params = {}) ⇒ Object

Find a specific card by its id.



36
37
38
 
# File 'lib/trello/card.rb', line 36

def find(id, params = {})
  client.find(:card, id, params)
end

Instance Method Details

#add_attachment(attachment, name = '') ⇒ Object

Add an attachment to this card



225
226
227
228
229
230
231
232
233
234
235
236
237
 
# File 'lib/trello/card.rb', line 225

def add_attachment(attachment, name='')
  if attachment.is_a? File
    client.post("/cards/#{id}/attachments", {
        :file => attachment,
        :name => name
      })
  else
    client.post("/cards/#{id}/attachments", {
        :url => attachment,
        :name => name
      })
  end
end

#add_checklist(checklist) ⇒ Object

Add a checklist to this card



163
164
165
166
167
 
# File 'lib/trello/card.rb', line 163

def add_checklist(checklist)
  client.post("/cards/#{id}/checklists", {
    :value => checklist.id
  })
end

#add_comment(text) ⇒ Object

Add a comment with the supplied text.



158
159
160
 
# File 'lib/trello/card.rb', line 158

def add_comment(text)
  client.post("/cards/#{id}/actions/comments", :text => text)
end

#add_label(colour) ⇒ Object

Add a label



207
208
209
210
211
212
213
 
# File 'lib/trello/card.rb', line 207

def add_label(colour)
  unless %w{green yellow orange red purple blue}.include? colour
    errors.add(:label, "colour '#{colour}' does not exist")
    return Trello.logger.warn "The label colour '#{colour}' does not exist."
  end
  client.post("/cards/#{id}/labels", { :value => colour })
end

#add_member(member) ⇒ Object

Add a member to this card



189
190
191
192
193
 
# File 'lib/trello/card.rb', line 189

def add_member(member)
  client.post("/cards/#{id}/members", {
    :value => member.id
  })
end

#attachments ⇒ Object

Retrieve a list of attachments



240
241
242
243
 
# File 'lib/trello/card.rb', line 240

def attachments
  attachments = client.get("/cards/#{id}/attachments").json_into(Attachment)
  MultiAssociation.new(self, attachments).proxy
end

#check_item_states ⇒ Object 



89
90
91
92
 
# File 'lib/trello/card.rb', line 89

def check_item_states
  states = client.get("/cards/#{self.id}/checkItemStates").json_into(CheckItemState)
  MultiAssociation.new(self, states).proxy
end

#close ⇒ Object 



143
144
145
 
# File 'lib/trello/card.rb', line 143

def close
  self.closed = true
end

#close! ⇒ Object 



147
148
149
150
 
# File 'lib/trello/card.rb', line 147

def close!
  close
  save
end

#closed? ⇒ Boolean

Check if the card is not active anymore.

Returns:

  • (Boolean) 


139
140
141
 
# File 'lib/trello/card.rb', line 139

def closed?
  closed
end

#delete ⇒ Object

Delete this card



134
135
136
 
# File 'lib/trello/card.rb', line 134

def delete
  client.delete("/cards/#{id}")
end

#labels ⇒ Object

Retrieve a list of labels



201
202
203
204
 
# File 'lib/trello/card.rb', line 201

def labels
  labels = client.get("/cards/#{id}/labels").json_into(Label)
  MultiAssociation.new(self, labels).proxy
end

#members ⇒ Object

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



99
100
101
102
103
104
 
# File 'lib/trello/card.rb', line 99

def members
  members = member_ids.map do |member_id|
    client.get("/members/#{member_id}").json_into(Member)
  end
  MultiAssociation.new(self, members).proxy
end

#move_to_board(new_board, new_list = nil) ⇒ Object

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



180
181
182
183
184
185
186
 
# File 'lib/trello/card.rb', line 180

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) ⇒ Object

Move this card to the given list



170
171
172
173
174
175
176
177
 
# File 'lib/trello/card.rb', line 170

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) ⇒ Object

Remove an attachment from this card



246
247
248
 
# File 'lib/trello/card.rb', line 246

def remove_attachment(attachment)
  client.delete("/cards/#{id}/attachments/#{attachment.id}")
end

#remove_label(colour) ⇒ Object

Remove a label



216
217
218
219
220
221
222
 
# File 'lib/trello/card.rb', line 216

def remove_label(colour)
  unless %w{green yellow orange red purple blue}.include? colour
    errors.add(:label, "colour '#{colour}' does not exist")
    return Trello.logger.warn "The label colour '#{colour}' does not exist." unless %w{green yellow orange red purple blue}.include? colour
  end
  client.delete("/cards/#{id}/labels/#{colour}")
end

#remove_member(member) ⇒ Object

Remove a member from this card



196
197
198
 
# File 'lib/trello/card.rb', line 196

def remove_member(member)
  client.delete("/cards/#{id}/members/#{member.id}")
end

#request_prefix ⇒ Object

:nodoc:



251
252
253
 
# File 'lib/trello/card.rb', line 251

def request_prefix
  "/cards/#{id}"
end

#save ⇒ Object

Saves a record.



107
108
109
110
111
112
113
114
115
116
117
118
 
# File 'lib/trello/card.rb', line 107

def save
  # If we have an id, just update our fields.
  return update! if id

  client.post("/cards", {
    name:   name,
    desc:   desc,
    idList: list_id,
    idMembers: member_ids,
    labels: card_labels
  }).json_into(self)
end

#update! ⇒ Object

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.



124
125
126
127
128
129
130
131
 
# File 'lib/trello/card.rb', line 124

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) ⇒ Object

Update the fields of a card.

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



56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
 
# File 'lib/trello/card.rb', line 56

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]]
  attributes[:desc]               = fields[SYMBOL_TO_STRING[:desc]]
  attributes[:due]                = Time.iso8601(fields[SYMBOL_TO_STRING[:due]]) rescue nil
  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]]
  attributes[:list_id]            = fields[SYMBOL_TO_STRING[:list_id]]
  attributes[:pos]                = fields[SYMBOL_TO_STRING[:post]]
  attributes[:card_labels]        = fields[SYMBOL_TO_STRING[: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]]
  self
end

#valid? ⇒ Boolean

Is the record valid?

Returns:

  • (Boolean) 


153
154
155
 
# File 'lib/trello/card.rb', line 153

def valid?
  name && list_id
end