Subversion Repositories web.active

<?php namespace ProcessWire;

/**
 * ProcessWire Markup RSS Module
 *
 * Given a PageArray of pages, this module will render an RSS feed from them. 
 * This is intended to be used directly from a template file. See usage below.
 *
 * USAGE
 * ~~~~~~
 * $rss = $modules->get('MarkupRSS'); 
 * $rss->setArray([ // specify RSS feed settings
 *   'title' => 'Latest updates',
 *   'description' => 'The most recent pages updated on my site',
 *   'itemTitleField' => 'title',
 *   'itemDateField' => 'created', // date field or 'created', 'published' or 'modified'
 *   'itemDescriptionField' => 'summary', 
 *   'itemDescriptionLength' => 1000, // truncate descriptions to this max length or 0 to allow HTML
 *   'itemContentField' => 'body', // optional HTML full-content, or omit to exclude
 *   'itemAuthorField' => 'author', // optional text or Page field containing author(s)
 * ]); 
 * $items = $pages->find('limit=10, sort=-modified'); // or any pages you want
 * $rss->render($items); 
 * exit; // exit now, or if you don’t then at least stop sending further output
 * ~~~~~~
 *
 * See also the $defaultConfigData below (first thing in the class) to see what
 * options you can change at runtime. 
 *
 * 
 * ProcessWire 3.x, Copyright 2023 by Ryan Cramer
 * https://processwire.com
 * 
 * @property string $title
 * @property string $url
 * @property string $description
 * @property string $xsl
 * @property string $css
 * @property string $copyright
 * @property int $ttl
 * @property string $itemTitleField
 * @property string $itemContentField
 * @property string $itemDateField
 * @property string $itemDescriptionField Field to use for item description.
 * @property string $itemDescriptionLength Max length for item description or 0 to allow HTML markup with any length (default=1024)
 * @property string $itemAuthorField 
 * @property string $itemAuthorElement
 * @property string $header
 * @property array|PageArray $feedPages
 * @property bool $stripTags Strip tags from item description? Applies only if `itemDescriptionLength>0`. (default=true)
 *
 *
 */

class MarkupRSS extends WireData implements Module, ConfigurableModule {
  
  /**
   * Return general info about the module for ProcessWire
   *
   */
  public static function getModuleInfo() {
    return array(
      'title' => 'Markup RSS Feed',
      'version' => 105,
      'summary' => 'Renders an RSS feed. Given a PageArray, renders an RSS feed of them.',
      'icon' => 'rss-square',
    );
  }

  protected static $defaultConfigData = array(
    'title' => 'Untitled RSS Feed',
    'url' => '', 
    'description' => '', 
    'xsl' => '', 
    'css' => '',
    'copyright' => '',
    'ttl' => 60,
    'stripTags' => true, 
    'itemTitleField' => 'title',
    'itemContentField' => '', // for <content:encoded>
    'itemDescriptionField' => 'summary',
    'itemDescriptionLength' => 1024, 
    'itemDateField' => 'created',
    'itemAuthorField' => '', // i.e. createdUser.title or leave blank to not use
    'itemAuthorElement' => 'dc:creator', // may be 'dc:creator' or 'author' (author if email address)
    'header' => 'Content-Type: application/xml; charset=utf-8;',
    'feedPages' => array(), 
  ); 

  /**
   * Set the default config data
   *
   */
  public function __construct() {
    parent::__construct();
    $this->setArray(self::$defaultConfigData);
  }

  /**
   * Module init
   *
   */
  public function init() { }

  /**
   * @param string $str
   * @return string
   * 
   */
  protected function ent1($str) {
    if(strpos($str, '&') !== false) $str = $this->wire()->sanitizer->unentities($str, true);
    return $this->ent($str);
  }

  /**
   * @param string $str
   * @return string
   * 
   *
   */
  protected function ent($str) {
    $str = htmlspecialchars($str, ENT_XML1 | ENT_QUOTES, 'UTF-8');
    $str = strtr($str, array(
      // https://validator.w3.org/feed/
      // recommends using hexadecimal entities here
      '&gt;' => '&#x0003E;',
      '&lt;' => '&#x0003C;',
      '&amp;' => '&#x00026;',
      '&quot;' => '&#x00022;',
      '&apos;' => '&#x00027;',
      '&#39;' => '&#x00027;',
    ));
    return $str;
  }

