Documentation

RSS

The RSS is the format developed for the exchange of information (mainly news) between sites. The RSS format is built on the XML specification. You can obtain the detailed information on the RSS 2.0 format here: http://backend.userland.com/rss.

Terms used

Channel
Information block in the RSS format.
Server site
It's a site that exports (transmits) information in the RSS format.
Client site
It's a site that imports (receives) information in the RSS format.
Caching
This means the temporary storage of information obtained from a server site, on a client site, to accelerate repeated access to it.
Channel node
Element of an information block e.g. news or product in the RSS format.

Export to the RSS

There are three ways to export the information block content to the RSS format.

Dynamic ("on-the-fly") generation of an RSS file upon the client site request

To enable this method, check the box Allow dynamic RSS export in the information block settings, and set the amount of time after which a client site will have to re-request information from a server site in the field Valid (hours) (during this period a client site will use the cached information).

The access to an RSS file comes to requesting the file /bitrix/rss.php from a server site with parameters ID, LANG, TYPE and LIMIT in the URL.

Request parameters
ParameterDescription
IDInformation block ID, or the symbolic code of the section.
LANG Site of the information block.
TYPE Type of the information block.
LIMIT Maximum number of information block elements to export.

Sample request

http://www.bitrixsoft.com/bitrix/rss.php?ID=3&LANG=ru&TYPE=news&LIMIT=3

Pregeneration of an RSS file

Enabling this method requires checking the flag Allow export to RSS file in the information block settings and set the fields Number of exported elements (limits the maximum number of elements exported to a file; set to -1 to remove restrictions) and Export last days (restricts the exported elements to those dated and active within the specified number of days; set to -1 to remove restrictions).

The RSS file is generated repeatedly at intervals specified in the field Valid (hours) and saved to a file with the name like iblock_rss_<block ID>.xml to the folder specified in the module settings.

To access the RSS file, a client site requests the file http://<server site>/<folder specified in the module settings>/iblock_rss_<block ID>.xml.

Sample request
http://www.bitrixsoft.com/upload/iblock_rss_3.xml

RSS channel element structure

By default, the node <item> is built as follows:


<item>
  <title>Field "Name of information block element"</title>
  <link>Field "Detailed view page URL"</link>
  <description>Field "Brief description" of an information block element. 
               If this field is empty, the field "Full description" is used.</description>
  <pubDate>Field "Active period" of the information block.</pubDate>
  <enclosure url="URL of an image loaded in the field "Brief description" of an information block element"
             length="Size of the image file" 
             type="Type of the image file" 
             width="Width of an image" 
             height="Height of an image"/>
</item>

You can alter the generation parameters on the information block editing page, section RSS export fields assignment. The RSS fields can have any text values. Besides that, use of parameter templates is permitted. Parameters should be specified in the form of #NAME#. Parameter names can be the property codes as well as the following values:

  • NAME - title of an information block element;
  • DETAIL_PAGE_URL - address of a page containing detailed view of an element;
  • PREVIEW_TEXT - brief description;
  • DETAIL_TEXT - detailed description;
  • ACTIVE_FROM - start of the active period.

Import from the RSS

To receive the information, a client site should call the method CIBlockRSS::GetNewsEx. The method GetNews is also supported but is now obsolete and is not recommended.

array
CIBlockRSS::GetNewsEx(
 SITE, 
 PORT, 
 PATH, 
 QUERY_STR
);

The method returns a channel from the cache (if it is not expired) or from a server site.

Request parameters

ParameterDescription
SITEAddress of a server site. For example, "www.bitrixsoft.com".
PORT Port of a server site. For example, 80.
PATH Path to the RSS file on the server site. For example, "/bitrix/rss.php".
QUERY_STR Query string (if required). For example, ID=3&LANG=ru&TYPE=news&LIMIT=5. Please note that the query string should conform the HTTP specification.

Return value

The function returns an array with the information from the requested RSS file.

Samples


<?
CModule::IncludeModule("iblock");
$arRes = CIBlockRSS::GetNewsEx("www.bitrix.com", 
                               80, "/bitrix/rss.php", 
                               "ID=3&LANG=ru&TYPE=news&LIMIT=5");
$arRes = CIBlockRSS::FormatArray($arRes);

echo $arRes["title"];          // Title of a channel or block
echo $arRes["link"];           // Server site URL
echo $arRes["description"];    // Description of a channel or block
echo $arRes["lastBuildDate"];  // File timestamp on the server site
echo $arRes["ttl"];            // Time-to-live

echo $arRes["image"]["title"];   // Image title if present
echo $arRes["image"]["url"];     // Link to the image file if present
echo $arRes["image"]["width"];   // Width of the image file if present
echo $arRes["image"]["height"];  // Height of the image file if present

echo $arRes["item"][0]["title"];       // Title of the first news
echo $arRes["item"][1]["title"];       // Title of the second news
echo $arRes["item"][1]["link"];        // Link to the second news
echo $arRes["item"][1]["description"]; // Description of the second news
echo $arRes["item"][1]["pubDate"];     // Date of the second news publication
echo $arRes["item"][1]["enclosure"]["url"];     // Link to the second news attachment
echo $arRes["item"][1]["enclosure"]["length"];  // Size of the second news attachment file
echo $arRes["item"][1]["enclosure"]["type"];    // MIME-type of the second news attachment
echo $arRes["item"][1]["enclosure"]["width"];   // Width of the second news enclosed image
echo $arRes["item"][1]["enclosure"]["height"];  // Height of the second news enclosed image

?>

<?
CModule::IncludeModule("iblock");
$arRes = CIBlockRSS::GetNewsEx("www.bitrixsoft.com", 
                               80, "/bitrix/rss.php", 
                               "ID=demo&LANG=en&TYPE=news&LIMIT=5");
$arRes = CIBlockRSS::FormatArray($arRes);
?>
<b><?echo $arRes["title"] ?></b><br>

<table cellpadding="2" cellspacing="0" border="0" width="80%">
  <?for ($i = 0; $i < count($arRes["item"]); $i++):?>
  <tr>
    <td width="100%">
      <font class="date">
        <?echo $arRes["item"][$i]["pubDate"]?>
      </font>&nbsp;|&nbsp;
      <?if (strlen($arRes["item"][$i]["link"])>0):?>
        <a href="<?echo $arRes["item"][$i]["link"]?>" class="title">
      <?endif;?>
      <?echo $arRes["item"][$i]["title"]?>
      <?if (strlen($arRes["item"][$i]["link"])>0):?>
        </a>
      <?endif;?>
      <br>
    </td>
  </tr>
  <tr>
    <td valign="top" width="100%">
      <?if (strlen($arRes["item"][$i]["enclosure"]["url"])>0):?>
        <table cellpadding="0" cellspacing="0" border="0" align="left">
          <tr>
            <td valign="top">
              <img 
               src="<?echo $arRes["item"][$i]["enclosure"]["url"] ?>" 
               width="<?echo $arRes["item"][$i]["enclosure"]["width"] ?>" 
               height="<?echo $arRes["item"][$i]["enclosure"]["height"]?>" 
               border="0">
            </td>
          </tr>
        </table>
      <?endif;?>
      <font class="text">
        <?echo $arRes["item"][$i]["description"];?>
        <br>
      </font>
    </td>
  </tr>
  <?endfor;?>
</table>

© «Bitrix24», 2001-2024
Up