prawn-extras 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0674038f691b219cab7a8e3974ff74d97bba0c95
-  data.tar.gz: 996793d3a1e293886c9553b5cdbb6205ada35039
+  metadata.gz: d8ee555f97717cd38b126129b42cf05ca6303bc1
+  data.tar.gz: 372404b0fedfa539b618002bef860e9f8a596feb
 SHA512:
-  metadata.gz: 5f4dc02abfc5e4163615539cda0f3423b3f1dfb2ac14dfd9449e0a3ac5f24697cb2c78a91ec7e4b6bd8eeec1e4801a95d12bfeae7c9ed0e053ba13611b506749
-  data.tar.gz: 977b5273cd914f7bdaa72a502afeaf5e09e1e466879d7f4cabe946fc7d6c2d78affea2046de91d74d762d75b9230f04fdce905bef1a7983dc923e54214216f04
+  metadata.gz: fa74c11b88d7359b56aa8e1d11c7aa1046c9d43fff88a3b09e553b9ac63aa95e9329e46e9decdad3df60c4de190a3f311660966dfab32b76f81a938c644e085a
+  data.tar.gz: c9997bc25526083a1e41c9edda945c374ce8a43bf8b30be9f97fde1cf33adbac46d427fc8fb0262b46ca9cc81324e8fe172ca9db6bc2366da9bc117adecc3240

data/lib/prawn/extras/box.rb

@@ -3,42 +3,70 @@ module Prawn
     module Box
       delegate :top_left, :width, :height, to: :bounds
 
+      # Returns the most recent created box which was created using the "box"
+      # method. It will be nil if no boxes were created or if they were all
+      # created with the :dont_track option set to true.
       def last_created_box
         @last_created_box ||= nil
       end
 
-      # Retorna um valor absoluto de width correspondente a porcentagem indicada,
-      # nos limites do relatório, que é entre '0' e 'bounds.width'.
-      # O parâmetro value deve ser um valor entre 0 e 100.
-      # Ex: chamando percent_w(50) fora de um bounding_box: 50% da width da página
-      # Ex: chamando percent_w(9) em um bounding_box: 9% da width do bounding_box
+      # Translates a percentage value to an absolute width value, within the
+      # limits of the current bounds (between 0 and "bounds.width").
+      #
+      # The value parameter must be an integer between 0 and 100. If a value
+      # outside these bounds is provided, it will be clamped.
+      #
       def percent_w(value)
-        # Faz o clamp no valor para garantir que ele fique entre 0% e 100%
-        clamped_value = [0, value, 100].sort[1]
-        bounds.width * (clamped_value / 100.0)
+        bounds.width * (clamp_percentage(value) / 100.0)
       end
 
-      # Retorna um valor absoluto de height correspondente a porcentagem indicada,
-      # nos limites do relatório, que é entre 'bounds.height' e '0'.
-      # O parâmetro value deve ser um valor entre 0 e 100.
-      # Ex: chamando percent_h(50) fora de um bounding_box: 50% da height da página
-      # Ex: chamando percent_h(9) em um bounding_box: 9% da height do bounding_box
+      # Translates a percentage value to an absolute width value, within the
+      # limits of the current bounds (between "bounds.height" and 0).
+      #
+      # The value parameter must be an integer between 0 and 100. If a value
+      # outside these bounds is provided, it will be clamped.
+      #
       def percent_h(value)
-        # Faz o clamp no valor para garantir que ele fique entre 0% e 100%
-        clamped_value = [0, value, 100].sort[1]
-        bounds.height * (clamped_value / 100.0)
+        bounds.height * (clamp_percentage(value) / 100.0)
       end
 
-      # Retorna um valor absoluto de height correspondente à height restante abaixo
-      # de base_height. base_height deve ser um objeto do tipo Bounds
+      # Returns the absolute height value remaining to the bottom of the
+      # current bounds, relative to the provided base_height.
+      #
+      # The base_height parameter must be a Prawn::Document::BoundingBox object,
+      # and the remaining height is calculated from the bottom side of this
+      # object.
+      #
       def remaining_height(base_height)
         base_height.anchor[1] - bounds.anchor[1]
       end
 