  /**
   * Render RSS header
   * 
   * @return string
   *
   */
  protected function renderHeader() {
    
    if(!$this->url) $this->url = $this->page->httpUrl;

    $xsl = $this->ent1($this->xsl); 
    $css = $this->ent1($this->css); 
    $title = $this->ent1($this->title);
    $url = $this->ent1($this->url);
    $description = $this->ent1($this->description);
    $pubDate = date(\DATE_RSS); 
    $ttl = (int) $this->ttl; 
    $copyright = $this->ent1($this->copyright);

    $out = '<?xml version="1.0" encoding="utf-8" ?>' . "\n";
    if($xsl) $out .= "<?xml-stylesheet type='text/xsl' href='$xsl' ?>\n";
    if($css) $out .= "<?xml-stylesheet type='text/css' href='$css' ?>\n";
    
    $xmlns = array(
      'xmlns:atom="http://www.w3.org/2005/Atom"',
      'xmlns:dc="http://purl.org/dc/elements/1.1/"'
    );
    if($this->itemContentField) {
      $xmlns[] = 'xmlns:content="http://purl.org/rss/1.0/modules/content/"';
    }
    $xmlns = implode(' ', $xmlns);
    
    $out .= 
      "<rss version=\"2.0\" $xmlns>\n" .
      "<channel>\n" .
      "\t<title>$title</title>\n" . 
      "\t<link>$url</link>\n" . 
      "\t<atom:link href=\"$url\" rel=\"self\" type=\"application/rss+xml\" />\n" . 
      "\t<description>$description</description>\n" . 
      "\t<pubDate>$pubDate</pubDate>\n";

    if($copyright) $out .= "\t<copyright>$copyright</copyright>\n";
    if($ttl) $out .= "\t<ttl>$ttl</ttl>\n";

    return $out; 
  }

  /**
   * Render individual RSS item
   * 
   * @param Page $page
   * @return string
   *
   */
  protected function renderItem(Page $page) {
    
    $sanitizer = $this->wire()->sanitizer;
    $title = strip_tags($page->get($this->itemTitleField));
    
    if(empty($title)) return '';
    
    $author = '';
    $description = '';
    $content = '';
    $pubDate = '';
    $title = $this->ent1($title);

    if($this->itemDateField && ($ts = $page->getUnformatted($this->itemDateField))) {
      // date
      $pubDate = "\t\t<pubDate>" . date(DATE_RSS, $ts) . "</pubDate>\n";
    }
  
    if($this->itemAuthorField) {
      // author
      $author = $page->get($this->itemAuthorField); 
      if($author instanceof Page) {
        $author = $author->get('title|name');
      } else if($author instanceof PageArray) {
        $author = $author->implode(', ', 'title');
      }
      $author = (string) $author;
      if(strlen($author)) {
        $author = $this->ent1($author); 
        $author = "\t\t<$this->itemAuthorElement>$author</$this->itemAuthorElement>\n"; 
      } else {
        $author = '';
      }
    }
    
    if($this->itemDescriptionField) {
      // description summary
      $description = $page->get($this->itemDescriptionField);
      if($description !== null) {
        if($this->itemDescriptionLength == 0) {
          // direct markup allowed in item description
          $description = $this->relativeToAbsoluteHtml($description, $page);
        } else {
          $description = $sanitizer->unentities($description, true);
          $description = $this->truncateDescription($description);
          $description = $this->ent($description);
        }
        $description = '<![CDATA[' . $description . ']]>';
      } else {
        $description = '';
      }
    }
    
    if($this->itemContentField) {
      // full HTML content, like that from CKEditor
      $content = (string) $page->get($this->itemContentField);
      $content = $this->relativeToAbsoluteHtml($content, $page);
      $content = "\t\t<content:encoded><![CDATA[" . $content . "]]></content:encoded>\n";
    }

    $out = 
      "\t<item>\n" .
      "\t\t<title>$title</title>\n" .
      "\t\t<description>$description</description>\n" .
      $pubDate . 
      $author . 
      $content . 
      "\t\t<link>$page->httpUrl</link>\n" .
      "\t\t<guid>$page->httpUrl</guid>\n" . 
      "\t</item>\n";

    return $out; 
  }

  /**
   * Render the feed and return it
   * 
   * @param PageArray|null $feedPages
   * @return string
   *
   */
  public function renderFeed(PageArray $feedPages = null) {

    if(!is_null($feedPages)) $this->feedPages = $feedPages;

    $out = $this->renderHeader();

    foreach($this->feedPages as $page) {
      if(!$page->viewable()) continue;
      $out .= $this->renderItem($page);
    }

    $out .= "</channel>\n</rss>\n";

    return $out; 
  }

