class Axlsx::Package

Package is responsible for managing all the bits and peices that Open Office XML requires to make a valid xlsx document including valdation and serialization.

Attributes

app[R]

provides access to the app doc properties for this package see App

core[R]

provides access to the core doc properties for the package see Core

Public Class Methods

new(options={}) { |self| ... } click to toggle source

Initializes your package

@param [Hash] options A hash that you can use to specify the author and workbook for this package. @option options [String] :author The author of the document @option options [Time] :created_at Timestamp in the document properties (defaults to current time). @option options [Boolean] :use_shared_strings This is passed to the workbook to specify that shared strings should be used when serializing the package. @example Package.new :author => ‘you!’, :workbook => Workbook.new

# File lib/axlsx/package.rb, line 23
def initialize(options={})
  @workbook = nil
  @core, @app  =  Core.new, App.new
  @core.creator = options[:author] || @core.creator
  @core.created = options[:created_at]
  parse_options options
  yield self if block_given?
end

Public Instance Methods

encrypt(file_name, password) click to toggle source

Encrypt the package into a CFB using the password provided This is not ready yet

# File lib/axlsx/package.rb, line 125
def encrypt(file_name, password)
  return false
  # moc = MsOffCrypto.new(file_name, password)
  # moc.save
end
serialize(output, confirm_valid=false) click to toggle source

Serialize your workbook to disk as an xlsx document.

@param [String] output The name of the file you want to serialize your package to @param [Boolean] confirm_valid Validate the package prior to serialization. @return [Boolean] False if confirm_valid and validation errors exist. True if the package was serialized @note A tremendous amount of effort has gone into ensuring that you cannot create invalid xlsx documents.

confirm_valid should be used in the rare case that you cannot open the serialized file.

@see Package#validate @example

# This is how easy it is to create a valid xlsx file. Of course you might want to add a sheet or two, and maybe some data, styles and charts.
# Take a look at the README for an example of how to do it!

#serialize to a file
p = Axlsx::Package.new
# ......add cool stuff to your workbook......
p.serialize("example.xlsx")

# Serialize to a stream
s = p.to_stream()
File.open('example_streamed.xlsx', 'w') { |f| f.write(s.read) }
# File lib/axlsx/package.rb, line 101
def serialize(output, confirm_valid=false)
  return false unless !confirm_valid || self.validate.empty?
  Relationship.clear_cached_instances
  Zip::OutputStream.open(output) do |zip|
    write_parts(zip)
  end
  true
end
to_stream(confirm_valid=false) click to toggle source

Serialize your workbook to a StringIO instance @param [Boolean] confirm_valid Validate the package prior to serialization. @return [StringIO|Boolean] False if confirm_valid and validation errors exist. rewound string IO if not.

# File lib/axlsx/package.rb, line 114
def to_stream(confirm_valid=false)
  return false unless !confirm_valid || self.validate.empty?
  Relationship.clear_cached_instances
  zip = write_parts(Zip::OutputStream.new("streamed", true))
  stream = zip.close_buffer
  stream.rewind
  stream
end
use_autowidth=(v) click to toggle source

Shortcut to specify that the workbook should use autowidth @see Workbook#use_autowidth

# File lib/axlsx/package.rb, line 34
def use_autowidth=(v)
  Axlsx::validate_boolean(v);
  workbook.use_autowidth = v
end
use_shared_strings() click to toggle source

Shortcut to determine if the workbook is configured to use shared strings @see Workbook#use_shared_strings

# File lib/axlsx/package.rb, line 43
def use_shared_strings
  workbook.use_shared_strings
end
use_shared_strings=(v) click to toggle source

Shortcut to specify that the workbook should use shared strings @see Workbook#use_shared_strings

# File lib/axlsx/package.rb, line 49
def use_shared_strings=(v)
  Axlsx::validate_boolean(v);
  workbook.use_shared_strings = v
end
validate() click to toggle source

Validate all parts of the package against xsd schema. @return [Array] An array of all validation errors found. @note This gem includes all schema from OfficeOpenXML-XMLSchema-Transitional.zip and OpenPackagingConventions-XMLSchema.zip

as per ECMA-376, Third edition. opc schema require an internet connection to import remote schema from dublin core for dc,
dcterms and xml namespaces. Those remote schema are included in this gem, and the original files have been altered to
refer to the local versions.

If by chance you are able to creat a package that does not validate it indicates that the internal
validation is not robust enough and needs to be improved. Please report your errors to the gem author.

@see www.ecma-international.org/publications/standards/Ecma-376.htm @example

# The following will output any error messages found in serialization.
p = Axlsx::Package.new
# ... code to create sheets, charts, styles etc.
p.validate.each { |error| puts error.message }
# File lib/axlsx/package.rb, line 146
def validate
  errors = []
  parts.each do |part|
    errors.concat validate_single_doc(part[:schema], part[:doc]) unless part[:schema].nil?
  end
  errors
end
workbook() { |workbook| ... } click to toggle source

