class MIME::CompositeMedia

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.

Attributes

boundary[R]

Public Class Methods

new(content_type) click to toggle source
Calls superclass method
# 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

Public Instance Methods

add(entity) click to toggle source

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.

# 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 = {}) click to toggle source

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)
# File lib/mime/composite_media.rb, line 96
def attach entity, params = {}
  entity.set_disposition('attachment', params)
  add(entity)
end
inline(entity, params = {}) click to toggle source

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'
# File lib/mime/composite_media.rb, line 116
def inline entity, params = {}
  entity.set_disposition('inline', params)
  add(entity)
end