Class: Trello::Label

Inherits:
BasicData show all
Defined in:
lib/trello/label.rb

Overview

A colored Label attached to a card

Constant Summary collapse

SYMBOL_TO_STRING = 
{
  id: 'id',
  name: 'name',
  board_id: 'idBoard',
  color: 'color',
  uses: 'uses'
}
VALID_LABEL_COLOURS = 
%w{green yellow orange red purple blue sky lime pink black} << ''

Instance Attribute Summary collapse

Attributes inherited from BasicData

#client

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from BasicData

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

Methods included from JsonUtils

included

Constructor Details

#initialize(fields = {}) ⇒ Label

Returns a new instance of Label.



73
74
75
 
# File 'lib/trello/label.rb', line 73

def initialize(fields = {})
  initialize_fields(fields)
end

Instance Attribute Details

#color ⇒ String

Returns:



9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
 
# File 'lib/trello/label.rb', line 9

class Label < BasicData
  register_attributes :id, :name, :board_id, :uses,
    readonly: [ :id, :uses, :board_id ]
  validates_presence_of :id, :board_id, :name
  validates_length_of   :name,        in: 1..16384

  SYMBOL_TO_STRING = {
    id: 'id',
    name: 'name',
    board_id: 'idBoard',
    color: 'color',
    uses: 'uses'
  }

  class << self
    VALID_LABEL_COLOURS = %w{green yellow orange red purple blue sky lime pink black} << ''

    # Find a specific label by its id.
    def find(id, params = {})
      client.find(:label, id, params)
    end

    # Create a new label and save it on Trello.
    def create(options)
      client.create(:label,
        'name' => options[:name],
        'idBoard' => options[:board_id],
        'color'   => options[:color],
      )
    end

    # Label colours
    def label_colours
      VALID_LABEL_COLOURS
    end
  end

  define_attribute_methods [:color]

  def color
    @__attributes[:color]
  end

  def color= colour
    unless Label.label_colours.include? colour
      errors.add(:label, "color '#{colour}' does not exist")
      return Trello.logger.warn "The label colour '#{colour}' does not exist."
    end

    self.send(:"color_will_change!") unless colour == @__attributes[:color]
    @__attributes[:color] = colour
  end

  # Update the fields of a label.
  #
  # Supply a hash of stringkeyed data retrieved from the Trello API representing
  # a label.
  def update_fields(fields)
    send('name_will_change!') if fields_has_key?(fields, :name)
    send('color_will_change!') if fields_has_key?(fields, :color)

    initialize_fields(fields)
  end

  def initialize(fields = {})
    initialize_fields(fields)
  end

  # Returns a reference to the board this label is currently connected.
  one :board, path: :boards, using: :board_id

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

    from_response client.post("/labels", {
      name:   name,
      color:   color,
      idBoard: board_id,
    })
  end

  # 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.
  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 if @changed_attributes.respond_to?(:clear)
    changes_applied if respond_to?(:changes_applied)

    client.put("/labels/#{id}", payload)
  end

  # Delete this label
  def delete
    client.delete("/labels/#{id}")
  end

  private

  def fields_has_key?(fields, key)
    fields.key?(SYMBOL_TO_STRING[key]) || fields.key?(key)
  end

  def initialize_fields(fields)
    attributes[:id] = fields['id'] || attributes[:id]
    attributes[:name]  = fields['name'] || fields[:name] || attributes[:name]
    attributes[:color] = fields['color'] || fields[:color] || attributes[:color]
    attributes[:board_id] = fields['idBoard'] || fields[:board_id] || attributes[:board_id]
    attributes[:uses] = fields['uses'] if fields.has_key?('uses')
    self
  end
end

#id ⇒ String

Returns:



9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
 
# File 'lib/trello/label.rb', line 9

