article_json 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0b9a465102850e508e0122f49d1a07dc2bb2f557
-  data.tar.gz: 1a8245e0c0c8e7d1d12cfc0fb3935ca339faf687
+  metadata.gz: a3ea32ede59212aaedc27f897922412e70bc1545
+  data.tar.gz: e95562bb9e98e42707a6f9a02f20595faf858d4b
 SHA512:
-  metadata.gz: '0825cb1ba5323f0fc31472af514c1606720e4c3ce22011dd61da46309c6eb9bd3997c9faf32e6cca995c7cc9069caf17c3dd22bc105b10add4040a995d8d1675'
-  data.tar.gz: 738b909324f0a12a1a9a27efcbdb58b6e7f496790b2a5f99e153c4424253c2c79be7af14b4824ddf48b3865b1e32934755272edeee5569fba1d31df45b000e18
+  metadata.gz: a8c1fa89e91fdb144be43cba372c2c59b96f9536031f4302eecd172593e0d0be0e4eb4310183e79beebbb4155d644a251a9c6663178cc23165337cfd97953570
+  data.tar.gz: b24715ad37d108a683a3baecc09acc586be9779c48d46c6007df141c45490afaa766f612d4f32c2ee894a45f5b0c4e99d8b1d38f9dc18e8fbcfc5f1cca5bbb6b

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.3.0 - 2017/11/21
+In this third bigger release we **added support**:
+- For exporting articles in the Facebook Instant Article format
+- For exporting articles in a plain text format
+- To all exporters for `caption` elements that are an empty array
+- For `[no-caption]` text in _Google Documents_ below elements (like images or embed URLs), this now returns empty caption for element
+
+**Improvements** were done regarding additional element placement:
+- Rework algorithm to place additional elements to better support placing a single element
+- Improve behavior of multiple calls to `Article#place_additional_elements`
+
+One potentially **breaking change** was added:
+- Remove deprecated `#register_html_element_exporter`, use `#register_element_exporters` instead
+
+**Fixes**:
+- Fix AMP export of Twitter tweets
+
 ## 0.2.1 - 2017/11/08
 **Fix**: Handle non-successful OEmbed responses by rendering message
 

data/README.md

@@ -32,6 +32,12 @@ puts article.to_amp
 # get javascript libraries needed for the AMP article
 puts article.amp_exporter.amp_libraries
 