-      # Cria um bounding_box. Esse método é basicamente um alias de bounding_box,
-      # exceto que oferece mais flexibilidade e facilidade na entrada dos
-      # parâmetros, permitindo expressar width e height como porcentagens, ex:
-      # box(top_left, '25%', '100%') {}
+      # This method is mostly an alias to Prawn's default bounding_box method.
+      # It passes parameters in a differnt way, but also includes the option to
+      # define a padding.
+      #
+      # The padding may be a single integer value applied to all sides, or four
+      # separate values passed as an array, applied clockwise starting from top.
+      #
+      # It also tracks by default which was the last box created (if using this
+      # method), so that the next box may be positioned relative to the previous
+      # one without the need to assign variables This can be disabled by
+      # setting the option :dont_track to any truthy value.
+      #
+      # The size parameters can be expressed either as points, which is the
+      # default, but also in percentages, both "global" and "local". To use
+      # percentages, the value must be passed as a String, with the % character
+      # at the end. The box will be created using "xx%" of the total available
+      # space of the current bounds.
+      #
+      # There's also the option to specify the width and height in percentages
+      # relative to the remaining space left. For example, if a box is created
+      # with its left side at 300, and the page is 600 wide, there's only 50% of
+      # space left, so width may only be 50% or lower. However, if width is
+      # passed as "100%l", with an l at the end, it will occupy "100%" of the
+      # remaining available space. This is useful for when a box must fill the
+      # remaining of the page but you don't know exactly where is the cursor.
+      #
       def box(position, width, height, options = {})
         size = build_size_options(position, width, height)
         box = bounding_box(position, size) do
@@ -48,46 +76,71 @@ module Prawn
         box
       end
 
-      # Cria um novo bounding_box posicionado à direita do bounding_box pai.
-      # O comportamento é o mesmo de chamar 'bounding_box', e aceita um bloco.
-      # Este método retorna o bounding_box criado, para ser referenciado depois.
-      # O parâmetro espaçamento é opcional e indica o tamanho do espaço entre a
-      # direita do pai e a esquerda do novo bounding_box.
+      # Sets a padding inside the current bounds. It essentially creates a new
+      # bounding_box centered on the current one, smaller in size, to simulate
+      # padding.
+      #
+      # "values" may be a single integer value applied to all sides, or four
+      # separate values passed as an array, applied clockwise starting from top.
+      #
+      def padding(values)
+        values = build_padding_values(values)
+        position = padding_position(values)
+        width, height = padding_size(values)
+        bounding_box(position, width: width, height: height) { yield }
+      end
+
+      # Defines a box directly to the right of "origin_box". The position is
+      # calculated relative to "origin_box", all other parameters are the same
+      # as in the "box" method above.
+      #
+      # An additional :gutter option may be set. This will add the specified
+      # value as space between "origin_box" and the new box.
+      #
       def box_beside(origin_box, width, height, options = {}, &block)
-        posicao = position_beside(origin_box, options[:gutter] || 0)
-        box(posicao, width, height, options, &block)
+        position = position_beside(origin_box, options[:gutter] || 0)
+        box(position, width, height, options, &block)
       end
 
-      # Cria um novo bounding_box posicionado à direita do último box criado.
-      # Funciona como o método acima box_a_direita_de, exceto que ele pega o box
-      # automaticamente. Caso não exista um último box criado (esse foi o primeiro),
-      # ele irá posicionar o box no top_left.
+      # Defines a box directly to the right of the most recent previously
+      # created box. The position is calculated relative to it, all other
+      # parameters are the same as in the "box" method above.
+      #
+      # An additional :gutter option may be set. This will add the specified
+      # value as space between the previous and the new box.
+      #
       def box_beside_previous(width, height, options = {}, &block)
         box_beside(last_created_box, width, height, options, &block)
       end
 
