article_json 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 14715c8b4542d6737963ab39e16c97a2060454ab
-  data.tar.gz: ae62279949f41500e34cb18bd1642b73c6bbb86a
+  metadata.gz: 416c6c5505374ac9303aa393dcfbfb361276fa45
+  data.tar.gz: 5e22d9856b75f0d16203678d2b00e9faa05831b5
 SHA512:
-  metadata.gz: 877ad153850744cd40a169240b1151ee09612775eb7bc4e53f5cebc60b0fc9c859e3861ebc4b1c3b119a618c905242945a681d1f749b1fedbfff69281ed5cd9c
-  data.tar.gz: a636ea3a56f54700275e31a38df2b41ed23f1c9d8199e5b5408b078c3e33fc999872406194bddc238bd57352a52f0e22c6ca3bef34ad43942b2a0eb06ed7d6f5
+  metadata.gz: 015714d59724701d0fc6edda9a7257315d903055c6d5c3a7c233e4f0780e2f6cb227e2c02c0f30df5999d6d8bc75da643c59bda757858386c55f604f8166b601
+  data.tar.gz: dd5b53abece174c23c2639ae80ef53f28bd79004249c46dc4aec26e1c0de4fa9bb91512be40625394b3e7c740bd3229e2596fba0655d2837d0cca5e0636db651

data/CHANGELOG.md

@@ -1,6 +1,19 @@
 # Changelog
 
-## ? - WIP
+## 0.2.0 - 2017/11/03
+In this second release we **added support** to:
+- Export AMP along with required libraries for AMP rendering
+- Configure custom HTML and AMP element exporters
+- Resolve oembed elements in HTML export
+
+One potentially **breaking change** was added:
+- Export quotes as `<div>` instead of `<aside>`
+
+**Fixes**:
+- Support Vimeo videos with old flash player URLs
+- Make Google Parser more fault tolerant
+- Respect linebreaks when importing Google Docs
+- Export linebreaks in JSON to `<br>` tags in HTML / AMP
 
 ## 0.1.0 - 2017/09/20
 This is the very first release, with the following functionality:

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,46 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at info@devex.com. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

data/README.md

@@ -27,6 +27,11 @@ article = ArticleJSON::Article.from_hash(parsed_json)
 # export article as HTML
 puts article.to_html
 
+# export article as AMP
+puts article.to_amp
+# get javascript libraries needed for the AMP article
+puts article.amp_exporter.amp_libraries
+
 # export article as JSON
 puts article.to_json
 ```
@@ -42,6 +47,44 @@ $ ./bin/article_json_export_google_doc.rb $DOC_ID \
     | ./bin/article_json_export_html.rb
 ```
 