The workbook this package will serialize or validate. @return [Workbook] If no workbook instance has been assigned with this package a new Workbook instance is returned. @raise ArgumentError if workbook parameter is not a Workbook instance. @note As there are multiple ways to instantiate a workbook for the package,

here are a few examples:
  # assign directly during package instanciation
  wb = Package.new(:workbook => Workbook.new).workbook

  # get a fresh workbook automatically from the package
  wb = Pacakge.new().workbook
  #     # set the workbook after creating the package
  wb = Package.new().workbook = Workbook.new
# File lib/axlsx/package.rb, line 65
def workbook
  @workbook || @workbook = Workbook.new
  yield @workbook if block_given?
  @workbook
end
workbook=(workbook) click to toggle source

@see workbook

# File lib/axlsx/package.rb, line 79
def workbook=(workbook) DataTypeValidator.validate "Package.workbook", Workbook, workbook; @workbook = workbook; end

Private Instance Methods

base_content_types() click to toggle source

Creates the minimum content types for generating a valid xlsx document. @return [ContentType] @private

# File lib/axlsx/package.rb, line 327
def base_content_types
  c_types = ContentType.new()
  c_types <<  Default.new(:ContentType => RELS_CT, :Extension => RELS_EX)
  c_types <<  Default.new(:Extension => XML_EX, :ContentType => XML_CT)
  c_types << Override.new(:PartName => "/#{APP_PN}", :ContentType => APP_CT)
  c_types << Override.new(:PartName => "/#{CORE_PN}", :ContentType => CORE_CT)
  c_types << Override.new(:PartName => "/xl/#{STYLES_PN}", :ContentType => STYLES_CT)
  c_types << Axlsx::Override.new(:PartName => "/#{WORKBOOK_PN}", :ContentType => WORKBOOK_CT)
  c_types.lock
  c_types
end
content_types() click to toggle source

Appends override objects for drawings, charts, and sheets as they exist in your workbook to the default content types. @return [ContentType] @private

# File lib/axlsx/package.rb, line 267
def content_types
  c_types = base_content_types
  workbook.drawings.each do |drawing|
    c_types << Axlsx::Override.new(:PartName => "/xl/#{drawing.pn}",
                                   :ContentType => DRAWING_CT)
  end

  workbook.charts.each do |chart|
    c_types << Axlsx::Override.new(:PartName => "/xl/#{chart.pn}",
                                   :ContentType => CHART_CT)
  end

  workbook.tables.each do |table|
    c_types << Axlsx::Override.new(:PartName => "/xl/#{table.pn}",
                                   :ContentType => TABLE_CT)
  end

  workbook.pivot_tables.each do |pivot_table|
    c_types << Axlsx::Override.new(:PartName => "/xl/#{pivot_table.pn}",
                                   :ContentType => PIVOT_TABLE_CT)
    c_types << Axlsx::Override.new(:PartName => "/xl/#{pivot_table.cache_definition.pn}",
                                   :ContentType => PIVOT_TABLE_CACHE_DEFINITION_CT)
  end

  workbook.comments.each do |comment|
    if comment.size > 0
    c_types << Axlsx::Override.new(:PartName => "/xl/#{comment.pn}",
                                   :ContentType => COMMENT_CT)
    end
  end

  if workbook.comments.size > 0
    c_types << Axlsx::Default.new(:Extension => "vml", :ContentType => VML_DRAWING_CT)
  end

  workbook.worksheets.each do |sheet|
    c_types << Axlsx::Override.new(:PartName => "/xl/#{sheet.pn}",
                                     :ContentType => WORKSHEET_CT)
  end
  exts = workbook.images.map { |image| image.extname }
  exts.uniq.each do |ext|
    ct = if  ['jpeg', 'jpg'].include?(ext)
           JPEG_CT
         elsif ext == 'gif'
           GIF_CT
         elsif ext == 'png'
           PNG_CT
         end
    c_types << Axlsx::Default.new(:ContentType => ct, :Extension => ext )
  end
  if use_shared_strings
    c_types << Axlsx::Override.new(:PartName => "/xl/#{SHARED_STRINGS_PN}",
                                   :ContentType => SHARED_STRINGS_CT)
  end
  c_types
end
parts() click to toggle source

The parts of a package @return [Array] An array of hashes that define the entry, document and schema for each part of the package. @private