+# export article as Facebook Instant Article HTML
+puts article.to_facebook_instant_article
+
+# export article as plain text
+puts article.to_plain_text
+
 # export article as JSON
 puts article.to_json
 ```
@@ -77,9 +83,10 @@ ArticleJSON.configure do |config|
     image: ArticleJSON::Export::HTML::Elements::ScaledImage
   )
   
-  # It works the same way for custom AMP exporters:
+  # It works the same way for custom AMP, FacebookInstantArticle, or 
+  # PlainText exporters:
   config.register_element_exporters(
-    :amp,
+    :amp, # Or change this for `:facebook_instant_article` or `:plain_text`
     image: ArticleJSON::Export::AMP::Elements::ScaledImage
   ) 
 end
@@ -201,6 +208,31 @@ An example of
 the AMP HTML export for the parsed reference document can be found 
 [here](https://github.com/Devex/article_json/blob/master/spec/fixtures/reference_document_exported.amp.html).
 
+### Facebook Instant Articles
+The `FacebookInstantArticle` exporter generates a custom HTML string for a list
+of elements. An example of the Facebook Instant Article export for the parsed
+reference document can be found 
+[here](https://github.com/Devex/article_json/blob/master/spec/fixtures/reference_document_exported.html).
+
+To learn more about the Facebook Instant Article HTML format see have a look at
+the [Facebook Developer Documentation](https://developers.facebook.com/docs/instant-articles/guides/format-overview).
+
+### Plain Text
+As the name suggests, this exporter generates a plain text version of the article.
+Rich text elements like images, embeds or even text boxes are not being rendered.
+
+The reference document rendered as plain text can be found
+[here](https://github.com/Devex/article_json/blob/master/spec/fixtures/reference_document_exported.txt).
+
+Usage:
+```ruby
+# Create your article instance as you normally do
+article = ArticleJSON::Article.from_hash(parsed_json)
+
+# Then simply call `#to_plain_text` on it
+article.to_plain_text 
+```
+
 ## Contributing
 - Fork this repository
 - Implement your feature or fix including Tests

data/lib/article_json/article.rb

@@ -1,10 +1,26 @@
 module ArticleJSON
   class Article
-    attr_reader :elements
+    attr_reader :article_elements, :additional_elements
 
     # @param [Array[ArticleJSON::Elements::Base]] elements
     def initialize(elements)
-      @elements = elements
+      @article_elements = elements
+      @additional_elements = []
+    end
+
+    # All elements of this article with optional additional elements placed in
+    # between
+    # @return [Array[ArticleJSON::Elements::Base]]
+    def elements
+      @elements ||= begin
+        if @additional_elements.any?
+          ArticleJSON::Utils::AdditionalElementPlacer
+            .new(@article_elements, @additional_elements)
+            .merge_elements
+        else
+          @article_elements
+        end
+      end
     end
 
     # Hash representation of the article
@@ -12,7 +28,7 @@ module ArticleJSON
     def to_h
       {
         article_json_version: VERSION,
-        content: @elements.map(&:to_h),
+        content: elements.map(&:to_h),
       }
     end
 
@@ -25,7 +41,7 @@ module ArticleJSON
     # Exporter instance for HTML
     # @return [ArticleJSON::Export::HTML::Exporter]
     def html_exporter
-      @html_exporter = ArticleJSON::Export::HTML::Exporter.new(@elements)
+      ArticleJSON::Export::HTML::Exporter.new(elements)
     end
 
     # HTML export of the article
@@ -37,7 +53,7 @@ module ArticleJSON
     # Exporter instance for AMP
     # @return [ArticleJSON::Export::AMP::Exporter]
     def amp_exporter
-      ArticleJSON::Export::AMP::Exporter.new(@elements)
+      ArticleJSON::Export::AMP::Exporter.new(elements)
     end
 
     # AMP export of the article
@@ -46,15 +62,39 @@ module ArticleJSON
       amp_exporter.html
     end
 
+    # Exporter instance for FacebookInstantArticle
+    # @return [ArticleJSON::Export::FacebookInstantArticle::Exporter]
+    def facebook_instant_article_exporter
+      ArticleJSON::Export::FacebookInstantArticle::Exporter.new(elements)
+    end
+
+    # FacebookInstantArticle export of the article
+    # @return [String]
+    def to_facebook_instant_article
+      facebook_instant_article_exporter.html
+    end
+
+    # Exporter instance for plain text
+    # @return [ArticleJSON::Export::PlainText::Exporter]
+    def plain_text_exporter
+      ArticleJSON::Export::PlainText::Exporter.new(elements)
+    end
+
+    # Plain text export of the article
+    # @return [String]
+    def to_plain_text
+      plain_text_exporter.text
+    end
+
     # Distribute passed elements evenly throughout the article. All passed
     # elements need to have an exporter to be represented in the rendered
-    # article.
+    # article. If the method is called multiple times, the order of additional
+    # elements is maintained.
     # @param [Object] additional_elements
     def place_additional_elements(additional_elements)
-      @elements =
-        ArticleJSON::Utils::AdditionalElementPlacer
-          .new(self, additional_elements)
-          .merge_elements
+      # Reset the `#elements` method memoization
+      @elements = nil
+      @additional_elements.concat(additional_elements)
     end
 
     class << self

data/lib/article_json/configuration.rb

@@ -21,40 +21,19 @@ module ArticleJSON
       @custom_element_exporters = {}
     end
 
-    # Register a new HTML element exporter or overwrite existing ones.
-    # @param [Symbol] type
-    # @param [Class] klass
-    # @deprecated Use `#register_element_exporters_for(:html, ...)` instead
-    def register_html_element_exporter(type, klass)
-      register_element_exporters(:html, type => klass)
-    end
-
-    # Return custom HTML exporters
-    # @return [Hash[Symbol => Class]]
-    # @deprecated use `#exporter_for` instead
-    def html_element_exporters
-      @custom_element_exporters[:html] || {}
-    end
-
-    # Set custom HTML exporters
-    # @param [Hash[Symbol => Class]] value
-    # @deprecated use `#register_element_exporters(:html, ...)` instead
-    def html_element_exporters=(value)
-      @custom_element_exporters[:html] = value
-    end
-
     # Register new element exporters or overwrite existing ones for a given
     # exporter type.
     # Usage example:
     #  register_element_exporters(:html,
