What are RSS Feeds?
RSS feeds (along with other popular formats such as MRSS, ATOM and iATM) are standardized web feeds that are used to share information and media across the web.
How do RSS Feeds work with BLOX?
BLOX CMS can both ingest content via RSS feed or be the RSS provider. The BLOX Syndication tool can be setup to pull in RSS feeds, as well as standardized feeds from some of our news partners like Associated Press or CNN. When it comes to providing content, RSS feeds can be crafted by modifying search queries with search parameters using the best practices listed below. The options listed apply to RSS, MRSS, ATOM and iATOM feed types, unless otherwise noted.
How to setup an RSS Feed
You can edit this example URL:
your_domain.com is the domain of your Blox CMS website.
/search/ is the search page of your Blox CMS website.
&q=<text string> is the keyword(s) you are searching for. No keyword(s) would be &q= . Multiple keywords can be searched for by adding a +. Ex: &q=city+hall+fire
&nsa=eedition tells our system NOT to search e-Editions.
&t=<asset type> is the asset type you are searching for. To search for all asset types use &t= .
- Asset types include:
- article
- audio
- collection
- flash
- html
- image
- link
- poll
- table
- video
- YouTube
- ZIP
&l= is the number of assets to be returned in the feed. This is a number between 1 and 100. Ex l=100
&s= is sort by. This is used in conjunction with &sd= (to set order). Options include:
- &s= blank equals relevance
- &s=start_time start time
- &s=title title in alphabetical order
&sd= returns the results in asc (ascending), or desc (descending) order
&c[]=<section name(s)> will restrict the search to only certain sections. Ex: &c[]=news/*,sports/* (this will search news and all subsections, and sports and all subsections).
&fl= this allows you to search for a specific flag. Ex. &fl=breaking
&nfl= this allows you to exclude a specific flag. Ex. &nfl=top_story
&d= this allows you to search a specific date. Ex: &d=01/20
&d1= used in conjunction with &d2= allows you to search a date range. Ex: &d1=01/19/2016&d2=01/21/2016. You can also use any natural language time expressions, such as "1 day ago" "30 minutes ago", "2 weeks ago" by URL encoding the spaces with %20. The time expression "24 hours ago" would be: "d1=24%20hours%20ago".
NOTE: &d=, and &d1= and &d2= come at the end of the URL. &f= comes before. For the purposes of this doc &f= is listed last.
NOTE: If you are not using date parameters, &d=, and &d1= and &d2= do not need to be part of the URL.
How to Generate an RSS Feed (Flex)
To do this is to add this path at the end of the domain: /search/?q=&t=article&f=rss (Example: http://www.yoursite.com/search/?q=&t=article&f=rss).
You can set the start and delete date for assets using dcterms:valid tag.
How to Generate an MRSS Feed
MRSS is an RSS Feed for Media files. Non-media files like html, poll, pdf, etc will not be listed. If some how they do get listed, the MRSS Feed will not validate them.
NOTE: In order to preview MRSS Feeds, you need a 3rd party MRSS Viewer.
NOTE: This currently works in ATOM. In order for this to work in RSS, a request needs to be submitted to Customer Service (800-293-9576).
&f=atom&altf=mrss tells the system to generate an MRSS feed.
MRSS is an RSS extension used for syndicating multimedia files (audio, video, image) in RSS feeds.
You can add &ips=300 to the extension, which will change the image preview size to 300 px wide.
Adding &emb=true to the string will turn on the embedded assets. This is off by default because this is not valid mrss, but is useful for app developers.
http://your_domain.bloxcms.com/search/?q=&nsa=eedition&t=&l=100&s=&sd=desc&f=atom&altf=mrss&emb=true
To display a span tag for each flag assigned to each story, you can add &flags=1.
To provide the full text of the article:
&fulltext=<passphrase> returns the full text of the articles in the feed instead of just the title and first paragraph.
To Set Up Fulltext:
- In Settings / Site select 'Custom Properties'.
- Click Add to create a new custom property.
- In the Name field, enter passphrase. In the Value field, enter any random passphrase (this will be used in the URL).
- Save these changes.
- To see the atom feed with the fulltext option, add &fulltext=<passphrase>' to the end of your Atom search URL.
http://your_domain.com/search/?q=&nsa=eedition&t=&l=100&s=&sd=desc&f=rss&fulltext=showtext
NOTE: In the example above showtext is the passphrase.
For more information on MRSS, click here.
How to Generate an iTunes Feed
You can set up the iTunes RSS feed by using our standard search queries, then use ?f=rss&altf=itunes in the URL parameters to trigger iTunes mode.
How to Generate an ATOM Feed
&f=atom tells the system to generate an ATOM feed.
Atom feeds include links to images for use in feeding 3rd-party sites or applications.
For example:
<link href="http://www.example.bloxcms.com/online_features/family_living/purr-fect-tips-to-protect-cats-year-round/image_74b320e6-2e7b-53a4-b1ea-da01f5fd8dfa.html"/>
How to Generate an iATOM Feed
&f=atom&altf=iatom tells the system to generate an iATOM feed.
AP’s iATOM is a variant of ATOM. It contains the full text of stories, rather than just a link to the full text. In AP Content Enrichment, iATOM is the preferred type of feed. Typically, for the purpose of sending content to AP you will want a feed of your latest 100 articles in iATOM format. That feed will look like this:
The number of paragraphs that are returned within an iatom search feed can be specified using pgs=value for the desired number of paragraphs. For example, to limit the number of paragraphs to 3, the parameter &pgs=3 could be added at the end of the string.
The use of &nfl=ap can also be added to an iatom feed, which basically means "no content with the flag equaling ap"
How to Generate a Secure Feed
Changing the http:// to https:// will transform your feeds into secure feeds. This is done in your Site Settings (go to Settings / Site and click on HTTPS - for help, Click Here).
Links to binary images and files will convert to a secure link. However, the URLs to actual website pages will not be https until the website is fully compliant.
NOTE: In order for this to function correctly, the site's HTTPS default setting will need to be changed from "Redirect to HTTPS" to "Do nothing".
How to Generate a Verve Feed (Flex)
&f=rss&altf=verve_full tells the system to generate a Verve feed.
This will integrate BLOX with the Verve mobile app. The Sponsored flag is supported by BLOX CMS for Verve feeds. Articles coming in from from a Verve Feed will display the Sponsored flag with the asset on your site.
How to Generate a Google Newsstand feed
Adding &altf=google_newsstand will allow you to send your stories up to Google Newsstand.
https://your_domain.bloxcms.com/search?f=rss&altf=google_newsstand&fl=featured&t=article,collection&l=20&s=start_time&sd=dec
How to Generate a Whiz feed
Adding &altf=whiz will allow you to generate a feed for Whiz apps.
https://your_domain.bloxcms.com/search?f=rss&altf=whiz
Deeper Dive: Using Search on your BLOX CMS website
Overview
This section goes into more detail of the available parameters discussed above at the top of this article.
The search application supports a variety of query parameters that are either passed through the URL or the search form. If passed through the URL, the query would be formatted with a question mark and then the query parameter name, an equals sign, and then the value. Query parameters are separated by ampersands.
Click the Advanced Search Options button to view additional search options.
You can use the advanced search options to build your RSS or ATOM feed. Choose what types of assets you want to pull, any keyword tags that you want to use as well as any sections you want to pull from.
Hitting Search will generate the page based on your specifications. The url of your page will look something like this:
Notice that the url is built using different URL queries. For instance ?q=Cubs means pull anything with the keyword 'cubs.' The f=atom tells it to display the results in atom.
Examples
Example 1
The above searches the word "fire" in the news section
Example 2
example.com/search/?c[]=news,sports
This returns all assets with section tags of news and sports.
Example 3
example.com/search/?c[]=news&k[]="afghanistan war"
The above would search the news section for stories with the keyword tag "afghanistan war."
NOTE: By default, the keyword tag search will formulate queries with OR statements, unless the keyword is wrapped in quotes (as above). So without quotes, the query above will search for assets with either Afghanistan as a keyword or war. But it would not return the same articles as "afghanistan war." The open and closed brackets after the "k" are only needed if you intend to search for multiple keywords. In the example above they are not required to create the appropriate search.
Parameters
The following query parameters are currently supported:
Section Tag Search
A list of categories to search against. Multiple categories can be provided with c[] notation.
short parameter: c
long parameter: category
An asterisk can be used for wildcard searching, which is useful to search all subcategories:
Multiple Categories can be searched by utilizing 'c[]' and a comma-separated list of sections:
https://www.example.com/search/?c[]=news,sports
NOTE: Multiple category searching is not supported in all applications.
Block ID
The Block ID can be found in the Title of the actual block or in the Widget Embed Code. This parameter accepts as input a single block ID. When a block ID is passed, all other search parameters are no longer relevant except offset (o), limit (l), and format (f). Format can be used to get RSS, JSON, or HTML (the default). The block template adapter should be extended to have a method called search_params that accepts any of the following parameters:
- offset: The offset to start the search at. By default, this should the limit of the block plus one. If passed, this will override the limit. If zero or empty, offset should be omitted.
- limit (l): The maximum results to return. The default should be 50 - the maximum number of items a block can return.
- format: The format parameter. By default, no format should be passed. Allows for RSS and other choices to be crafted.
- short parameter: bl (lowercase L)
- full parameter: block_id
Example
<a href="https://www.example.com/search/?[% this.block.search_params('limit': 25) | html %]">More items from this block</a>
This example would then return
<a href="https://www.example.com/search/?bi=1234&l=25"a>More items from block</a>
NOTE: This parameter will return search results for Editorial, Community, and Marketplace applications.
Flag Search
A list of flags to search against. Multiple flags can be provided with fl[] notation. Example: http://example.com?fl[]breaking,top_story
- short parameter: fl
NOTE: To use the fl parameter, the application must be declared, even when the desired application is the same as the default application.
Application Search
Which application to search against. This defaults to editorial: http://www.example.com/search/?app=editorial
short parameter: app
Other options include business, calendar, classifieds, and e-edition. However, full support may not be available for each.
Start Date
A starting date range. If not supplied, it is assumed to be ANY asset from any time period.
- short parameter: d1
- long parameter: start_date
End Date
An ending date range. If 'd2' is provided, this acts as the ending range. If not provided, it is assumed 'today'. Future search dates are not made available on the front-end.
- short parameter: d2
- long parameter: end_date
BEST PRACTICE: When using d1 and d2 date range parameters, remember that the starting date range should be the date that is furthest in the past. Additionally, remember that you can use some PHP natural language relative specifiers to create your search. For example, this will return articles that are less than 3 months old: /&d1=90%20days%20ago&d2=today
Date Selector
A boolean value, when set to on, can be used in combination with the d1 variable to search a range of dates with a specific phrase. This is frequently used to generate search results for a range of time using a worded phrase such as "today", "yesterday", "24+hours+ago"
- short parameter: d
- long parameter: date_selector
- http://www.example.com/search/?c[]=news&d=on&d1=48+hours+ago
Result Format
The output format of the results. The default is 'html'. Other choices include 'atom' and 'rss'.
- short parameter: f
- long parameter: format
Keyword Search
Search using the query provided against the keywords field. This is not full text, only the keyword tags are searched.
NOTE: Search results will now pull both the correct and incorrect version of Latin-based words with accented letters, for example: senor and señor.
Additionally, you will need to search for multiple-word keyword tags by enclosing the tag in quotes (see example at the top of this page).
BEST PRACTICE: Using the pound sign (#) at the start of your keywords will tell the system to NOT display them where keywords are normally displayed - for example, in front-page blocks or at the bottom of stories. For example:
#latest
If you'd like to search for keywords that start with a pound sign, however, you must remember to URL encode them within the query string. Like so:
example.com/search/?k=%23latest
- short parameter: k
- long parameter: keywords
Limit
The number of results to return. Defaults to 10.
- short parameter: l
- long parameter: limit
- secondary parameter: num
Offset
How many search results to skip before producing results to the client. This is needed for paging.
- short parameter: o
- long parameter: offset
- secondary parameter: start
Query Search
A query for the search terms provided. This is in a full text format, searching the headline, body text and keyword tags.
- short parameter: q
- long parameter: query
Sort Order
Sort the results in the order of the given definition. The default is 'asc.' Another choice would be 'desc.'
- short parameter: sd
Sort By
Sort the results by the given definition. The default is 'relevance.' Other choices would be 'start_time', 'priority' and 'title.'
- short parameter: s
Asset Type
A list of asset types that you would like returned. Options are: Article, Image, Collection, Audio, Flash, HTML, Link, PDF, Poll, Table, Video, YouTube, ZIP. If a selection of asset types is not made, all types will be returned.
- short parameter: t
- long parameter: type
Article with Preview Image Only
This allows you to search on Article Assets that have a Preview Image only.
- Parameter: hpr=1
Author
This will search the author field for the UUID provided.
- short parameter: a
- http://www.example.com/search/?a=be722206-efd8-11e6-8ed4-333d8c39201f
Byline
This will search the byline field for the string provided
- short parameter: b
- long parameter: byline
- http://www.example.com/search/?b=John Doe
Update time
This will search the time the asset was updated
- short parameter: s
Classifieds
To create a search of ALL classified assets the format:
To create a search of only liner ads:
To create a search of only PDF display ads:
- http://www.example.com/classifieds/?l=100&q=&t=pdfdisplayad
To create a search of only classifieds coupons:
RSS Feeds Image Size
By default, images will come through an RSS Feed in a 300 pixel width by 200 pixel height. Use the 'ips' parameter to specify the width size you want it set to.
- short parameter: ips
- long parameter: ips=1000 (ie: using 1000 pixels - set this to the size you want - it can go anywhere in the string)
Search Exclusions
Exclude Specific Category
An exclusion can be added to filter out query results that belong to certain sections of your site.
- short parameter: nc
- long parameter: no category
- example.com/search/?nc=sports*/
The above searches for articles, excluding those that are section tagged as sports.
Exclude Specific Flag
A RSS feed can be created, based on a search that excludes assets with a specific flag.
- example.com/search/?nfl=contributed&f=rss
- The above searches for all assets, except for contributed assets, while generating an RSS feed.
Exclude Keyword
A RSS feed can be created, based on a search that excludes assets with a specific keyword.
- The above searches for all assets, except for assets with a keyword of "school", while generating an RSS feed.
Exclude Specific Source Application
A RSS feed can be created, based on a search that excludes assets created by a specific application
example.com/search/?nsa=eedition
- The above searches for all assets, except for assets created by the eedition application.
NOTE: nsa=eedition is used by default on most search forms in BLOX to prevent assets created by the e-Edition application from showing up in regular searches.