# File lib/axlsx/package.rb, line 195
def parts
  parts = [
   {:entry => RELS_PN, :doc => relationships.to_xml_string, :schema => RELS_XSD},
   {:entry => "xl/#{STYLES_PN}", :doc => workbook.styles.to_xml_string, :schema => SML_XSD},
   {:entry => CORE_PN, :doc => @core.to_xml_string, :schema => CORE_XSD},
   {:entry => APP_PN, :doc => @app.to_xml_string, :schema => APP_XSD},
   {:entry => WORKBOOK_RELS_PN, :doc => workbook.relationships.to_xml_string, :schema => RELS_XSD},
   {:entry => CONTENT_TYPES_PN, :doc => content_types.to_xml_string, :schema => CONTENT_TYPES_XSD},
   {:entry => WORKBOOK_PN, :doc => workbook.to_xml_string, :schema => SML_XSD}
  ]

  workbook.drawings.each do |drawing|
    parts << {:entry => "xl/#{drawing.rels_pn}", :doc => drawing.relationships.to_xml_string, :schema => RELS_XSD}
    parts << {:entry => "xl/#{drawing.pn}", :doc => drawing.to_xml_string, :schema => DRAWING_XSD}
  end


  workbook.tables.each do |table|
    parts << {:entry => "xl/#{table.pn}", :doc => table.to_xml_string, :schema => SML_XSD}
  end
  workbook.pivot_tables.each do |pivot_table|
    cache_definition = pivot_table.cache_definition
    parts << {:entry => "xl/#{pivot_table.rels_pn}", :doc => pivot_table.relationships.to_xml_string, :schema => RELS_XSD}
    parts << {:entry => "xl/#{pivot_table.pn}", :doc => pivot_table.to_xml_string} #, :schema => SML_XSD}
    parts << {:entry => "xl/#{cache_definition.pn}", :doc => cache_definition.to_xml_string} #, :schema => SML_XSD}
  end

  workbook.comments.each do|comment|
    if comment.size > 0
      parts << { :entry => "xl/#{comment.pn}", :doc => comment.to_xml_string, :schema => SML_XSD }
      parts << { :entry => "xl/#{comment.vml_drawing.pn}", :doc => comment.vml_drawing.to_xml_string, :schema => nil }
    end
  end

  workbook.charts.each do |chart|
    parts << {:entry => "xl/#{chart.pn}", :doc => chart.to_xml_string, :schema => DRAWING_XSD}
  end

  workbook.images.each do |image|
    parts << {:entry => "xl/#{image.pn}", :path => image.image_src}
  end

  if use_shared_strings
    parts << {:entry => "xl/#{SHARED_STRINGS_PN}", :doc => workbook.shared_strings.to_xml_string, :schema => SML_XSD}
  end

  workbook.worksheets.each do |sheet|
    parts << {:entry => "xl/#{sheet.rels_pn}", :doc => sheet.relationships.to_xml_string, :schema => RELS_XSD}
    parts << {:entry => "xl/#{sheet.pn}", :doc => sheet.to_xml_string, :schema => SML_XSD}
  end
  parts
end
relationships() click to toggle source

Creates the relationships required for a valid xlsx document @return [Relationships] @private

# File lib/axlsx/package.rb, line 342
def relationships
  rels = Axlsx::Relationships.new
  rels << Relationship.new(self, WORKBOOK_R, WORKBOOK_PN)
  rels << Relationship.new(self, CORE_R, CORE_PN)
  rels << Relationship.new(self, APP_R, APP_PN)
  rels.lock
  rels
end
validate_single_doc(schema, doc) click to toggle source

Performs xsd validation for a signle document

@param [String] schema path to the xsd schema to be used in validation. @param [String] doc The xml text to be validated @return [Array] An array of all validation errors encountered. @private

# File lib/axlsx/package.rb, line 254
def validate_single_doc(schema, doc)
  schema = Nokogiri::XML::Schema(File.open(schema))
  doc = Nokogiri::XML(doc)
  errors = []
  schema.validate(doc).each do |error|
    errors << error
  end
  errors
end
write_parts(zip) click to toggle source

Writes the package parts to a zip archive. @param [Zip::OutputStream] zip @return [Zip::OutputStream]

# File lib/axlsx/package.rb, line 159
def write_parts(zip)
  p = parts
  p.each do |part|
    unless part[:doc].nil?
      zip.put_next_entry(zip_entry_for_part(part))
      entry = ['1.9.2', '1.9.3'].include?(RUBY_VERSION) ? part[:doc].force_encoding('BINARY') : part[:doc]
      zip.puts(entry)
    end
    unless part[:path].nil?
      zip.put_next_entry(zip_entry_for_part(part))
      # binread for 1.9.3
      zip.write IO.respond_to?(:binread) ? IO.binread(part[:path]) : IO.read(part[:path])
    end
  end
  zip
end
zip_entry_for_part(part) click to toggle source

Generate a Entry for the given package part. The important part here is to explicitly set the timestamp for the zip entry: Serializing axlsx packages with identical contents should result in identical zip files – however, the timestamp of a zip entry defaults to the time of serialization and therefore the zip file contents would be different every time the package is serialized.

Note: {Core#created} also defaults to the current time – so to generate identical axlsx packages you have to set this explicitly, too (eg. with ‘Package.new(created_at: Time.local(2013, 1, 1))`).

@param part A hash describing a part of this pacakge (see {#parts}) @return [Zip::Entry]

# File lib/axlsx/package.rb, line 187
def zip_entry_for_part(part)
  timestamp = Zip::DOSTime.at(@core.created.to_i)
  Zip::Entry.new("", part[:entry], "", "", 0, 0, Zip::Entry::DEFLATED, 0, timestamp)
end