write_xlsx 1.07.0 → 1.09.0

data/lib/write_xlsx/format.rb

@@ -2,177 +2,20 @@
 require 'write_xlsx/utility'
 
 module Writexlsx
-  # ==CELL FORMATTING
-  #
-  # This section describes the methods and properties that are available
-  # for formatting cells in Excel. The properties of a cell that can be
-  # formatted include: fonts, colours, patterns, borders, alignment and
-  # number formatting.
-  #
-  # ===Creating and using a Format object
-  #
-  # Cell formatting is defined through a Format object. Format objects
-  # are created by calling the workbook add_format() method as follows:
-  #
-  #     format1 = workbook.add_format             # Set properties later
-  #     format2 = workbook.add_format(props_hash) # Set at creation
-  #
-  # The format object holds all the formatting properties that can be applied
-  # to a cell, a row or a column. The process of setting these properties is
-  # discussed in the next section.
-  #
-  # Once a Format object has been constructed and its properties have been
-  # set it can be passed as an argument to the worksheet write methods as
-  # follows:
-  #
-  #     worksheet.write( 0, 0, 'One', format )
-  #     worksheet.write_string( 1, 0, 'Two', format )
-  #     worksheet.write_number( 2, 0, 3, format )
-  #     worksheet.write_blank( 3, 0, format )
-  #
-  # Formats can also be passed to the worksheet set_row() and set_column()
-  # methods to define the default property for a row or column.
-  #
-  #     worksheet.set_row( 0, 15, format )
-  #     worksheet.set_column( 0, 0, 15, format )
-  #
-  # ===Format methods and Format properties
-  #
-  # The following table shows the Excel format categories, the formatting
-  # properties that can be applied and the equivalent object method:
-  #
-  #     Category   Description       Property        Method Name
-  #     --------   -----------       --------        -----------
-  #     Font       Font type         font            set_font()
-  #                Font size         size            set_size()
-  #                Font color        color           set_color()
-  #                Bold              bold            set_bold()
-  #                Italic            italic          set_italic()
-  #                Underline         underline       set_underline()
-  #                Strikeout         font_strikeout  set_font_strikeout()
-  #                Super/Subscript   font_script     set_font_script()
-  #                Outline           font_outline    set_font_outline()
-  #                Shadow            font_shadow     set_font_shadow()
-  #
-  #     Number     Numeric format    num_format      set_num_format()
-  #
-  #     Protection Lock cells        locked          set_locked()
-  #                Hide formulas     hidden          set_hidden()
-  #
-  #     Alignment  Horizontal align  align           set_align()
-  #                Vertical align    valign          set_align()
-  #                Rotation          rotation        set_rotation()
-  #                Text wrap         text_wrap       set_text_wrap()
-  #                Justify last      text_justlast   set_text_justlast()
-  #                Center across     center_across   set_center_across()
-  #                Indentation       indent          set_indent()
-  #                Shrink to fit     shrink          set_shrink()
-  #
-  #     Pattern    Cell pattern      pattern         set_pattern()
-  #                Background color  bg_color        set_bg_color()
-  #                Foreground color  fg_color        set_fg_color()
-  #
-  #     Border     Cell border       border          set_border()
-  #                Bottom border     bottom          set_bottom()
-  #                Top border        top             set_top()
-  #                Left border       left            set_left()
-  #                Right border      right           set_right()
-  #                Border color      border_color    set_border_color()
-  #                Bottom color      bottom_color    set_bottom_color()
-  #                Top color         top_color       set_top_color()
-  #                Left color        left_color      set_left_color()
-  #                Right color       right_color     set_right_color()
-  #
-  # There are two ways of setting Format properties: by using the object
-  # method interface or by setting the property directly. For example,
-  # a typical use of the method interface would be as follows:
-  #
-  #     format = workbook.add_format
-  #     format.set_bold
-  #     format.set_color( 'red' )
-  #
-  # By comparison the properties can be set directly by passing a hash
-  # of properties to the Format constructor:
-  #
-  #     format = workbook.add_format( :bold => 1, :color => 'red' )
-  #
-  # or after the Format has been constructed by means of the
-  # set_format_properties() method as follows:
-  #
-  #     format = workbook.add_format
-  #     format.set_format_properties( :bold => 1, :color => 'red' )
-  #
-  # You can also store the properties in one or more named hashes and pass
-  # them to the required method:
-  #
-  #     font = {
-  #         :font  => 'Arial',
-  #         :size  => 12,
-  #         :color => 'blue',
-  #         :bold  => 1
-  #     }
-  #
-  #     shading = {
-  #         :bg_color => 'green',
-  #         :pattern  => 1
-  #     }
-  #
-  #     format1 = workbook.add_format( font )           # Font only
-  #     format2 = workbook.add_format( font, shading )  # Font and shading
-  #
-  # The provision of two ways of setting properties might lead you to wonder
-  # which is the best way. The method mechanism may be better is you prefer
-  # setting properties via method calls (which the author did when the code
-  # was first written) otherwise passing properties to the constructor has
-  # proved to be a little more flexible and self documenting in practice.
-  # An additional advantage of working with property hashes is that it allows
-  # you to share formatting between workbook objects as shown in the example
-  # above.
-  #
-  # ===Working with formats
-  #
-  # The default format is Arial 10 with all other properties off.
-  #
-  # Each unique format in WriteXLSX must have a corresponding Format
-  # object. It isn't possible to use a Format with a write() method and then
-  # redefine the Format for use at a later stage. This is because a Format
-  # is applied to a cell not in its current state but in its final state.
-  # Consider the following example:
-  #
-  #     format = workbook.add_format
-  #     format.set_bold
-  #     format.set_color( 'red' )
-  #     worksheet.write( 'A1', 'Cell A1', format )
-  #     format.set_color( 'green' )
-  #     worksheet.write( 'B1', 'Cell B1', format )
-  #
-  # Cell A1 is assigned the Format format which is initially set to the colour
-  # red. However, the colour is subsequently set to green. When Excel displays
-  # Cell A1 it will display the final state of the Format which in this case
-  # will be the colour green.
-  #
-  # In general a method call without an argument will turn a property on,
-  # for example:
-  #
-  #     format1 = workbook.add_format
-  #     format1.set_bold         # Turns bold on
-  #     format1.set_bold( 1 )    # Also turns bold on
-  #     format1.set_bold( 0 )    # Turns bold off
-  #
   class Format
     include Writexlsx::Utility
 