-    #                                 image: MyImageExporter,
-    #                                 advertisement: MyAdExporter)
+    #                             image: MyImageExporter,
+    #                             advertisement: MyAdExporter)
     # @param [Symbol] exporter
     # @param [Hash[Symbol => Class]] type_class_mapping
     def register_element_exporters(exporter, type_class_mapping)
-      unless %i(html amp).include?(exporter)
-        raise ArgumentError, '`exporter` needs to be either `:html` or `:amp` '\
-                             "but is `#{exporter.inspect}`"
+      valid_exporters = %i(html amp facebook_instant_article plain_text)
+      unless valid_exporters.include?(exporter)
+        raise ArgumentError, '`exporter` needs to be one of ' \
+                             "#{valid_exporters} but is `#{exporter.inspect}`"
       end
       if !type_class_mapping.is_a?(Hash) ||
           type_class_mapping.keys.any? { |key| !key.is_a? Symbol } ||

data/lib/article_json/elements/paragraph.rb

@@ -32,6 +32,16 @@ module ArticleJSON
         end
       end
 
+      # Return the sum of all characters within the content's text elements
+      # @return [Integer]
+      def length
+        return 0 if empty?
+        @content.reduce(0) do |sum, element|
+          sum + (element.respond_to?(:length) ? element.length : 0)
+        end
+      end
+      alias size length
+
       class << self
         # Create a paragraph element from Hash
         # @return [ArticleJSON::Elements::Paragraph]

data/lib/article_json/elements/text.rb

@@ -40,6 +40,14 @@ module ArticleJSON
         empty? || content.gsub(/[\s\u00A0]/, '').empty?
       end
 
+      # Get the number of characters contained by this text element
+      # @return [Integer]
+      def length
+        return 0 if blank?
+        content.length
+      end
+      alias size length
+
       class << self
         # Create a text element from Hash
         # @return [ArticleJSON::Elements::Text]

data/lib/article_json/export/amp/elements/embed.rb

@@ -55,8 +55,11 @@ module ArticleJSON
 
           # @return [Nokogiri::XML::Element]
           def tweet_node
+            # The embed_id of a tweet is stored as "<handle>/<tweet_id>" but
+            # the `amp-twitter` tag only takes the `tweet_id` part
+            tweet_id = @element.embed_id.split('/').last
             create_element('amp-twitter',
-                           'data-tweetid' => @element.embed_id,
+                           'data-tweetid': tweet_id,
                            width: default_width,
                            height: default_height)
           end

data/lib/article_json/export/common/elements/base.rb

@@ -0,0 +1,84 @@
+module ArticleJSON
+  module Export
+    module Common
+      module Elements
+        module Base
+          # Extend `base` class with `ClassMethods` upon inclusion
+          def self.included(base)
+            base.extend ClassMethods
+          end
+
+          # @param [ArticleJSON::Elements::Base] element
+          def initialize(element)
+            @element = element
+          end
+
+          # Export the given element. Dynamically looks up the right
+          # export-element-class, instantiates it and then calls the `#export`
+          # method.
+          # @return [Object]
+          def export
+            exporter.export unless exporter.nil?
+          end
+
+          private
+
+          # Get the right exporter class for the given element
+          # @return [ArticleJSON::Export::Common::Elements::Base]
+          def exporter
+            @exporter ||=
+              self.class.base_class? ? self.class.build(@element) : self
+          end
+
+          # Return the base class for the current element instance
+          # @return [ArticleJSON::Export::Common::Elements::Base]
+          def base_class
+            self.class.namespace::Base
+          end
+
+          module ClassMethods
+            # Instantiate the correct sub class for a given element
+            # @param [ArticleJSON::Elements::Base] element
+            # @return [ArticleJSON::Export::Common::Elements::Base]
+            def build(element)
+              klass = exporter_by_type(element.type)
+              klass.new(element) unless klass.nil?
+            end
+
+            # Look up the correct exporter class based on the element type
+            # @param [Symbol] type
+            # @return [ArticleJSON::Export::Common::Elements::Base]
+            def exporter_by_type(type)
+              key = type.to_sym
+              custom_class = ArticleJSON.configuration.element_exporter_for(
+                export_format, key
+              )
+              custom_class || default_exporter_mapping[key]
+            end
+
+            # Check if the current class is the base class a child class.
+            # Since this common module is in a different namespace, a simple
+            # `self == Base` check does not work.
+            # @return [Boolean]
+            def base_class?
+              self == namespace::Base
+            end
+
+            def default_exporter_mapping
+              {
+                text: namespace::Text,
+                paragraph: namespace::Paragraph,
+                heading: namespace::Heading,
+                list: namespace::List,
+                quote: namespace::Quote,
+                image: namespace::Image,
+                embed: namespace::Embed,
+                text_box: namespace::TextBox,
+              }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/article_json/export/common/html/elements/base.rb

