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
| Parameter | Description |
|---|---|
| ID | Information 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
| Parameter | Description |
|---|---|
| SITE | Address 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> |
<?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>