-    attr_reader :xf_index, :dxf_index, :num_format   # :nodoc:
+    attr_reader :xf_index, :dxf_index, :num_format                                                 # :nodoc:
     attr_reader :underline, :font_script, :size, :theme, :font, :font_family, :hyperlink, :xf_id   # :nodoc:
-    attr_reader :diag_type, :diag_color, :font_only, :color, :color_indexed   # :nodoc:
-    attr_reader :left, :left_color, :right, :right_color, :top, :top_color, :bottom, :bottom_color   # :nodoc:
-    attr_reader :font_scheme   # :nodoc:
-    attr_accessor :num_format_index, :border_index, :font_index   # :nodoc:
-    attr_accessor :fill_index, :font_condense, :font_extend, :diag_border   # :nodoc:
-    attr_accessor :bg_color, :fg_color, :pattern   # :nodoc:
+    attr_reader :diag_type, :diag_color, :font_only, :color, :color_indexed                        # :nodoc:
+    attr_reader :left, :left_color, :right, :right_color, :top, :top_color, :bottom, :bottom_color # :nodoc:
+    attr_reader :font_scheme                                                                       # :nodoc:
+    attr_accessor :num_format_index, :border_index, :font_index                                    # :nodoc:
+    attr_accessor :fill_index, :font_condense, :font_extend, :diag_border                          # :nodoc:
+    attr_accessor :bg_color, :fg_color, :pattern                                                   # :nodoc:
 