+### Configuration
+There are some configuration options that allow a more tailored usage of the
+`article_json` gem. The following code snippet gives an example for every
+available setting: 
+
+```ruby
+ArticleJSON.configure do |config|
+  # set a custom user agent used for o-embed API calls
+  config.oembed_user_agent = 'devex oembed (+https://www.devex.com/)'
+
+  # Register additional html exporters, just make sure that it complies with the
+  # interface of other element exporter classes (extend Base, implement #export)
+  config.register_element_exporters(
+    :html,
+    advertisement: ArticleJSON::Export::HTML::Elements::Advertisement
+  )
+  
+  # You can also overwrite existing exporters:
+  config.register_element_exporters(
+    :html,
+    image: ArticleJSON::Export::HTML::Elements::ScaledImage
+  )
+  
+  # And you can define multiple custom exporters:
+  config.register_element_exporters(
+    :html,
+    advertisement: ArticleJSON::Export::HTML::Elements::Advertisement,
+    image: ArticleJSON::Export::HTML::Elements::ScaledImage
+  )
+  
+  # It works the same way for custom AMP exporters:
+  config.register_element_exporters(
+    :amp,
+    image: ArticleJSON::Export::AMP::Elements::ScaledImage
+  ) 
+end
+``` 
+
 ## Format
 A full example of the format can be found in the test fixtures:
 [Parsed Reference Document](https://github.com/Devex/article_json/blob/master/spec/fixtures/reference_document_parsed.json)
@@ -51,12 +94,113 @@ A full example of the format can be found in the test fixtures:
 This [Reference Document](https://docs.google.com/document/d/1E4lncZE2jDkbE34eDyYQmXKA9O26BHUiwguz4S9qyE8/edit?usp=sharing)
 lists contains all supported formatting along with some descriptions.
 
+## Add custom elements
+Sometimes you might want to place additional elements into the article, like e.g. advertisements. 
+`article_json` supports this via `article.place_additional_elements` which accepts an array of elements that you can define in your own code. 
+Each element that is added this way will directly get placed in between paragraphs of the article.
+The method ensures that an additional element is never added before or after any node other than paragraphs (e.g. an image).
+The elements are added in the order you pass them into the method.
+If the article should not have enough spaces to place all the provided elements, they will be placed after the last element in the article.
+
+You can pass any type of element into this method. 
+If the objects you pass in are instances of elements defined within this gem (e.g. `ArticleJSON::Elements::Image`), you won't have to do anything else to get them rendered.
+If you pass in an instance of a custom class (e.g. `MyAdvertisement`), make sure to register an exporter for this type (check the _Configuration_ section for more details).
+
+Example using only existing elements:
+```ruby
+# Create your article instance as you normally do
+article = ArticleJSON::Article.from_hash(parsed_json)
+
+# Within your code, create additional elements you would like to add
+image_advertisement = 
+  ArticleJSON::Elements::Image.new(source_url: 'https://robohash.org/great-ad', 
+                                   caption: ArticleJSON::Elements::Text.new(
+                                    content: 'Buy more robots!',
+                                    href: '/robot-sale'
+                                   ))
+text_box_similar_articles = 
+  ArticleJSON::Elements::TextBox.new(content: [
+    ArticleJSON::Elements::Heading.new(level: 3, content: 'Read more...'),  
+    ArticleJSON::Elements::List.new(content: [
+      ArticleJSON::Elements::Paragraph(content: [
+        ArticleJSON::Elements::Text.new(content: 'Very similar article', 
+                                        href: '/news/123'),
+      ]),
+      ArticleJSON::Elements::Paragraph(content: [
+        ArticleJSON::Elements::Text.new(content: 'Great article!', 
+                                        href: '/news/42'),
+      ]),
+    ]),  
+  ])
+
+# Add these elements to the article
+article.place_additional_elements([image_advertisement, 
+                                   text_box_similar_articles])
+               
+# Export the article to the different formats as you would normally do                    
+article.to_html # this will now include the custom elements
+``` 
+
+Example with custom advertisement elements:
+```ruby
+# Define your custom element class
+class MyAdvertisement
+  attr_reader :url
+  
+  def initialize(url:)
+    @url = url
+  end
+  
+  def type
+    :my_advertisement
+  end
+end
+
+# Define an exporter for your class, we only use HTML in this example but this
+# would work similarly for AMP or other formats
+class MyAdvertisementExporter < 
+  ArticleJSON::Export::HTML::Elements::Base 
+  
+  # Needs to implement the `#export` method
+  def export
+    create_element(:iframe, src: @element.url)
+  end
+end
+
+# Register your custom exporter for your element type
+config.register_element_exporters(
+  :html,
+  my_advertisement: MyAdvertisementExporter
+)
+
+# Create the elements you want to add
+ad_1 = MyAdvertisement.new(url: '/my_first_ad')
+ad_2 = MyAdvertisement.new(url: '/my_second_ad')
+ad_3 = MyAdvertisement.new(url: '/my_last_ad')
+
+# Add them to the article
+article.place_additional_elements([ad_1, ad_2, ad_3])
+
+# And again, export the article as you would normally do it
+article.to_html
+```
+
 ## Export
 ### HTML
 The HTML exporter generates a HTML string for a list of elements. An example of
 the HTML export for the parsed reference document can be found 
 [here](https://github.com/Devex/article_json/blob/master/spec/fixtures/reference_document_exported.html).
 
+### AMP
+The AMP exporter generates an AMP HTML representation of the elements. 
+
+AMP uses [custom HTML tags](https://www.ampproject.org/docs/reference/components), some of which require additional Javascript libraries.
+If you have an `article` (see code example in _Usage_ section), you can get a list of the custom tags required by this article by calling `article.amp_exporter.custom_element_tags` and by calling `article.amp_exporter.amp_libraries` you get a list of `<script>` tags that can directly be included on your page to render the AMP article. 
+
+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).
+
 ## Contributing
 - Fork this repository
 - Implement your feature or fix including Tests
@@ -72,7 +216,7 @@ See the
 ### Tests
 For the whole test suite, run `bundle exec rspec`.
 
-For individual tests, run `bundle exec rspec spec/article_json/version_spec.rb`. 
+For individual tests, run `bundle exec rspec spec/article_json/version_spec.rb`.
 
 ## License
 MIT License, see the [license file](LICENSE).

data/lib/article_json/article.rb

@@ -2,7 +2,7 @@ module ArticleJSON
   class Article
     attr_reader :elements
 
-    # @param [Arra[ArticleJSON::Elements::Base]] elements
+    # @param [Array[ArticleJSON::Elements::Base]] elements
     def initialize(elements)
       @elements = elements
     end
@@ -22,10 +22,39 @@ module ArticleJSON
       to_h.to_json
     end
 
+    # Exporter instance for HTML
+    # @return [ArticleJSON::Export::HTML::Exporter]
+    def html_exporter
+      @html_exporter = ArticleJSON::Export::HTML::Exporter.new(@elements)
+    end
+
     # HTML export of the article
     # @return [String]
     def to_html
-      ArticleJSON::Export::HTML::Exporter.new(@elements).html
+      html_exporter.html
+    end
+
+    # Exporter instance for AMP
+    # @return [ArticleJSON::Export::AMP::Exporter]
+    def amp_exporter
+      ArticleJSON::Export::AMP::Exporter.new(@elements)
+    end
+
+    # AMP export of the article
+    # @return [String]
+    def to_amp
+      amp_exporter.html
+    end
+
+    # Distribute passed elements evenly throughout the article. All passed
+    # elements need to have an exporter to be represented in the rendered
+    # article.
+    # @param [Object] additional_elements
+    def place_additional_elements(additional_elements)
+      @elements =
+        ArticleJSON::Utils::AdditionalElementPlacer
+          .new(self, additional_elements)
+          .merge_elements
     end
 
     class << self

data/lib/article_json/configuration.rb

@@ -18,6 +18,62 @@ module ArticleJSON
 
     def initialize
       @oembed_user_agent = nil
+      @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)
+    # @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}`"
+      end
+      if !type_class_mapping.is_a?(Hash) ||
+          type_class_mapping.keys.any? { |key| !key.is_a? Symbol } ||
+          type_class_mapping.values.any? { |value| !value.is_a? Class }
+        raise ArgumentError, '`type_class_mapping` has to be a Hash with '\
+                             'symbolized keys and classes as values but is '\
+                             "`#{type_class_mapping.inspect}`"
+      end
+
+      @custom_element_exporters[exporter.to_sym] ||= {}
+      @custom_element_exporters[exporter.to_sym].merge!(type_class_mapping)
+    end
+
+    # Get custom exporter class for a given exporter and element type
+    # @param [Symbol] exporter_type
+    # @param [Symbol] element_type
+    # @return [Class|nil]
+    def element_exporter_for(exporter_type, element_type)
+      @custom_element_exporters.dig(exporter_type, element_type)
     end
   end
 end

data/lib/article_json/elements/paragraph.rb

@@ -18,6 +18,20 @@ module ArticleJSON
         }
       end
 
+      # Return `true` if the paragraph has no elements
+      # @return [Boolean]
+      def empty?
+        !content || content.empty?
+      end
+
+      # Return `true` if the paragraph is empty or if all elements are blank
+      # @return [Boolean]
+      def blank?
+        empty? || content.all? do |element|
+          element.respond_to?(:blank?) && element.blank?
+        end
+      end
+
       class << self
         # Create a paragraph element from Hash
         # @return [ArticleJSON::Elements::Paragraph]

data/lib/article_json/elements/text.rb

@@ -27,6 +27,19 @@ module ArticleJSON
         }
       end
 
