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
50
51
 
# 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],
    'due' => options[:due],
    'pos' => options[:pos]
  )
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



233
234
235
236
237
238
239
240
241
242
243
244
245
 
# File 'lib/trello/card.rb', line 233

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



166
167
168
169
170
 
# File 'lib/trello/card.rb', line 166

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

#add_comment(text) ⇒ Object

Add a comment with the supplied text.



161
162
163
 
# File 'lib/trello/card.rb', line 161

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

#add_label(colour) ⇒ Object

Add a label



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

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



197
198
199
200
201
 
# File 'lib/trello/card.rb', line 197

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

#attachments ⇒ Object

Retrieve a list of attachments



248
249
250
251
 
# File 'lib/trello/card.rb', line 248

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

#check_item_states ⇒ Object 



91
92
93
94
 
# File 'lib/trello/card.rb', line 91

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

#close ⇒ Object 



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

def close
  self.closed = true
end

#close! ⇒ Object 



150
151
152
153
 
# File 'lib/trello/card.rb', line 150

def close!
  close
  save
end

#closed? ⇒ Boolean

Check if the card is not active anymore.

Returns:

  • (Boolean) 


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

def closed?
  closed
end

#create_new_checklist(name) ⇒ Object

create a new checklist and add it to this card



173
174
175
 
# File 'lib/trello/card.rb', line 173

def create_new_checklist(name)
  client.post("/cards/#{id}/checklists", { name: name })
end

#delete ⇒ Object

Delete this card



137
138
139
 
# File 'lib/trello/card.rb', line 137

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

#labels ⇒ Object

Retrieve a list of labels



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

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.



101
102
103
104
105
106
 
# File 'lib/trello/card.rb', line 101

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)



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

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



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

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



254
255
256
 
# File 'lib/trello/card.rb', line 254

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

#remove_label(colour) ⇒ Object

Remove a label



224
225
226
227
228
229
230
 
# File 'lib/trello/card.rb', line 224

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



204
205
206
 
# File 'lib/trello/card.rb', line 204

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

#request_prefix ⇒ Object

:nodoc:



259
260
261
 
# File 'lib/trello/card.rb', line 259

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

#save ⇒ Object

Saves a record.



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

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,
    pos: pos
  }).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.



127
128
129
130
131
132
133
134
 
# File 'lib/trello/card.rb', line 127

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.



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

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[:pos]]
  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) 


156
157
158
 
# File 'lib/trello/card.rb', line 156

def valid?
  name && list_id
end