@@ -4,22 +4,9 @@ module ArticleJSON
       module HTML
         module Elements
           module Base
-            # Extend `base` class with `ClassMethods` upon inclusion
+            # Also include the generic base element concern
             def self.included(base)
-              base.extend ClassMethods
-            end
-
-            # @param [ArticleJSON::Elements::Base] element
-            def initialize(element)
-              @element = element
-            end
-
-            # Export a HTML node out of the given element
-            # Dynamically looks up the right export-element-class, instantiates it
-            # and then calls the #build method.
-            # @return [Nokogiri::XML::NodeSet]
-            def export
-              exporter.export unless exporter.nil?
+              base.include ArticleJSON::Export::Common::Elements::Base
             end
 
             private
@@ -48,61 +35,6 @@ module ArticleJSON
                 elements.each { |element| node_set.push(element) }
               end
             end
-
-            # Get the right exporter class for the given element
-            # @return [ArticleJSON::Export::Common::HTML::Elements::Base]
-            def exporter
-              @exporter ||=
-                self.class.base_class? ? self.class.build(@element) : self
-            end
-
-            # Return the base class for the current element instance
-            # @return [ArticleJSON::Export::Common::HTML::Elements::Base]
-            def base_class
-              self.class.namespace::Base
-            end
-
-            module ClassMethods
-              # Instantiate the correct sub class for a given element
-              # @param [ArticleJSON::Elements::Base] element
-              # @return [ArticleJSON::Export::Common::HTML::Elements::Base]
-              def build(element)
-                klass = exporter_by_type(element.type)
-                klass.new(element) unless klass.nil?
-              end
-
-              # Look up the correct exporter class based on the element type
-              # @param [Symbol] type
-              # @return [ArticleJSON::Export::Common::HTML::Elements::Base]
-              def exporter_by_type(type)
-                key = type.to_sym
-                custom_class = ArticleJSON.configuration.element_exporter_for(
-                  export_format, key
-                )
-                custom_class || default_exporter_mapping[key]
-              end
-
-              # Check if the current class is the base class a child class.
-              # Since this common module is in a different namespace, a simple
-              # `self == Base` check does not work.
-              # @return [Boolean]
-              def base_class?
-                self == namespace::Base
-              end
-
-              def default_exporter_mapping
-                {
-                  text: namespace::Text,
-                  paragraph: namespace::Paragraph,
-                  heading: namespace::Heading,
-                  list: namespace::List,
-                  quote: namespace::Quote,
-                  image: namespace::Image,
-                  embed: namespace::Embed,
-                  text_box: namespace::TextBox,
-                }
-              end
-            end
           end
         end
       end

data/lib/article_json/export/common/html/elements/embed.rb

@@ -11,14 +11,17 @@ module ArticleJSON
             def export
               create_element(:figure) do |figure|
                 figure.add_child(embed_node)
-                figure.add_child(caption_node(:figcaption))
+                if @element.caption&.any?
+                  figure.add_child(caption_node(:figcaption))
+                end
               end
             end
 
             private
 
             def embed_node
-              create_element(:div, class: 'embed') do |div|
+              type = @element.embed_type.to_s.tr('_','-')
+              create_element(:div, class: "embed #{type}") do |div|
                 div.add_child(embedded_object)
               end
             end

data/lib/article_json/export/common/html/elements/image.rb

@@ -12,7 +12,9 @@ module ArticleJSON
             def export
               create_element(:figure, node_opts) do |figure|
                 figure.add_child(image_node)
-                figure.add_child(caption_node(:figcaption))
+                if @element.caption&.any?
+                  figure.add_child(caption_node(:figcaption))
+                end
               end
             end
 

