Class: MIME::CompositeMedia

Inherits:
Media
  • Object
show all
Defined in:
lib/mime/composite_media.rb

Overview

Composite media types allow encapsulating, mixing, and hierarchical structuring of entities of different types within a single message. Therefore, a CompositeMedia body is composed of one or more CompositeMedia and/or DiscreteMedia objects.

CompositeMedia implements Content-Disposition for dictating presentation style of body entities via #add, #attach, and #inline. For more information on disposition parameters, such as filename, size, and modification-date, see tools.ietf.org/html/rfc2183.

This class is abstract.

Direct Known Subclasses

Message, Multipart

Defined Under Namespace

Classes: Body

Instance Attribute Summary collapse

Attributes inherited from Media

#body, #headers

Attributes included from Headers::MIME

#description, #disposition, #id, #mime_version, #transfer_encoding, #type

Instance Method Summary collapse

Methods inherited from Media

#to_s

Constructor Details

#initialize(content_type) ⇒ CompositeMedia

Returns a new instance of CompositeMedia.



46
47
48
49
50
 
# File 'lib/mime/composite_media.rb', line 46

def initialize content_type
  AbstractClassError.no_instantiation(self, CompositeMedia)
  @boundary = "Boundary_#{ID.generate_id}"  # delimits body entities
  super(Body.new(boundary), content_type, 'boundary' => boundary)
end

Instance Attribute Details

#boundary ⇒ Object (readonly)

Returns the value of attribute boundary.



44
45
46
 
# File 'lib/mime/composite_media.rb', line 44

def boundary
  @boundary
end

Instance Method Details

#add(entity) ⇒ Object

Add a Media entity to the message.

The entity will be added to the main body of the message with no disposition specified. Presentation of the entity will be dictated by the display user agent.

Text and HTML Multipart/Alternative message

A display user agent may only be capable of displaying plain text. If so, it will choose to display the Text/Plain entity. However, if it is capable of displaying HTML, it may choose to display the Text/HTML version.

msg = MIME::Multipart::Alternative.new
msg.add(MIME::Text.new('plain text'))
msg.add(MIME::Text.new('<html>html text</html>', 'html'))

The order in which the entities are added is significant. Add the simplest representations first or in increasing order of complexity.

Raises:



72
73
74
75
 
# File 'lib/mime/composite_media.rb', line 72

def add entity
  raise Error.new('can only add Media objects') unless entity.is_a? Media
  @body.add(entity)
end

#attach(entity, params = {}) ⇒ Object

Attach a Media entity to the message.

The entity will be presented as separate from the main body of the message. Thus, display of the entity will not be automatic, but contingent upon some further action of the user. For example, the display user agent may present an icon representation of the entity, which the user can select to view or save the entity.

Attachment with filename and size parameters:

f = File.open('file.txt')
file = MIME::Text.new(f.read)
text = MIME::Text.new('See the attached file.')

msg = MIME::Multipart::Mixed.new
msg.inline(text)
msg.attach(file, 'filename' => f.path, 'size' => f.size)



96
97
98
99
 
# File 'lib/mime/composite_media.rb', line 96

def attach entity, params = {}
  entity.set_disposition('attachment', params)
  add(entity)
end

#inline(entity, params = {}) ⇒ Object

Inline a Media entity in the message.

The entity will be embedded within the main body of the message. Thus, display of the entity will be automatic upon display of the message. Inline entities should be added in the order in which they occur within the message.

Message with two embedded images:

msg = MIME::Multipart::Mixed.new
msg.inline(MIME::Image.new(File.read('screenshot1.png'), 'png'))
msg.inline(MIME::Image.new(File.read('screenshot2.png'), 'png'))
msg.description = 'My screenshots'



116
117
118
119
 
# File 'lib/mime/composite_media.rb', line 116

def inline entity, params = {}
  entity.set_disposition('inline', params)
  add(entity)
end