-    attr_accessor :dxf_bg_color, :dxf_fg_color   # :nodoc:
-    attr_reader :rotation, :bold, :italic, :font_strikeout
+    attr_accessor :dxf_bg_color, :dxf_fg_color                                                     # :nodoc:
+    attr_reader :rotation, :bold, :italic, :font_strikeout                                         # :nodoc:
 
     def initialize(formats, params = {})   # :nodoc:
       @formats = formats
@@ -268,17 +111,6 @@ module Writexlsx
     #
     # Convert hashes of properties to method calls.
     #
-    # The properties of an existing Format object can be also be set by means
-    # of set_format_properties():
-    #
-    #     format = workbook.add_format
-    #     format.set_format_properties(:bold => 1, :color => 'red');
-    #
-    # However, this method is here mainly for legacy reasons. It is preferable
-    # to set the properties in the format constructor:
-    #
-    #     format = workbook.add_format(:bold => 1, :color => 'red');
-    #
     def set_format_properties(*properties)   # :nodoc:
       return if properties.empty?
       properties.each do |property|
@@ -747,7 +579,7 @@ module Writexlsx
         writer.empty_tag('sz', [ ['val', size] ]) unless dxf_format
 
         if theme == -1
-          # Ignore for excel2003_style
+        # Ignore for excel2003_style
         elsif ptrue?(theme)
           write_color(writer, 'theme', theme)
         elsif ptrue?(@color_indexed)
@@ -845,7 +677,7 @@ module Writexlsx
 
     def write_font_family_scheme(writer)
       if ptrue?(@font_family)
-          writer.empty_tag('family', [ ['val', @font_family] ])
+        writer.empty_tag('family', [ ['val', @font_family] ])
       end
 
       if ptrue?(@font_charset)

data/lib/write_xlsx/package/app.rb

@@ -7,6 +7,7 @@ module Writexlsx
     class App
 
       include Writexlsx::Utility
+      attr_writer :doc_security
 
       def initialize(workbook)
         @writer = Package::XMLWriterSimple.new
@@ -14,6 +15,7 @@ module Writexlsx
         @part_names    = []
         @heading_pairs = []
         @properties    = {}
+        @doc_security  = 0
       end
 
       def set_xml_writer(filename)
@@ -103,8 +105,8 @@ module Writexlsx
 
         schema   = 'http://schemas.openxmlformats.org/officeDocument/2006/'
         attributes = [
-            ['xmlns',     "#{schema}extended-properties"],
-            ['xmlns:vt',  "#{schema}docPropsVTypes"]
+          ['xmlns',     "#{schema}extended-properties"],
+          ['xmlns:vt',  "#{schema}docPropsVTypes"]
         ]
 
         @writer.tag_elements('Properties', attributes) { yield }
@@ -123,9 +125,7 @@ module Writexlsx
       # Write the <DocSecurity> element.
       #
       def write_doc_security
-        data = 0
-
-        @writer.data_element('DocSecurity', data)
+        @writer.data_element('DocSecurity', @doc_security)
       end
 
       #

data/lib/write_xlsx/package/button.rb

@@ -50,8 +50,8 @@ module Writexlsx
       # attributes for <v:fill> element.
       def fill_attributes
         [
-         ['color2',             'buttonFace [67]'],
-         ['o:detectmouseclick', 't']
+          ['color2',             'buttonFace [67]'],
+          ['o:detectmouseclick', 't']
         ]
       end
 
@@ -60,9 +60,9 @@ module Writexlsx
       #
       def write_rotation_lock
         attributes = [
-                      ['v:ext',    'edit'],
-                      ['rotation', 't']
-                     ]
+          ['v:ext',    'edit'],
+          ['rotation', 't']
+        ]
         @writer.empty_tag('o:lock', attributes)
       end
 
