JSON Format for News Articles & Ruby Gem.
First, install the gem with gem install article_json
or add it to your Gemfile
via gem 'article_json'
.
require 'article_json'
# parse the HTML export of a Google Document
article = ArticleJSON::Article.from_google_doc_html(google_doc_html)
# initialize article-json format from storage (JSON string)
article = ArticleJSON::Article.from_json(json_string)
# initialize article-json format from storage (already parsed JSON)
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 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
To load, parse and html-export the latest version of the reference document, run the following:
$ export DOC_ID=1E4lncZE2jDkbE34eDyYQmXKA9O26BHUiwguz4S9qyE8
$ ./bin/article_json_export_google_doc.rb $DOC_ID \
| ./bin/article_json_parse_google_doc.rb \
| ./bin/article_json_export_html.rb
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:
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, FacebookInstantArticle, or
# PlainText exporters:
config.register_element_exporters(
:amp, # Or change this for `:facebook_instant_article` or `:plain_text`
image: ArticleJSON::Export::AMP::Elements::ScaledImage
)
end
A full example of the format can be found in the test fixtures: Parsed Reference Document
This Reference Document lists contains all supported formatting along with some descriptions.
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:
# 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:
# 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
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.
The AMP exporter generates an AMP HTML representation of the elements.
AMP uses custom HTML tags, 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.
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.
To learn more about the Facebook Instant Article HTML format see have a look at the Facebook Developer Documentation.
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.
Usage:
# 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
- Fork this repository
- Implement your feature or fix including Tests
- Update the change log
- Commit your changes with a meaningful commit message
- Create a pull request
Thank you!
See the list of contributors.
For the whole test suite, run bundle exec rspec
.
For individual tests, run bundle exec rspec spec/article_json/version_spec.rb
.
MIT License, see the license file.