+      # Returns `true` if `content` has a length of zero or is `nil`
+      # @return [Boolean]
+      def empty?
+        !content || content.empty?
+      end
+
+      # Returns `true` if `content` is empty (see `#empty?`) or only contains
+      # whitespace (including non-breaking whitespace) characters
+      # @return [Boolean]
+      def blank?
+        empty? || content.gsub(/[\s\u00A0]/, '').empty?
+      end
+
       class << self
         # Create a text element from Hash
         # @return [ArticleJSON::Elements::Text]

data/lib/article_json/export/amp/custom_element_library_resolver.rb

@@ -0,0 +1,55 @@
+module ArticleJSON
+  module Export
+    module AMP
+      # AMP uses custom HTML tags for elements like iframes or embedded youtube
+      # videos. These elements each require a javascript to be loaded to be
+      # properly rendered by the browser. This class resolves the custom tags to
+      # a list of javascript libraries which then can be included on the page.
+      class CustomElementLibraryResolver
+        # @param [Array[Symbol]] custom_element_tags
+        def initialize(custom_element_tags)
+          @custom_element_tags = custom_element_tags
+        end
+
+        # List of all custom tags with their library source URI
+        # @return [Hash[Symbol => String]]
+        def sources
+          @custom_element_tags.each_with_object({}) do |custom_element, mapping|
+            src = custom_element_script_mapping(custom_element)
+            mapping[custom_element] = src if src
+          end
+        end
+
+        # Return all custom library script tags required for the given custom
+        # element tags
+        # @return [Array[String]]
+        def script_tags
+          sources.map do |custom_element_tag, src|
+            <<-HTML.gsub(/\s+/, ' ').strip
+                <script async 
+                        custom-element="#{custom_element_tag}" 
+                        src="#{src}"></script>
+            HTML
+          end
+        end
+
+        private
+
+        # Given a custom_element identifier, get the script script source
+        # @param [Symbol] custom_element_tag
+        # @return [String]
+        def custom_element_script_mapping(custom_element_tag)
+          {
+            'amp-iframe': 'https://cdn.ampproject.org/v0/amp-iframe-0.1.js',
+            'amp-twitter': 'https://cdn.ampproject.org/v0/amp-twitter-0.1.js',
+            'amp-youtube': 'https://cdn.ampproject.org/v0/amp-youtube-0.1.js',
+            'amp-vimeo': 'https://cdn.ampproject.org/v0/amp-vimeo-0.1.js',
+            'amp-facebook':
+              'https://cdn.ampproject.org/v0/amp-facebook-0.1.js',
+          }[custom_element_tag]
+        end
+      end
+    end
+  end
+end
+

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