@@ -71,9 +71,9 @@ module Writexlsx
       #
       def write_textbox
         attributes = [
-                      ['style', 'mso-direction-alt:auto'],
-                      ['o:singleclick', 'f']
-                     ]
+          ['style', 'mso-direction-alt:auto'],
+          ['o:singleclick', 'f']
+        ]
 
         @writer.tag_elements('v:textbox', attributes) do
           # Write the div element.

data/lib/write_xlsx/package/comments.rb

@@ -177,8 +177,8 @@ module Writexlsx
       #
       def write_textbox
         attributes = [
-                      ['style', 'mso-direction-alt:auto']
-                     ]
+          ['style', 'mso-direction-alt:auto']
+        ]
 
         @writer.tag_elements('v:textbox', attributes) do
           # Write the div element.
@@ -191,8 +191,8 @@ module Writexlsx
       #
       def write_client_data
         attributes = [
-                      ['ObjectType', 'Note']
-                     ]
+          ['ObjectType', 'Note']
+        ]
 
         @writer.tag_elements('x:ClientData', attributes) do
           @writer.empty_tag('x:MoveWithCells')
@@ -225,10 +225,10 @@ module Writexlsx
         @author      = options[:author]
         @start_cell  = options[:start_cell]
         @start_row, @start_col = if @start_cell
-          substitute_cellref(@start_cell)
-        else
-          [ options[:start_row], options[:start_col] ]
-        end
+                                   substitute_cellref(@start_cell)
+                                 else
+                                   [ options[:start_row], options[:start_col] ]
+                                 end
         @visible     = options[:visible]
         @x_offset    = options[:x_offset]       || default_x_offset(col)
         @y_offset    = options[:y_offset]       || default_y_offset(row)

data/lib/write_xlsx/package/conditional_format.rb

@@ -397,14 +397,8 @@ module Writexlsx
       def range_start_cell_for_conditional_formatting(*args)  # :nodoc:
         row1, row2, col1, col2, user_range, param =
                                             row_col_param_for_conditional_formatting(*args)
-        # If the first and last cell are the same write a single cell.
-        if row1 == row2 && col1 == col2
-          range = xl_rowcol_to_cell(row1, col1)
-          @start_cell = range
-        else
-          range = xl_range(row1, row2, col1, col2)
-          @start_cell = xl_rowcol_to_cell(row1, col1)
-        end
+        range       = xl_range(row1, row2, col1, col2)
+        @start_cell = xl_rowcol_to_cell(row1, col1)
 
         # Override with user defined multiple range if provided.
         range = user_range if user_range

data/lib/write_xlsx/package/content_types.rb

@@ -165,9 +165,9 @@ module Writexlsx
       #
       def add_table_name(table_name)
         add_override(
-                     "/xl/tables/#{table_name}.xml",
-                     "#{App_document}spreadsheetml.table+xml"
-                     )
+          "/xl/tables/#{table_name}.xml",
+          "#{App_document}spreadsheetml.table+xml"
+        )
       end
 
       #
@@ -187,6 +187,15 @@ module Writexlsx
         add_override(custom, "#{App_document}custom-properties+xml")
       end
 
+      #
+      # Add the metadata file to the ContentTypes overrides.
+      #
+      def add_metadata
+        add_override(
+          "/xl/metadata.xml",
+          "#{App_document}spreadsheetml.sheetMetadata+xml"
+        )
+      end
 
       private
 
@@ -219,10 +228,10 @@ module Writexlsx
 
       def write_default_or_override(tag, param0, a)
         @writer.empty_tag(tag,
-          [
-            [param0, a[0]],
-            ['ContentType', a[1]]
-          ])
+                          [
+                            [param0, a[0]],
+                            ['ContentType', a[1]]
+                          ])
       end
 
       #
@@ -231,8 +240,8 @@ module Writexlsx
       def write_types
         xmlns = 'http://schemas.openxmlformats.org/package/2006/content-types'
         attributes = [
-                      ['xmlns', xmlns]
-                     ]
+          ['xmlns', xmlns]
+        ]
 
         @writer.tag_elements('Types', attributes) { yield }
       end