data/lib/article_json/export/common/html/elements/quote.rb

@@ -10,11 +10,13 @@ module ArticleJSON
             # Generate the quote node with all its containing text elements
             # @return [Nokogiri::XML::NodeSet]
             def export
-              create_element(:div, node_opts) do |div|
+              create_element(quote_tag, node_opts) do |div|
                 @element.content.each do |child_element|
                   div.add_child(base_class.new(child_element).export)
                 end
-                div.add_child(caption_node(:small))
+                if @element.caption&.any?
+                  div.add_child(caption_node(caption_tag))
+                end
               end
             end
 
@@ -24,6 +26,18 @@ module ArticleJSON
             def node_opts
               { class: ['quote', floating_class].compact.join(' ') }
             end
+
+            # HTML tag for the wrapping node
+            # @return [Symbol]
+            def quote_tag
+              :div
+            end
+
+            # HTML tag for the node containing the caption
+            # @return [Symbol]
+            def caption_tag
+              :small
+            end
           end
         end
       end

data/lib/article_json/export/facebook_instant_article/elements/base.rb

@@ -0,0 +1,30 @@
+module ArticleJSON
+  module Export
+    module FacebookInstantArticle
+      module Elements
+        class Base
+          include ArticleJSON::Export::Common::HTML::Elements::Base
+
+          class << self
+            # Return the module namespace this class and its subclasses are
+            # nested in
+            # @return [Module]
+            def namespace
+              ArticleJSON::Export::FacebookInstantArticle::Elements
+            end
+
+            private
+
+            # The format this exporter is returning. This is used to determine
+            # which custom element exporters should be applied from the
+            # configuration.
+            # @return [Symbol]
+            def export_format
+              :facebook_instant_article
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/article_json/export/facebook_instant_article/elements/embed.rb

@@ -0,0 +1,44 @@
+module ArticleJSON
+  module Export
+    module FacebookInstantArticle
+      module Elements
+        class Embed < Base
+          include ArticleJSON::Export::Common::HTML::Elements::Shared::Caption
+
+          # Generate the embedded element node
+          # @return [Nokogiri::XML::NodeSet]
+          def export
+            create_element(:figure, class: 'op-interactive') do |figure|
+              figure.add_child(embed_node)
+              if @element.caption&.any?
+                figure.add_child(caption_node(:figcaption))
+              end
+            end
+          end
+
+          private
+
+          # Type specific object that should be embedded
+          # @return [Nokogiri::XML::Element]
+          def embed_node
+            if %i(facebook_video tweet).include? @element.embed_type.to_sym
+              iframe_node
+            else
+              embedded_object
+            end
+          end
+
+          def iframe_node
+            create_element(:iframe) do |div|
+              div.add_child(embedded_object)
+            end
+          end
+
+          def embedded_object
+            Nokogiri::HTML.fragment(@element.oembed_data[:html])
+          end
+        end
+      end
+    end
+  end
+end

data/lib/article_json/export/facebook_instant_article/elements/heading.rb

@@ -0,0 +1,11 @@
+module ArticleJSON
+  module Export
+    module FacebookInstantArticle
+      module Elements
+        class Heading < Base
+          include ArticleJSON::Export::Common::HTML::Elements::Heading
+        end
+      end
+    end
+  end
+end

data/lib/article_json/export/facebook_instant_article/elements/image.rb

@@ -0,0 +1,11 @@
+module ArticleJSON
+  module Export
+    module FacebookInstantArticle
+      module Elements
+        class Image < Base
+          include ArticleJSON::Export::Common::HTML::Elements::Image
+        end
+      end
+    end
+  end
+end

data/lib/article_json/export/facebook_instant_article/elements/list.rb

@@ -0,0 +1,11 @@
+module ArticleJSON
+  module Export
+    module FacebookInstantArticle
+      module Elements
+        class List < Base
+          include ArticleJSON::Export::Common::HTML::Elements::List
+        end
+      end
+    end
+  end
+end

data/lib/article_json/export/facebook_instant_article/elements/paragraph.rb

@@ -0,0 +1,11 @@
+module ArticleJSON
+  module Export
+    module FacebookInstantArticle
+      module Elements
+        class Paragraph < Base
+          include ArticleJSON::Export::Common::HTML::Elements::Paragraph
+        end
+      end
+    end
+  end
+end