Table of Contents

Overview

This document describes the steps necessary to create the different types of feeds (RSS, MRSS, ATOM, etc.) to use when syndicating content. 

URL Parameters


NOTE: The options listed below apply to RSS, MRSS, ATOM and iATOM, unless otherwise noted.


To Set Up Any Feed

You can edit this example URL:

http://your_domain.com/search/?q=city+hall+fire&nsa=eedition&t=&l=100&s=&sd=desc&f=rss&d=&d1=&d2=

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
    • pdf
    • 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


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.



NOTE: If you are using hours you need to add the parameter &xd=1.

Example: http://www.example.com/search/?c[]=news&d=on&d1=48+hours+ago&xd=1


To Generate an RSS Feed (Zen)

&f=rss tells the system to generate an RSS feed.

http://your_domain.bloxcms.com/search/?q=&nsa=eedition&t=&l=100&s=&sd=desc&f=rss

By default, RSS will only include the headline and first paragraph.

To include ONLY the headline, add &altf=headonly to the url.

http://your_domain.bloxcms.com/search/?q=&nsa=eedition&t=&l=100&s=&sd=desc&f=rss&altf=headonly

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:

  1. In Settings / Site select 'Custom Properties'.
  2. Click Add to create a new custom property. 
  3. In the Name field, enter passphrase. In the Value field, enter any random passphrase (this will be used in the URL).
  4. Save these changes.
  5. 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.


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. 

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: 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
  •  
  • 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/?bl=1234&1=25"a>More items from block</a>

Note:  This parameter will return search results for Editorial, Community, and Marketplace applications.


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.

http://your_domain.com/search/?q=&nsa=eedition&t=&l=100&s=&sd=desc&f=atom&altf=mrss

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.

http://your_domain.com/search/?q=&nsa=eedition&t=&l=100&s=&sd=desc&f=atom&altf=mrss&ips=300

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.

http://www.example.bloxcms.com/search/?q=&nsa=eedition&t=&l=100&s=&sd=desc&f=atom&altf=mrss&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:

  1. In Settings / Site select 'Custom Properties'.
  2. Click Add to create a new custom property. 
  3. In the Name field, enter passphrase. In the Value field, enter any random passphrase (this will be used in the URL).
  4. Save these changes.
  5. 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.

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.

https://www.example.com/podcasts/tigers/?sd=desc&amp;l=100&amp;nsa=eedition&amp;t=audio&amp;f=rss&amp;altf=itunes

To Generate an ATOM Feed

&f=atom tells the system to generate an ATOM feed.

http://yourdomain.com/search/?q=&nsa=eedition&t=&l=100&s=&sd=desc&f=atom

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"/>

To Generate an iATOM Feed

&f=atom&altf=iatom tells the system to generate an iATOM feed.

http://yourdomain.com/search/?q=&nsa=eedition&t=&l=100&s=&sd=desc&f=atom&altf=iatom

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:

http://example.com/search/?q=&t=article&l=100&d=&date-selector=on&d1=24+hours+ago&d2=&s=start_time&f=atom&altf=iatom

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"

Using Search on your Blox CMS website

Another way to generate an RSS or ATOM feed is through the search page in your Zen website. Usually located at http://your_domain.com/search.  Your search page should have a box that looks like this:

+2 
rss search

Click the Advanced Search Options button to view additional search options.

+2 
rss advanced search

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. From the Format dropdown select either RSS or ATOM depending on which type of feed you want to build. Hitting Search will generate the page based on your specifications. The url of your page will look something like this:

http://www.training.bloxcms.com/search/?q=Cubs&nsa=eedition&t=&l=10&s=&sd=desc&f=atom&d=&d1=&d2=

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. For more on Search Queries visit: Search Queries

'Fulltext' option

There is a method for creating an Atom feed that provides the full text of articles. This requires an extended URL using a matching passphrase created in the BLOX admin.

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).

https://your_domain.bloxcms.com/search/?q=&nsa=eedition&t=&l=100&s=&sd=desc&f=rss

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 work, the site's HTTPS setting must be set to "Do nothing"


+2 
Site settings

To Generate a Verve Feed (Flex)

 &f=rss&altf=verve_full tells the system to generate a Verve feed. 

http://www.yourdomain.com/search/q="test"&nsa=eedition&t=&l=5&s=&sd=desc&f=rss&altf=verve_full

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.

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

To Generate a Whiz feed

Adding &altf=whiz will allow you to send your stories up to Whiz. 

https://your_domain.bloxcms.com/search?f=rss&altf=whiz

Overview

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.

Examples

Example 1

example.com/search/?q=fire&amp;c[]=news

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

https://www.example.com/search/?c=news

An asterisk can be used for wildcard searching, which is useful to search all subcategories:

https://www.example.com/search/?c=news*

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: 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 

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/?bl=1234&1=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.


http://www.example.com/search/?f=rss&amp;fl=top_story

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"


NOTE: If you are using hours you need to add the parameter &xd=1.

Example: http://www.example.com/search/?c[]=news&d=on&d1=48+hours+ago&xd=1


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.  

Byline

This will search the byline field for the string provided

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:

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.

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.

Exclude Keyword

A RSS feed can be created, based on a search that excludes assets with a specific keyword.

Exclude Specific Source Application

A RSS feed can be created, based on a search that excludes assets created by a specific 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.