Class: Axlsx::Package

Inherits:
Object
  • Object
show all
Defined in:
lib/axlsx/package.rb

Overview

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.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) {|_self| ... } ⇒ Package

Initializes your package

Examples:

Package.new :author => ‘you!’, :workbook => Workbook.new

Parameters:

  • options (Hash) (defaults to: {}) —

    A hash that you can use to specify the author and workbook for this package.

Options Hash (options):

  • :author (String) —

    The author of the document

Yields:

  • (_self)

Yield Parameters:



28
29
30
31
32
 
# File 'lib/axlsx/package.rb', line 28

def initialize(options={})
  @core, @app = Core.new, App.new
  @core.creator = options[:author] || @core.creator
  yield self if block_given?
end

Instance Attribute Details

#workbook ⇒ Workbook

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

The workbook this package will serialize or validate.

Returns:

  • (Workbook) —

    If no workbook instance has been assigned with this package a new Workbook instance is returned.

Raises:

  • ArgumentError if workbook parameter is not a Workbook instance.



21
22
23
 
# File 'lib/axlsx/package.rb', line 21

def workbook
  @workbook
end

Instance Method Details

#serialize(output, confirm_valid = false) ⇒ Boolean

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.

Serialize your workbook to disk as an xlsx document.

Examples:

# 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!
f = File.open('test.xlsx', 'w')
Package.new.serialize(f)

# You will find a file called test.xlsx

Parameters:

  • output (File) —

    The file you want to serialize your package to

  • confirm_valid (Boolean) (defaults to: false) —

    Validate the package prior to serialization.

Returns:

  • (Boolean) —

    False if confirm_valid and validation errors exist. True if the package was serialized

See Also:



55
56
57
58
59
60
61
62
 
# File 'lib/axlsx/package.rb', line 55

def serialize(output, confirm_valid=false)
  return false unless !confirm_valid || self.validate.empty?
  f = File.new(output, "w")
  Zip::ZipOutputStream.open(f.path) do |zip|
    parts.each{ |part| zip.put_next_entry(part[:entry]); zip.puts(part[:doc]) }
  end
  true
end

#validate ⇒ Array

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.

Validate all parts of the package against xsd schema.

Examples:

# 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 }

Returns:

  • (Array) —

    An array of all validation errors found.

See Also:



79
80
81
82
83
 
# File 'lib/axlsx/package.rb', line 79

def validate
  errors = []
  parts.each { |part| errors.concat validate_single_doc(part[:schema], part[:doc]) }
  errors
end