@@ -0,0 +1,36 @@
+module ArticleJSON
+  module Export
+    module AMP
+      module Elements
+        class Base
+          include ArticleJSON::Export::Common::HTML::Elements::Base
+
+          # List of custom element tags used by this element
+          # @return [Array[Symbol]]
+          def custom_element_tags
+            []
+          end
+
+          class << self
+            # Return the module namespace this class and its subclasses are
+            # nested in
+            # @return [Module]
+            def namespace
+              ArticleJSON::Export::AMP::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
+              :amp
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,97 @@
+module ArticleJSON
+  module Export
+    module AMP
+      module Elements
+        class Embed < Base
+          include ArticleJSON::Export::Common::HTML::Elements::Embed
+
+          # Custom element tags required for this embedded element
+          # @return [Array[Symbol]]
+          def custom_element_tags
+            case @element.embed_type.to_sym
+            when :youtube_video then %i(amp-youtube)
+            when :vimeo_video then %i(amp-vimeo)
+            when :facebook_video then %i(amp-facebook)
+            when :tweet then %i(amp-twitter)
+            when :slideshare then %i(amp-iframe)
+            else []
+            end
+          end
+
+          private
+
+          # Type specific object that should be embedded
+          # @return [Nokogiri::XML::Element|nil]
+          def embedded_object
+            case @element.embed_type.to_sym
+            when :youtube_video
+              youtube_node
+            when :vimeo_video
+              vimeo_node
+            when :facebook_video
+              facebook_node
+            when :tweet
+              tweet_node
+            when :slideshare
+              slideshare_node
+            end
+          end
+
+          # @return [Nokogiri::XML::Element]
+          def youtube_node
+            create_element('amp-youtube',
+                           'data-videoid' => @element.embed_id,
+                           width: default_width,
+                           height: default_height)
+          end
+
+          # @return [Nokogiri::XML::Element]
+          def vimeo_node
+            create_element('amp-vimeo',
+                           'data-videoid' => @element.embed_id,
+                           width: default_width,
+                           height: default_height)
+          end
+
+          # @return [Nokogiri::XML::Element]
+          def tweet_node
+            create_element('amp-twitter',
+                           'data-tweetid' => @element.embed_id,
+                           width: default_width,
+                           height: default_height)
+          end
+
+          # @return [Nokogiri::XML::Element]
+          def facebook_node
+            url = "#{@element.oembed_data[:author_url]}videos/#{@element.embed_id}"
+            create_element('amp-facebook',
+                           'data-embedded-as' => 'video',
+                           'data-href' => url,
+                           width: default_width,
+                           height: default_height)
+          end
+
+          # @return [Nokogiri::XML::Element]
+          def slideshare_node
+            node = Nokogiri::HTML(@element.oembed_data[:html]).xpath('//iframe')
+            create_element('amp-iframe',
+                           src: node.attribute('src').value,
+                           width: node.attribute('width').value,
+                           height: node.attribute('height').value,
+                           frameborder: '0',)
+          end
+
+          # @return [String]
+          def default_width
+            '560'
+          end
+
+          # @return [String]
+          def default_height
+            '315'
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,30 @@
+module ArticleJSON
+  module Export
+    module AMP
+      module Elements
+        class Image < Base
+          include ArticleJSON::Export::Common::HTML::Elements::Image
+
+          private
+
+          # @return [Nokogiri::HTML::NodeSet]
+          def image_node
+            create_element('amp-img',
+                           src: @element.source_url,
+                           width: default_width,
+                           height: default_height,
+                           layout: :responsive)
+          end
+
+          def default_width
+            '640'
+          end
+
+          def default_height
+            '480'
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

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