  /**
   * Render the feed and echo it (with proper http header)
   * 
   * @param PageArray|null $feedPages
   * @return bool
   *
   */
  public function render(PageArray $feedPages = null) {
    header($this->header); 
    echo $this->renderFeed($feedPages);
    return true; 
  }

  /**
   * Truncate the description to a specific length and then truncate to avoid splitting any words.
   * 
   * @param string $str
   * @return string
   *
   */
  protected function truncateDescription($str) {

    $str = trim($str);
    $maxlen = $this->itemDescriptionLength;
    
    if(!$maxlen) return $str;

    if($this->stripTags) $str = strip_tags($str); 

    if(strlen($str) < $maxlen) return $str; 

    $str = trim(substr($str, 0, $maxlen)); 

    // boundaries that we can end the summary with
    $boundaries = array('. ', '? ', '! ', ', ', '; ', '-');
    $bestPos = 0;

    foreach($boundaries as $boundary) {
      if(($pos = strrpos($str, $boundary)) !== false) {
        // find the boundary that is furthest in string
        if($pos > $bestPos) $bestPos = $pos;
      }
    }

    // determine if we should truncate to last punctuation or last space.
    // if the last punctuation is further away then 1/4th the total length, then we'll 
    // truncate to the last space. Otherwise, we'll truncate to the last punctuation.
    $spacePos = strrpos($str, ' '); 
    if($spacePos > $bestPos && (($spacePos - ($maxlen / 4)) > $bestPos)) $bestPos = $spacePos; 

    if(!$bestPos) $bestPos = $maxlen;

    return trim(substr($str, 0, $bestPos+1)); 
  }
  
  /**
   * Update links and other references in HTML content to be suitable for RSS
   *
   * @param string $content
   * @param Page $page
   * @return string
   *
   */
  protected function relativeToAbsoluteHtml($content, Page $page) {

    $rootUrl = $this->wire()->config->urls->httpRoot;
    $pageUrl = $page->httpUrl();

    $a = array(
      ' href="/' => ' href="' . $rootUrl,
      " href='/" => " href='" . $rootUrl,
      ' src="/' => ' src="' . $rootUrl,
      " src='/" => " src='" . $rootUrl,
      ' href="#' => ' href="' . $pageUrl . '#',
      " href='#" => " href='" . $pageUrl . '#',
      '<![CDATA[' => '&lt;![CDATA[',
      ']]>' => ']]&gt;'
    );

    return str_replace(array_keys($a), array_values($a), $content);
  }