-      # Cria um novo bounding_box posicionado abaixo do bounding_box pai.
-      # O comportamento é o mesmo de chamar 'bounding_box', e aceita um bloco.
-      # Este método retorna o bounding_box criado, para ser referenciado depois.
-      # O parâmetro espaçamento é opcional e indica o tamanho do espaço entre o
-      # limite inferior do pai e o topo do novo bounding_box.
+      # Defines a box directly below "origin_box". The position is calculated
+      # relative to "origin_box", all other parameters are the same as in the
+      # "box" method above.
+      #
+      # An additional :gutter option may be set. This will add the specified
+      # value as space between "origin_box" and the new box.
+      #
       def box_below(origin_box, width, height, options = {}, &block)
-        posicao = position_below(origin_box, options[:gutter] || 0)
-        box(posicao, width, height, options, &block)
+        position = position_below(origin_box, options[:gutter] || 0)
+        box(position, width, height, options, &block)
       end
 
-      # Cria um novo bounding_box posicionado abaixo do último box criado.
-      # Funciona como o método acima box_abaixo_de, exceto que ele pega o box
-      # automaticamente. Caso não exista um último box criado (esse foi o primeiro),
-      # ele irá posicionar o box no top_left.
+      # Defines a box directly below the most recent previously created box.
+      # The position is calculated relative to it, all other parameters are the
+      # same as in the "box" method above.
+      #
+      # An additional :gutter option may be set. This will add the specified
+      # value as space between the previous and the new box.
+      #
       def box_below_previous(width, height, opcoes = {}, &block)
         box_below(last_created_box, width, height, opcoes, &block)
       end
 
-      # Retorna uma posição (para um novo bounding_box), imediatamente à direita
-      # de um bounding_box pai, alinhado verticalmente ao topo do pai.
-      # O parâmetro espaçamento é opcional e indica o tamanho do espaço entre a
-      # direita do pai e a esquerda dessa nova posição.
+      # Returns a two element array defining a position that is directly to the
+      # right of "origin_box". An optional gutter may be passed, and it will
+      # be converted to horizontal space between the "origin_box" and this new
+      # position.
+      #
       def position_beside(origin_box, gutter = 0)
         correct_origin = Array(origin_box).first
         return top_left if origin_box.nil?
@@ -95,10 +148,11 @@ module Prawn
         sum_dimensions(correct_origin.absolute_top_right, diff)
       end
 
-      # Retorna uma posição (para um novo bounding_box), imediatamente abaixo de um
-      # bounding_box pai, alinhado horizontalmente com a esquerda do pai.
-      # O parâmetro espaçamento é opcional e indica o tamanho do espaço entre o
-      # limite inferior do pai e o topo dessa nova posição.
+      # Returns a two element array defining a position that is directly below
+      # "origin_box". An optional gutter may be passed, and it will be
+      # converted to vertical space between the "origin_box" and this new
+      # position.
+      #
       def position_below(origin_box, gutter = 0)
         correct_origin = Array(origin_box).first
         return top_left if correct_origin.nil?
@@ -106,45 +160,20 @@ module Prawn
         sum_dimensions(correct_origin.absolute_bottom_left, diff)
       end
 
-      # Cria um bounding box para agir como se fosse um padding (igual ao do CSS).
-      # Tamanho pode ser um número, que será aplicado aos quatro lados, ou pode ser
-      # um array com 4 valores, para o padding de cima, direita, baixo e esquerda,
-      # nessa ordem.
-      def padding(values)
-        values = build_padding_values(values)
-        posicao = padding_position(values)
-        width, height = padding_size(values)
-        bounding_box(posicao, width: width, height: height) { yield }
-      end
-
       protected
 
-      # Checa se o valor da width é uma string e contém o caractere %. Se tiver,
-      # fazer o cálculo correto da width, senão, retornar a mesma width.
-      # O cálculo da width é relativo ao espaço horizontal global. Para fazer ele
-      # ser relativo ao espaço restante, basta adicionar um 'l' depois de '%'.
-      # Espaço restante é o espaço que sobrou após a posição passada no parâmetro,
-      # ou seja, se o pai ocupar metade da width da página, o valor em porcentagem
-      # será relativo aos 50% livres, e não à width total da página.
       def t_width(position, width)
         return width unless width.to_s.include? '%'
