Class: Axlsx::Package

Inherits:
Object
  • Object
show all
Includes:
OptionsParser
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 validation and serialization.

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from OptionsParser

#parse_options

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

  • :created_at (Time) —

    Timestamp in the document properties (defaults to current time).

  • :use_shared_strings (Boolean) —

    This is passed to the workbook to specify that shared strings should be used when serializing the package.

Yields:

  • (_self)

Yield Parameters:


23
24
25
26
27
28
29
30
 
# 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

Instance Attribute Details

#app ⇒ Object (readonly)

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


10
11
12
 
# File 'lib/axlsx/package.rb', line 10

def app
  @app
end

#core ⇒ Object (readonly)

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


14
15
16
 
# File 'lib/axlsx/package.rb', line 14

def core
  @core
end

Instance Method Details

#encrypt(file_name, password) ⇒ Object

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


145
146
147
148
149
 
# File 'lib/axlsx/package.rb', line 145

def encrypt(file_name, password)
  return false
  # moc = MsOffCrypto.new(file_name, password)
  # moc.save
end

#serialize(output, options = {}, secondary_options = nil) ⇒ Boolean

Note:

A tremendous amount of effort has gone into ensuring that you cannot create invalid xlsx documents. options[: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!

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

# Serialize to a file, using a system zip binary
p.serialize("example.xlsx", zip_command: "zip", confirm_valid: false)
p.serialize("example.xlsx", zip_command: "/path/to/zip")
p.serialize("example.xlsx", zip_command: "zip -1")

# Serialize to a stream
s = p.to_stream()
File.open('example_streamed.xlsx', 'wb') { |f| f.write(s.read) }

Parameters:

  • output (String) —

    The name of the file you want to serialize your package to

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

Options Hash (options):

  • :confirm_valid (Boolean) —

    Validate the package prior to serialization.

  • :zip_command (String) —

    When nil, #serialize with RubyZip to zip the XLSX file contents. When a String, the provided zip command (e.g., "zip") is used to zip the file contents (may be faster for large files)

Returns:

  • (Boolean) —

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

See Also:


103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
 
# File 'lib/axlsx/package.rb', line 103

def serialize(output, options = {}, secondary_options = nil)
  if !workbook.styles_applied
    workbook.apply_styles 
  end

  confirm_valid, zip_command = parse_serialize_options(options, secondary_options)
  return false unless !confirm_valid || self.validate.empty?
  zip_provider = if zip_command
                   ZipCommand.new(zip_command)
                 else
                   Zip::OutputStream
                 end
  Relationship.initialize_ids_cache
  zip_provider.open(output) do |zip|
    write_parts(zip)
  end
  true
ensure
  Relationship.clear_ids_cache
end

#to_stream(confirm_valid = false) ⇒ StringIO|Boolean

Serialize your workbook to a StringIO instance

Parameters:

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

    Validate the package prior to serialization.

Returns:

  • (StringIO|Boolean) —

    False if confirm_valid and validation errors exist. rewound string IO if not.


128
129
130
131
132
133
134
135
136
137
138
139
140
141
 
# File 'lib/axlsx/package.rb', line 128

def to_stream(confirm_valid=false)
  if !workbook.styles_applied
    workbook.apply_styles 
  end

  return false unless !confirm_valid || self.validate.empty?
  Relationship.initialize_ids_cache
  zip = write_parts(Zip::OutputStream.new(StringIO.new.binmode, true))
  stream = zip.close_buffer
  stream.rewind
  stream
ensure
  Relationship.clear_ids_cache
end

#use_autowidth=(v) ⇒ Object

Shortcut to specify that the workbook should use autowidth

See Also:


34
35
36
37
 
# File 'lib/axlsx/package.rb', line 34

def use_autowidth=(v)
  Axlsx::validate_boolean(v);
  workbook.use_autowidth = v
end

#use_shared_strings ⇒ Object

Shortcut to determine if the workbook is configured to use shared strings

See Also:


43
44
45
 
# File 'lib/axlsx/package.rb', line 43

def use_shared_strings
  workbook.use_shared_strings
end

#use_shared_strings=(v) ⇒ Object

Shortcut to specify that the workbook should use shared strings

See Also:


49
50
51
52
 
# File 'lib/axlsx/package.rb', line 49

def use_shared_strings=(v)
  Axlsx::validate_boolean(v);
  workbook.use_shared_strings = v
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 create 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:


166
167
168
169
170
171
172
173
174
 
# File 'lib/axlsx/package.rb', line 166

def validate
  errors = []
  parts.each do |part|
    unless part[:schema].nil?
      errors.concat validate_single_doc(part[:schema], part[:doc].to_xml_string)
    end
  end
  errors
end

#workbook {|@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.

Yields:

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.


65
66
67
68
69
 
# File 'lib/axlsx/package.rb', line 65

def workbook
  @workbook || @workbook = Workbook.new
  yield @workbook if block_given?
  @workbook
end

#workbook=(workbook) ⇒ Object

See Also:


72
 
# File 'lib/axlsx/package.rb', line 72

def workbook=(workbook) DataTypeValidator.validate :Package_workbook, Workbook, workbook; @workbook = workbook; end