Software

Hop Apple News

Current Version: 3.0.0
  • EE5
  • EE6
  • EE7
Buy on Devotee Buy on EE Store

  • Installation EE 3+

    1. Unzip the folder to a temporary location on your local hard drive.
    2. FTP the files from their local folders to the same locations in your EE install’s /system/user/addons/ and /themes/user/ folders on the server.
    3. Navigate to Add-ons in your EE control panel and install the add-on. That’s it!

  • Installation EE 2

    1. Unzip the folder to a temporary location on your local hard drive.
    2. FTP the files from their local folders to the same locations in your EE install’s /system/expressionengine/third_party/ and /themes/third_party/ folders on the server.
    3. Navigate to Modules in your EE control panel and install the add-on. That’s it!

  • Set up a template

    The add-on doesn’t fetch fields from the DB, it requires you to create a specific very simple template to output the fields you want and eventually do some processing if needed.

    The template must contain only the HTML content that will be converted and sent to Apple News as the article content. That means no <head>, <body>, <script>, <div>. You may only use <p>, <h1-6>, <blockquote>, <ul>, <ol>, <img> tags. Additionally, we created these tags to pass in some important meta information:

    • <apple_thumbnail_url>
    • <apple_title>
    • <apple_excerpt>
    • <apple_intro>
    • <apple_byline>

    Here is an example:

    {if "{exp:hop_apple_news:is_hop_apple_news}" == "yes"}
{exp:channel:entries channel="news" limit="1" require_entry="yes"}
    <apple_thumbnail_url>
        <img src="/images/uploads/default_image.jpg" width="350" height="240" alt="default image" />
    </apple_thumbnail_url>
    <apple_title>{title}</apple_title>
    <apple_excerpt>{excerpt}</apple_excerpt>
    <apple_intro>{intro}</apple_intro>
    <apple_byline>By {byline}</apple_byline>
    <p>{main_content}</p>{!-- if main_content is not RTE; if RTE, remove the p tags --}
{/exp:channel:entries}
{/if}

    Note the {exp:hop_apple_news:is_hop_apple_news} tag. This tag returns yes only if the page is fetched from the add-on. That means nobody will see the content of that page other than the add-on parser. That tag is simply using the user agent sent in the request to verify if it’s coming from the add-on or not.

    Remove the {if} if you want to test your template in your browser. This allows for easy debugging and complex processing.

    Be sure to handle all channel cases in that template if you will send entries from multiple channels to Apple News.

  • Configure the settings

    Add the template URL in the add-on settings. The add-on will try to fetch the HTML from that template we created, appending the entry id at the end of it.

    For example: If your template is news/apple_news_format, just enter /news/apple_news_format in the Entry URL settings field.

  • Set up an Apple News field(s)

    The add-on has a custom field included called Hop Apple News. That field is used to trigger the add-on when saving an entry. Simply add the custom field to any channel you want, just like you would do for any other custom field. There are no options to configure.

    In the Publish entry screen, the field will be displayed as a dropdown. The options are:

    • Don’t Publish This tells the add-on to not send that entry to Apple. If the entry has been sent to Apple in the past, it means the update you made to the entry won’t be sent.
    • Publish Live This publishes the article as live in Apple News. If the article has already been published, this option will update it.
    • Publish Draft This sends the article as draft in Apple News. If a draft has already been sent, this option will update it. You can’t send an article as draft if it has already been sent as live.
    • Delete This deletes the article from Apple News. Once deleted, it’s totally removed from Apple News. You will be able to re-submit the article as draft or live.

    If the entry has been sent to Apple News, the field will display some information regarding the article, including the Apple News share link or errors if any.

    You’re all set

    Once you’ve done all the steps, you are ready to send your articles to Apple News. If your Apple News channel hasn’t been approved by Apple yet, you won’t be able to send the articles as live (this will trigger an error).

    You will have to send a few articles as drafts and then ask Apple to approve your channel in order to publish articles live.

  • Usage

    Setup layout and styling

    Apple allows quite deep styling but it’s not really easy to comprehend. It’s sometimes hard to get a sense of what settings or parameters do what.

    Each element (title, list, paragraph…) has its own styling. It’s not possible to set a general style for all elements. The styling is divided into different parts (borders, text style, shadow…).

    Our add-on allows you to setup styling for every element via the Layout page, which should make styling easier.

    Once the styles are roughly setup, it’s ready to be previewed.

    Article Preview

    Apple provides a tool that allows you to preview an article without sending it to your Apple News account.

    Grab the News Preview app, launch it and select a device to preview the articles on.

    Now, go on the Preview page of the add-on to generate an article.json file from an entry (just enter an entry id). Drag and drop that file into the News Preview app. The News app should automatically open on the device and show the article.

    Notes:

    • The file must be named article.json
    • If the file is not correctly formed or contains invalid elements, the News Preview app will show an error message with details about the issue.

    We recommend previewing a wide range of articles containing different elements in them to be sure they properly display in the iOS News app.

    Previewing on your device

    You can preview draft articles on your device, but they need to be sent to Apple News first.

    The iCloud account you’re connected to on your device must be the same account that is registered as the Apple News Publisher.

    In Safari, go to https://www.icloud.com/#newspublisher. Under the Articles tab, choose Drafts. There will be a note there explaining how you can preview your Draft articles on an iOS device.

    Important: If you’ve delivered articles using the Apple News API or a plug-in, make sure you preview them in Apple News to see how they look on iPhones and iPads.

    Click on “previewed them” to open up a popup containing the URL to your news channel. Opening that URL on an iOS device should open your channel in the News app, where you can view draft articles.

    Send entries to Apple News

    As explained above, use the custom field when creating or editing an entry to automatically trigger the add-on.

    Entries list

    The add-on saves a record of all entries that have been sent to Apple. The entries list gives you access to those records, including details and any errors from Apple.

    Supported HTML Code

    As mentioned before, the add-on cannot convert all HTML code into a valid Apple News JSON data file. If you’re unsure, please refer to the Apple developer documentation for the most up to date information on valid code.

  • Testing

    There are 3 parts to test: the conversion process, the layout/styling and the automatic sending to Apple.

    Testing the code conversion

    One of the biggest and most complicated parts of the add-on is the conversion from HTML to Apple News JSON data.

    Testing the conversion is actually simple. To avoid having to deal with entries, you can write raw HTML in a template. Then go to the add-on Settings page and set the Entry URL to use the template you created. Then go to the preview page, generate an article.json file and test that file in the News Preview app.

    Testing the layout/styling and previewing articles

    Refer to the documentation to learn how to setup the articles layout and styling.

    Once you’re done with styling, choose or create a new entry with a wide range of elements (titles, lists, paragraphs, images…).

    Create an article.json file from that article to preview it (learn more about article preview in the documentation above).

    Testing the automatic sending to Apple

    This doesn’t require to have styling already set.

    Make sure all the settings are correctly set in the Settings page of the add-on.

    Make sure you have a channel with a Hop Apple News custom field.

    Create a new entry or edit an existing entry of that channel. Set the Hop Apple News field to Publish Draft. Save the entry. That should trigger the entry to be sent to Apple (unless you’ve disabled the add-on or if the entry status isn’t set accordingly to the add-on settings).

    Go to your Apple News Publisher account, select the right channel and look at the Drafts article listing. You should see your entry. It’s saved as a draft, nobody will be able to see that article in the News app, except you.

    You should now try to edit the entry, select Publish Draft again and save, to make sure the entry are properly being updated in your Apple News Publisher account.

  • External Libraries

    Apple News API

    This Library isn’t up to date and doesn’t contain attributes that were published in the 1.1 version (and later) Apple News API.

    The code has also been modified from the original to make it easier to work with.

  • Updating

    Updating is easy:

    1. Download a new version from this website, and extract on your hard drive.
    2. Upload the new files to their appropriate locations.

  • Uninstalling

    1. Navigate to the Add-Ons > Modules tab in your EE control panel and uninstall the module.
    2. Remove the add-on directory from your EE system folder on the server.

  • Version History

    Last updated: one month ago

    3.0.0 - 2024-02-29

    Updated

    • Hello EE7!
    • PSR-12

    2.0.0 - 2021-06-15

    Updated

    • Hello EE6!

    1.1.0 - 2021-06-10

    Changed

    • Change directory structure, no code changes

    1.0.0 - 2019-03-27

    Added

    • Initial release

Have a Project for Us?

Request a Proposal