  /**
   * Provide fields for configuring this module
   * 
   * @param array $data
   * @return InputfieldWrapper
   *
   */
  public function getModuleConfigInputfields(array $data) {
  
    /** @var Modules $modules */
    $modules = $this->wire('modules');

    /** @var InputfieldWrapper $form */
    $form = $this->wire(new InputfieldWrapper());
    /** @var InputfieldFieldset $inputfields */
    $inputfields = $modules->get('InputfieldFieldset');
    $inputfields->attr('name', '_defaults');
    $inputfields->label = 'RSS feed defaults';
    $inputfields->icon = 'rss';
    $inputfields->description = 
      "Select the default options for any given feed. Each of these may be overridden in the API, " . 
      "so the options you select below should be considered defaults, unless you only have 1 feed. " . 
      "If you only need to support 1 feed, then you will not need to override any of these in the API.";
    $form->add($inputfields);

    foreach(self::$defaultConfigData as $key => $value) {
      if(!isset($data[$key])) $data[$key] = $value; 
    }

    /** @var InputfieldText $f */
    $f = $modules->get('InputfieldText');
    $f->attr('name', 'title');
    $f->attr('value', $data['title']);
    $f->label = "Feed title";
    $f->description = "The primary title of the RSS feed.";
    $f->columnWidth = 50;
    $inputfields->add($f);

    /** @var InputfieldURL $f */
    $f = $modules->get('InputfieldURL');
    $f->attr('name', 'url');
    $f->attr('value', $data['url']);
    $f->label = "Feed URL";
    $f->description = "Optional URL on your site that serves as a feed index.";
    $f->columnWidth = 50;
    $inputfields->add($f);

    /** @var InputfieldText $f */
    $f = $modules->get('InputfieldText');
    $f->attr('name', 'description');
    $f->attr('value', $data['description']);
    $f->label = "Feed description";
    $f->description = "Optional default description for a feed.";
    $f->columnWidth = 50;
    $inputfields->add($f);

    /** @var InputfieldURL $f */
    $f = $modules->get('InputfieldURL');
    $f->attr('name', 'xsl');
    $f->attr('value', $data['xsl']);
    $f->label = "Link to XSL stylesheet";
    $f->description = "Optional URL/link to an XSL stylesheet.";
    $f->columnWidth = 50;
    $inputfields->add($f);

    /** @var InputfieldURL $f */
    $f = $modules->get('InputfieldURL');
    $f->attr('name', 'css');
    $f->attr('value', $data['css']);
    $f->label = "Link to CSS stylesheet";
    $f->description = "Optional URL/link to a CSS stylesheet.";
    $f->columnWidth = 50;
    $inputfields->add($f);

    /** @var InputfieldText $f */
    $f = $modules->get('InputfieldText');
    $f->attr('name', 'copyright');
    $f->attr('value', $data['copyright']);
    $f->label = "Feed copyright";
    $f->description = "Optional default copyright statement for a feed.";
    $f->columnWidth = 50;
    $inputfields->add($f);

    /** @var InputfieldSelect $f3 */
    $f3 = $modules->get('InputfieldSelect');
    $f3->attr('name', 'itemDateField');
    $f3->attr('value', $data['itemDateField']);
    $f3->label = "Feed item date field";
    $f3->description = "The default field to use as an individual feed item's date.";
    $f3->addOption('created');
    $f3->addOption('modified');
    $f3->addOption('published');
    $f3->columnWidth = 50;

    /** @var InputfieldSelect $f1 */
    $f1 = $modules->get('InputfieldSelect');
    $f1->attr('name', 'itemTitleField');
    $f1->attr('value', $data['itemTitleField']);
    $f1->label = "Feed item title field";
    $f1->description = "The default field to use as an individual feed item's title.";
    $f1->columnWidth = 50;

    /** @var InputfieldSelect $f2 */
    $f2 = $modules->get('InputfieldSelect');
    $f2->attr('name', 'itemDescriptionField');
    $f2->attr('value', $data['itemDescriptionField']);
    $f2->label = "Feed item description field";
    $f2->columnWidth = 50;
    $f2->description = "The default field to use as an individual feed item's description (typically a summary or body field). Note that HTML will be stripped out.";

    /** @var InputfieldInteger $f2a */
    $f2a = $modules->get('InputfieldInteger');
    $f2a->attr('name', 'itemDescriptionLength');
    $f2a->attr('value', (int) $data['itemDescriptionLength']);
    $f2a->label = "Maximum characters for item description field";
    $f2a->columnWidth = 50;
    $f2a->description = "The item description will be truncated to be no longer than the max length. When greater than 0, HTML tags will be removed or encoded.";
    $f2a->notes = "Specify `0` for no max length AND to allow HTML in the description.";

    /** @var InputfieldSelect $f4 */
    $f4 = $modules->get('InputfieldSelect');
    $f4->attr('name', 'itemContentField');
    $f4->attr('value', $data['itemContentField']);
    $f4->label = "HTML content/body field";
    $f4->description = "Optional field that contains the entire article/bodycopy in HTML. Select only if you intend to include the entire content in the RSS feed, otherwise use just the description field.";
    $f4->columnWidth = 50;

    /** @var InputfieldInteger $ttl */
    $ttl = $modules->get('InputfieldInteger');
    $ttl->attr('name', 'ttl');
    $ttl->attr('value', (int) $data['ttl']);
    $ttl->label = "Feed TTL";
    $ttl->description = "TTL stands for \"time to live\" in minutes. It indicates how long a channel can be cached before refreshing from the source. Default is 60.";
    $ttl->columnWidth = 50;

    foreach($this->wire()->fields as $field) {
      $fieldtype = $field->type; 

      if($fieldtype instanceof FieldtypeTextarea) {
        $f2->addOption($field->name); 
        $f4->addOption($field->name); 
        
      } else if($fieldtype instanceof FieldtypeText) {
        $f1->addOption($field->name); 
        $f2->addOption($field->name); 
        
      } else if($fieldtype instanceof FieldtypeDatetime) {
        $f3->addOption($field->name); 
      }
    }

    $inputfields->add($f1);
    $inputfields->add($f3);
    $inputfields->add($f2);
    $inputfields->add($f2a);
    $inputfields->add($f4);
    $inputfields->add($ttl);

    return $form;

  }

}