data/lib/write_xlsx/package/core.rb

@@ -68,11 +68,11 @@ module Writexlsx
         xmlns_xsi      = 'http://www.w3.org/2001/XMLSchema-instance'
 
         attributes = [
-            ['xmlns:cp',       xmlns_cp],
-            ['xmlns:dc',       xmlns_dc],
-            ['xmlns:dcterms',  xmlns_dcterms],
-            ['xmlns:dcmitype', xmlns_dcmitype],
-            ['xmlns:xsi',      xmlns_xsi]
+          ['xmlns:cp',       xmlns_cp],
+          ['xmlns:dc',       xmlns_dc],
+          ['xmlns:dcterms',  xmlns_dcterms],
+          ['xmlns:dcmitype', xmlns_dcmitype],
+          ['xmlns:xsi',      xmlns_xsi]
         ]
 
         @writer.tag_elements('cp:coreProperties', attributes) { yield }

data/lib/write_xlsx/package/custom.rb

@@ -47,7 +47,7 @@ module Writexlsx
           @properties.each do |property|
             # Write the property element.
             write_property(property)
-        end
+          end
         end
       end
 
@@ -112,7 +112,7 @@ module Writexlsx
         end
 
         @writer.data_element('vt:bool', data)
-    end
+      end
 
       #
       # Write the <vt:filetime> element.

data/lib/write_xlsx/package/metadata.rb

@@ -0,0 +1,159 @@
+# -*- coding: utf-8 -*-
+require 'write_xlsx/package/xml_writer_simple'
+require 'write_xlsx/utility'
+
+module Writexlsx
+  module Package
+    #
+    # Metadata - A class for writing the Excel XLSX metadata.xml file.
+    #
+    class Metadata
+      include Writexlsx::Utility
+
+      def initialize(workbook)
+        @writer = Package::XMLWriterSimple.new
+        @workbook      = workbook
+      end
+
+      def set_xml_writer(filename)
+        @writer.set_xml_writer(filename)
+      end
+
+      def assemble_xml_file
+        write_xml_declaration do
+          # Write the metadata element.
+          write_metadata
+          # Write the metadataTypes element.
+          write_metadata_types
+          # Write the futureMetadata element.
+          write_future_metadata
+          # Write the cellMetadata element.
+          write_cell_metadata
+          @writer.end_tag('metadata')
+        end
+      end
+
+      private
+
+      #
+      # Write the <metadata> element.
+      #
+      def write_metadata
+        xmlns = 'http://schemas.openxmlformats.org/spreadsheetml/2006/main'
+        xmlns_xda =
+          'http://schemas.microsoft.com/office/spreadsheetml/2017/dynamicarray'
+
+        attributes = [
+          ['xmlns',     xmlns],
+          ['xmlns:xda', xmlns_xda]
+        ]
+
+        @writer.start_tag('metadata', attributes)
+      end
+
+      #
+      # Write the <metadataTypes> element.
+      #
+      def write_metadata_types
+        attributes = [['count', 1 ]]
+
+        @writer.tag_elements('metadataTypes', attributes) do
+          # Write the metadataType element.
+          write_metadata_type
+        end
+      end
+
+      #
+      # Write the <metadataType> element.
+      #
+      def write_metadata_type
+        attributes = [
+          ['name',                'XLDAPR'],
+          ['minSupportedVersion', 120000],
+          ['copy',                1],
+          ['pasteAll',            1],
+          ['pasteValues',         1],
+          ['merge',               1],
+          ['splitFirst',          1],
+          ['rowColShift',         1],
+          ['clearFormats',        1],
+          ['clearComments',       1],
+          ['assign',              1],
+          ['coerce',              1],
+          ['cellMeta',            1]
+        ]
+
+        @writer.empty_tag('metadataType', attributes)
+      end
+
+      #
+      # Write the <futureMetadata> element.
+      #
+      def write_future_metadata
+        attributes = [
+          ['name',  'XLDAPR'],
+          ['count', 1]
+        ]
+
+        @writer.tag_elements('futureMetadata', attributes) do
+          @writer.tag_elements('bk') do
+            @writer.tag_elements('extLst') do
+              # Write the ext element.
+              write_ext();
+            end
+          end
+        end
+      end
+
+      #
+      # Write the <ext> element.
+      #
+      def write_ext
+        attributes = [[ 'uri', '{bdbb8cdc-fa1e-496e-a857-3c3f30c029c3}']]
+        @writer.tag_elements('ext', attributes) do
+          # Write the xda:dynamicArrayProperties element.
+          write_xda_dynamic_array_properties
+        end
+      end
+
+      #
+      # Write the <xda:dynamicArrayProperties> element.
+      #
+      def write_xda_dynamic_array_properties
+        attributes = [
+          ['fDynamic',   1],
+          ['fCollapsed', 0]
+        ]
+
+        @writer.empty_tag('xda:dynamicArrayProperties', attributes)
+      end
+
+      #
+      # Write the <cellMetadata> element.
+      #
+      def write_cell_metadata
+        count = 1
+
+        attributes = [['count', count]]
+
+        @writer.tag_elements('cellMetadata', attributes) do
+          @writer.tag_elements('bk') do
+            # Write the rc element.
+            write_rc
+          end
+        end
+      end
+
+      #
+      # Write the <rc> element.
+      #
+      def write_rc
+        attributes = [
+          ['t', 1],
+          ['v', 0]
+        ]
+        @writer.empty_tag('rc', attributes)
+      end
+    end
+  end
+end