-        valor = percent_w(width.to_f) # Valor percentual global
-        return valor unless width.to_s.include? 'l' # 'l' de 'local'
-        valor * (1.0 - (position.first / bounds.width)) # Valor percentual relativo
-      end
-
-      # Checa se o valor da height é uma string e contém o caractere %. Se tiver,
-      # fazer o cálculo correto da width, senão, retornar a mesma height.
-      # O cálculo da height é relativo ao espaço vertical global. Para fazer ele
-      # ser relativo ao espaço restante, basta adicionar um 'l' depois de '%'.
-      # Espaço restante é o espaço que sobrou após a posição passada no parâmetro,
-      # ou seja, se o pai ocupar metade da height da página, o valor em porcentagem
-      # será relativo aos 50% livres, e não à height total da página.
+        valor = percent_w(width.to_f) # Global percentage
+        return valor unless width.to_s.include? 'l'
+        valor * (1.0 - (position.first / bounds.width)) # Local percentage
+      end
+
       def t_height(position, height)
         return height unless height.to_s.include? '%'
-        valor = percent_h(height.to_f) # Valor percentual global
-        return valor unless height.to_s.include? 'l' # 'l' de 'local'
-        valor * (position.last / bounds.height) # Valor percentual relativo
+        valor = percent_h(height.to_f) # Global percentage
+        return valor unless height.to_s.include? 'l'
+        valor * (position.last / bounds.height) # Local percentage
       end
 
       def build_padding_values(values)
@@ -169,6 +198,10 @@ module Prawn
       def build_size_options(position, width, height)
         { width: t_width(position, width), height: t_height(position, height) }
       end
+
+      def clamp_percentage(value)
+        [0, value.to_i, 100].sort[1]
+      end
     end
   end
 end

data/lib/prawn/extras/dynamic_repeater.rb

@@ -30,9 +30,8 @@ module Prawn
     # ==========================================================================
     module DynamicRepeater
       # Saves a named value for a specific page of the generated PDF. This will
-      # save the value for the specified page down to the first page of the
-      # document (page 1), or until there's already another value saved for a
-      # previous page.
+      # save the value for the specified page and also fill any page gaps with
+      # the latest previous value submitted.
       #
       # Example:
       #
@@ -43,10 +42,11 @@ module Prawn
       # override these values.
       #
       def store_value_in_page(key, value, page = page_number)
-        page.downto(1).each do |page_index|
-          next if repeater_values(key).keys.include?[page_index]
-          repeater_values(key)[page_index] = value
+        latest_value = value_in_page(key, page) # Gets the last value submitted
+        (page - 1).downto(max_index(page)).each do |page_index|
+          repeater_values(key)[page_index] = latest_value
         end
+        repeater_values(key)[page] = value
       end
 
       # Returns the value for a key at a specific page. If the page is greater
@@ -66,13 +66,13 @@ module Prawn
       # value_in_page(:name, -1) => ""
       #
       def value_in_page(key, page, default_value = '')
-        repeater_values(key)[[page, max_index(key).min]] || default_value
+        repeater_values(key)[[page, max_index(key)].min] || default_value
       end
 
       private
 
       def max_index(key)
-        repeater_values(key).keys.max
+        repeater_values(key).keys.max.to_i
       end
 
       def repeater_values(key)

data/lib/prawn/extras/version.rb

@@ -1,5 +1,5 @@
 module Prawn
   module Extras
-    VERSION = '0.1.0'.freeze
+    VERSION = '0.1.1'.freeze
   end
 end

metadata

@@ -1,29 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: prawn-extras
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Rodrigo Castro
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-12-09 00:00:00.000000000 Z
+date: 2017-02-06 00:00:00.000000000 Z
 dependencies:
-- !ruby/object:Gem::Dependency
-  name: rails
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 4.2.0
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 4.2.0
 - !ruby/object:Gem::Dependency
   name: prawn
   requirement: !ruby/object:Gem::Requirement
@@ -89,7 +75,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.5.1
+rubygems_version: 2.4.6
 signing_key: 
 specification_version: 4
 summary: Extra functions for the great Prawn gem