class Label < BasicData
  register_attributes :id, :name, :board_id, :uses,
    readonly: [ :id, :uses, :board_id ]
  validates_presence_of :id, :board_id, :name
  validates_length_of   :name,        in: 1..16384

  SYMBOL_TO_STRING = {
    id: 'id',
    name: 'name',
    board_id: 'idBoard',
    color: 'color',
    uses: 'uses'
  }

  class << self
    VALID_LABEL_COLOURS = %w{green yellow orange red purple blue sky lime pink black} << ''

    # Find a specific label by its id.
    def find(id, params = {})
      client.find(:label, id, params)
    end

    # Create a new label and save it on Trello.
    def create(options)
      client.create(:label,
        'name' => options[:name],
        'idBoard' => options[:board_id],
        'color'   => options[:color],
      )
    end

    # Label colours
    def label_colours
      VALID_LABEL_COLOURS
    end
  end

  define_attribute_methods [:color]

  def color
    @__attributes[:color]
  end

  def color= colour
    unless Label.label_colours.include? colour
      errors.add(:label, "color '#{colour}' does not exist")
      return Trello.logger.warn "The label colour '#{colour}' does not exist."
    end

    self.send(:"color_will_change!") unless colour == @__attributes[:color]
    @__attributes[:color] = colour
  end

  # Update the fields of a label.
  #
  # Supply a hash of stringkeyed data retrieved from the Trello API representing
  # a label.
  def update_fields(fields)
    send('name_will_change!') if fields_has_key?(fields, :name)
    send('color_will_change!') if fields_has_key?(fields, :color)

    initialize_fields(fields)
  end

  def initialize(fields = {})
    initialize_fields(fields)
  end

  # Returns a reference to the board this label is currently connected.
  one :board, path: :boards, using: :board_id

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

    from_response client.post("/labels", {
      name:   name,
      color:   color,
      idBoard: board_id,
    })
  end

  # 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.
  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 if @changed_attributes.respond_to?(:clear)
    changes_applied if respond_to?(:changes_applied)

    client.put("/labels/#{id}", payload)
  end

  # Delete this label
  def delete
    client.delete("/labels/#{id}")
  end

  private

  def fields_has_key?(fields, key)
    fields.key?(SYMBOL_TO_STRING[key]) || fields.key?(key)
  end

  def initialize_fields(fields)
    attributes[:id] = fields['id'] || attributes[:id]
    attributes[:name]  = fields['name'] || fields[:name] || attributes[:name]
    attributes[:color] = fields['color'] || fields[:color] || attributes[:color]
    attributes[:board_id] = fields['idBoard'] || fields[:board_id] || attributes[:board_id]
    attributes[:uses] = fields['uses'] if fields.has_key?('uses')
    self
  end
end

Class Method Details

.create(options) ⇒ Object

Create a new label and save it on Trello.



32
33
34
35
36
37
38
 
# File 'lib/trello/label.rb', line 32

def create(options)
  client.create(:label,
    'name' => options[:name],
    'idBoard' => options[:board_id],
    'color'   => options[:color],
  )
end

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

Find a specific label by its id.



27
28
29
 
# File 'lib/trello/label.rb', line 27

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

.label_colours ⇒ Object

Label colours



41
42
43
 
# File 'lib/trello/label.rb', line 41

def label_colours
  VALID_LABEL_COLOURS
end

Instance Method Details

#delete ⇒ Object

Delete this label



107
108
109
 
# File 'lib/trello/label.rb', line 107

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

#save ⇒ Object

Saves a record.



81
82
83
84
85
86
87
88
89
90
 
# File 'lib/trello/label.rb', line 81

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

  from_response client.post("/labels", {
    name:   name,
    color:   color,
    idBoard: board_id,
  })
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.



96
97
98
99
100
101
102
103
104
 
# File 'lib/trello/label.rb', line 96

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 if @changed_attributes.respond_to?(:clear)
  changes_applied if respond_to?(:changes_applied)

  client.put("/labels/#{id}", payload)
end

#update_fields(fields) ⇒ Object

Update the fields of a label.

Supply a hash of stringkeyed data retrieved from the Trello API representing a label.



66
67
68
69
70
71
 
# File 'lib/trello/label.rb', line 66

def update_fields(fields)
  send('name_will_change!') if fields_has_key?(fields, :name)
  send('color_will_change!') if fields_has_key?(fields, :color)

  initialize_fields(fields)
end