data/lib/write_xlsx/package/packager.rb

@@ -6,6 +6,7 @@ require 'write_xlsx/package/comments'
 require 'write_xlsx/package/content_types'
 require 'write_xlsx/package/core'
 require 'write_xlsx/package/custom'
+require 'write_xlsx/package/metadata'
 require 'write_xlsx/package/relationships'
 require 'write_xlsx/package/shared_strings'
 require 'write_xlsx/package/styles'
@@ -56,6 +57,7 @@ module Writexlsx
         write_drawing_rels_files
         add_image_files
         add_vba_project
+        write_metadata_file
       end
 
       private
@@ -155,6 +157,7 @@ module Writexlsx
         app.add_named_ranges_parts
 
         app.set_properties(@workbook.doc_properties)
+        app.doc_security = @workbook.read_only
 
         FileUtils.mkdir_p("#{@package_dir}/docProps")
         app.set_xml_writer("#{@package_dir}/docProps/app.xml")
@@ -174,6 +177,20 @@ module Writexlsx
         core.assemble_xml_file
       end
 
+      #
+      # Write the metadata.xml file.
+      #
+      def write_metadata_file
+        metadata = Package::Metadata.new(@workbook)
+
+        return unless @workbook.has_metadata?
+
+        FileUtils.mkdir_p("#{@package_dir}/xl")
+
+        metadata.set_xml_writer( "#{@package_dir}/xl/metadata.xml")
+        metadata.assemble_xml_file
+      end
+
       #
       # Write the custom.xml file.
       #
@@ -210,6 +227,8 @@ module Writexlsx
         content.add_vba_project if @workbook.vba_project
         # Add the custom properties if present.
         content.add_custom_properties unless @workbook.custom_properties.empty?
+        # Add the metadata file if present.
+        content.add_metadata if @workbook.has_metadata?
 
         content.set_xml_writer("#{@package_dir}/[Content_Types].xml")
         content.assemble_xml_file
@@ -304,6 +323,9 @@ module Writexlsx
           rels.add_ms_package_relationship('/vbaProject', 'vbaProject.bin')
         end
 
+        # Add the metadata file if required.
+        rels.add_document_relationship('/sheetMetadata', 'metadata.xml') if @workbook.has_metadata?
+
         rels.set_xml_writer("#{@package_dir}/xl/_rels/workbook.xml.rels")
         rels.assemble_xml_file
       end