Newscoop 3 Cookbook

List articles and article related content

List of Articles

Purpose:

Select the list of articles according to the given constraints and current environmental variables. The publication, language, issue, section and article variables may not be defined outside the list_articles statement; inside the statement however, all these variables are defined. The code between "{{ list_articles }}" statement "{{ /list_articles }}" is repeated for every article in the list.

Syntax:

{{ list_articles [length="<integer_value>"]
        [columns="<integer_value>"]
        [constraints="<list_of_article_constraints>"]
        [ignore_publication="true"]
        [ignore_issue="true"]
        [ignore_section="true"]
        [ignore_language="true"]
        [location="<longitude, latitude>]
        [order="<order_condition>"] }}
    <list_of_instructions>
{{ /list_articles }}

Filters:

  • length="<integer_value>": <integer_value> specifies list_length and forces the list to have at most list_length items. If the list contains more items than list_length items the interval of elements to be displayed can be switched using has_previous_elements and has_next_elements from the current_list object
  • columns="<integer_value>": <integer_value> specifies columns_number and sets an environment variable. This is incremented as if the items were placed in a table cell. The counting starts from one and the variable is incremented for every new element. When it reaches the maximum value it is reset to one. This is very useful in building tables of data. For details see current list
{{ list_articles length="10" columns="2" order="byPublishDate desc"}}
{{ if $gimme->current_list->column == "1" }}
left column
{{ /if }}
{{ /list_articles }}
  • ignore_publication: list articles from all publications, not only from the environment publication
  • ignore_issue: list articles from all issues, not only from the environment issue; if the section was defined it will list only articles from the environment section
  • ignore_section: list articles from all sections, not only from the environment section
  • ignore_language: list articles in all languages; if the issue and section were defined in the environment it lists only articles belonging to the environment issue/section
  • location: longitude and latitude values for the location

<list_of_instructions> may contain any statement except those listed at the end of the page.

  • <list_of_article_constraints>=
    • <article_constraint> <list_of_article_constraints>
    • <article_constraint>
  • <article_constraint>=
  • name <string_operator> <string_value>
  • number <integer_operator> <integer_value>
  • keyword <string_value>
  • OnFrontPage <switoperator> <switvalue>
  • OnSection [<switoperator> <switvalue>]
  • upload_date <date_operator> <date_value>
  • publish_date <date_operator> <date_value>
  • public <switoperator> <switvalue>
  • type <switoperator> <article_type>
  • <article_type> <article_type_attribute> <attribute_type_operator> <attribute_type_value>
  • matchAllTopics
  • matchAnyTopic
  • topic is|not <string_value>
  • reads <integer_operator> <integer_value>
  • author <string_operator> <string_value>
  • issue <integer_operator> <integer_value>
  • section <integer_operator> <integer_value>

Examples:

Taken from Template Pack "The Custodian" (date 2011-03-16) file "article.tpl"

{{ list_articles name="topic_articles"
constraints="number not `$gimme->article->number`
`$topic_cond` matchAnyTopic"  ignore_issue=true length=3 }}
  {{ include file="classic/tpl/teaserframe_articlelistright.tpl"
}}
  {{ include file="classic/tpl/pagination.tpl" }}
  {{ assign var="number_cond" value="`$number_cond`
number not `$gimme->article->number` " }}
{{ /list_articles }}

Examples of constraints:

constraints="issue greater 10 issue smaller 20"

constraints="section greater_equal 40 section smaller 60"

  • name, number, upload_date, publish_date are self-explanatory article attributes
  • keyword: all articles containing the specified keyword (and respecting all the other constraints) will be in the list
  • OnFrontPage: articles having "Show article on front page" flag in <switoperator> relation with <switvalue> will be selected; for details see Creating articles within a section
  • OnSection: articles having "Show article on section page" flag in <switoperator> relation with <switvalue> will be selected; for details see Creating articles within a section
  • public: articles having "Allow users without subscription..." flag in <switoperator> relation with <switvalue> will be selected
  • type: only articles having the given time will be selected
  • ... <article_type_attribute> ...: articles being of <article_type> and having <article_type_attribute> in <attribute_type_operator> relation with <attribute_type_value> will be selected; for details see "Article Types"
  • matchAllTopics/matchAnyTopic: defines the behaviour of the list when matching articles topics against the list of topics given as parameters:
    • matchAllTopics will force the selection of articles that have all the given topics
    • matchAnyTopic (default) will select articles that have at least one topic from the given topic list
  • topic: if "is" operator is used, articles having specified topic in their list of topics will be selected; if "not" operator is uses articles not having specified topic in their list of topics will be selected
  • reads: you can set constraints based on the number of readers that viewed this article since it was published
  • author: you can list articles that have or don't have a certain author; e.g.: "author is John\ Doe" (the backslash is needed to escape the space character - see Language Elements; Conventions at the bottom of the page). The author attribute has a predefined value "__current"; when using this value the author will be filled in from the currently defined article. For example: "author is __current"

Note on author attribute: this works only in Newscoop 3.2.1 and newer versions.

Note on topics: the topic name must be written in the following format: <topic_name>:<language_code>

Examples of valid topic names:

sports:en

health:en

Note on topics: If a certain topic was defined in the template environment by use of the "set_topic" statement or URL parameter the list will change the behaviour of the articles list. Only articles having that topic will be listed. For example:

{{ set_topic name="test:en" }}
{{ list_articles }}
...
{{ /list_articles }}

This will list only articles having the topic 'test'. The topic is automatically appended to the URL parameters so you don't have to set the topic in the current page.

  • <order_condition>=
    • byNumber desc|asc
    • byName desc|asc
    • byDate desc|asc
    • byCreationDate desc|asc
    • byPublishDate desc|asc
    • byLastUpdate desc|asc
    • byPopularity desc|asc
    • byPublication desc|asc
    • byIssue desc|asc
    • bySection desc|asc
    • byLanguage desc|asc
    • bySectionOrder desc|asc
    • byComments desc|asc
    • byLastComment desc|asc
  • byComments instructs the Newscoop to list articles by the number of comments filed to each article
  • byLastComment will list articles ordered by the last article comment time
  • byDate is an alias of byCreationDate
  • The other order conditions are self-explanatory
  • The default order of articles in the list (if no order condition was set) is: first they are ordered by the issue number descending, then by the section number ascending and by the article order in the section ascending

Note: byComments and byLastComment only work in Newscoop 3.2.2 and newer. byLastUpdate is implemented in Newscoop 3.5 and newer.

Inside the list the data context is defined by the constraints applied to the current article for every processed line. The data context is restored after the list processing.

Constraints:

Inside list_articles the following statements are forbidden:

  • list_languages
  • set_language
  • set_default_language
  • unset_language
  • set_publication
  • set_default_publication
  • unset_publication
  • list_issues
  • set_issue
  • set_default_issue
  • set_current_issue
  • unset_issue
  • list_sections
  • set_section
  • set_default_section
  • unset_section
  • list_articles
  • set_article
  • set_default_article
  • unset_article

list_articles statement cannot be used inside list_subtitles, or list_searresults statements.

List of Article Attachments

Purpose:

Create a list of documents attached to the article currently defined in the template environment. If the article was not set the list is empty. The code between "{{ list_article_attachments }}" statement and "{{ /list_article_attachments }} is repeated for every attachment in the list.

Syntax:

{{ list_article_attachments [length="<integer_value>"]
                            [columns="<integer_value>"]
                            [language="current"] }}
   <list_of_instructions>
{{ /list_article_attachments }}

Filters:

  • all_languages: if true (default) the list will contain all article attachments independent of their language; if false, the list will contain only article attachments that have the language currently defined by the template environment
  • length="<integer_value>": <integer_value> specifies list_length and forces the list to have at most list_length items. If the list contains more items than list_length items the interval of elements to be displayed can be switched using has_previous_elements and has_next_elements from the current_list object
  • columns="<integer_value>": <integer_value> specifies columns_number and sets an environment variable. This is incremented as if the items were placed in a table cell. The counting starts from one and the variable is incremented for every new element. When it reaches the maximum value it is reset to one. This is very useful in building tables of data. For details see current_list
  • language="current": list only attachments that were set as available for all translations and available for the language currently set in the template environment

Inside list_articles the following statements are forbidden:

  • set_language
  • set_default_language
  • unset_language
  • set_publication
  • set_default_publication
  • unset_publication
  • list_issues
  • set_issue
  • set_default_issue
  • set_current_issue
  • unset_issue
  • list_sections
  • set_section
  • set_default_section
  • unset_section
  • list_articles
  • set_article
  • set_default_article
  • unset_article
  • list_article_attachments

Inside the list, the current article attachment is set to the current element of the list. The environment context is restored after the list processing.

Example:

{{ list_article_attachments }}
 {{ if $gimme->current_list->at_beginning }}
  <h4>Downloads:</h4>
 {{ /if }}
  <a href="/attachment/{{ $gimme->attachment->identifier }}">
   {{ $gimme->attachment->file_name }}</a>
  ({{ $gimme->attachment->size_kb }}kb)<br/>
{{ /list_article_attachments }}

Here is an example of how to use the attachment list to play a number of MP3 files:

{{ list_article_attachments }}
 {{ if $gimme->attachment->extension == "mp3" }}
<object type="application/x-shockwave-flash"
data="/templates/radioactive/apps/player_mp3_maxi.swf" width="200" height="20">
<param name="movie" value="/templates/radioactive/apps/player_mp3_maxi.swf" />
<param name="bgcolor" value="#444444"/>
<param name="FlashVars" value="mp3={{ uri options="articleattachment" }}" />
<!-- player home: http://flash-mp3-player.net/ -->
</object>
 {{ /if }}
{{ /list_article_attachments }}

List of Article Authors

Note: this works only in Newscoop 3.5.0 and newer versions.

Purpose:

Create the list of authors to the article currently defined in the template environment. If the article was not defined, the list is empty. The code between the "{{ list_article_authors }}" statement and "{{ /list_article_authors }} is repeated for every author in the list. Inside the list every author is represented by an author object, (see "Author").

Syntax:

{{ list_article_authors [length="<integer_value>"]
                        [columns="<integer_value>"]
                        [order="<author_order>"] }}
   <list_of_instructions>
{{ /list_article_authors }}

Filters:

  • length="<integer_value>": <integer_value> specifies list_length and forces the list to have at most list_length items. If the list contains more items than list_length items the interval of elements to be displayed can be switched using has_previous_elements and has_next_elements from the current_list object
  • columns="<integer_value>": <integer_value> specifies columns_number and sets an environment variable. This is incremented as if the items were placed in a table cell. The counting starts from one and the variable is incremented for every new element. When it reaches the maximum value it is reset to one. This is very useful in building tables of data. For details see current_list.
  • order="<author_order>"=
    • byFirstName: order by the author's first name
    • byLastName: order by the author's last name

Example:

Taken from Template Pack "The Journal" (date 2011-03-15) file "article-author-popup.tpl"

{{ list_article_authors }}
 <div id="hidden{{ $gimme->current_list->index }}Content"  class="teammemberinfo" style="display:none">
  <img style="width: 150px; float: left; margin: 0 10px 10px 0"
  src="{{ $gimme->author->picture->imageurl }}" />
   <h2>{{ $gimme->author->name }}</h2>
    <div class="text">
    {{ $gimme->author->biography->text }}
    </div>
</div>
{{ /list_article_authors }}

Inside list_articles the following statements are forbidden:

  • set_language
  • set_default_language
  • unset_language
  • set_publication
  • set_default_publication
  • unset_publication
  • list_issues
  • set_issue
  • set_default_issue
  • set_current_issue
  • unset_issue
  • list_sections
  • set_section
  • set_default_section
  • unset_section
  • list_articles
  • set_article
  • set_default_article
  • unset_article
  • list_article_images

Inside the list, the current author is set to the current element of the list. The environment context is restored after the list processing.

List of Article Comments

Purpose:

Create a list of comments attached to the article currently defined in the template environment. If the article was not defined the comments list is empty. The code between the "{{ list_article_comments }}" statement and "{{ /list_article_commnets }}" is repeated for every comment in the list.

Syntax:

{{ list_article_comments [ignore_language="true|false"]
                         [ignore_article="true|false"]
                         [length="<integer_value>"]
                         [columns="<integer_value>"]
                         [order="<order_condition>"] }}
   <list_of_instructions>
{{ /list_article_comments }}

Filters:

  • ignore_language: list comments regardless of the comment language
  • ignore_article: list comments for all articles, not only for the current article
  • length="<integer_value>": <integer_value> specifies list_length and forces the list to have at most list_length items. If the list contains more items than list_length items the interval of elements to be displayed can be switched using has_previous_elements and has_next_elements from the current_list object.
  • columns="<integer_value>": <integer_value> specifies columns_number and sets an environment variable. This is incremented as if the items were placed in a table cell. The counting starts from one and the variable is incremented for every new element. When it reaches the maximum value it is reset to one. This is very useful in building tables of data. For details see current_list.

Note on ignore_article: this option will force the list order to date ordering. ignore_language and ignore_article only work in Newscoop 3.2.2 and newer.

  • <order_condition>=
    • byDate desc|asc
    • default desc|asc

The default order of the comments in the list (if no order condition was specified) is based on the tree structure of the comments as in the following example:

  • root comment 1
    • reply 1 (parent is root comment 1)
      • reply 1_1 (parent is reply 1)
  • root comment 2
  • ...

The first element in the list is the first comment that was submitted, second is it's first reply (if it exists), first reply of the first reply .. and so on down the tree structure, until it finds no other reply, second reply to the root element etc.

If the order by date condition was specified the comments are displayed strictly by their submission date, regardless of the relation they had to the other comments.

Example:

{{ list_article_comments order="byDate desc" }}
    Subject: {{ $gimme->comment->subject }}<br/>
    Posted {{ $gimme->comment->submit_date }}
    by <b>{{ $gimme->comment->reader_email }}</b>
    <br/>
    {{ $gimme->comment->content }}
    <br/>
{{ /list_article_comments }}

The following example is taken from the Template Pack "The Custodian" (2011-03-16) file "comments.tlp"

{{ list_article_comments }}
{{ if $gimme->current_list->at_beginning }}
 <a name="commentlist">
  <h4>
  {{ if $gimme->language->name == "English" }}Previous comments
  {{ else }}Los comentarios anteriores
  {{ /if }}
  </h4>
 </a>
{{ /if }}
 <div class="comment" {{ if $gimme->current_list->at_end }}
  id="everlast"{{ /if }}>
   <p><strong>{{ $gimme->comment->nickname }}</strong><br>
   {{ $gimme->comment->content }}</p>
    <p>
     <em>
      {{ $gimme->comment->subject }} |
      <span>{{ $gimme->comment->submit_date|camp_date_format:"%M
      %e, %Y" }}</span>
     </em>
    </p>
 </div>
<!-- /.comment -->
{{ /list_article_comments }}

Inside list_articles the following statements are forbidden:

  • set_language
  • set_default_language
  • unset_language
  • set_publication
  • set_default_publication
  • unset_publication
  • list_issues
  • set_issue
  • set_default_issue
  • set_current_issue
  • unset_issue
  • list_sections
  • set_section
  • set_default_section
  • unset_section
  • list_articles
  • set_article
  • set_default_article
  • unset_article
  • list_article_comments

List of Article Images

Purpose:

Create a list of images attached to the article currently defined in the template environment. If the article was not defined, the list is empty. The code between the "{{ list_article_images }}" statement and "{{ /list_article_images }} is repeated for every image in the list.

Syntax:

{{ list_article_images [length="<integer_value>"]
                       [columns="<integer_value>"]
                       [order="<image_order>"] }}
   <list_of_instructions>
{{ /list_article_images }}

Filters:

  • length="<integer_value>": <integer_value> specifies list_length and forces the list to have at most list_length items. If the list contains more items than list_length items the interval of elements to be displayed can be switched using has_previous_elements and has_next_elements from the current_list object
  • columns="<integer_value>": <integer_value> specifies columns_number and sets an environment variable. This is incremented as if the items were placed in a table cell. The counting starts from one and the variable is incremented for every new element. When it reaches the maximum value it is reset to one. This is very useful in building tables of data. For details see current_list.
  • order="<image_order>"=
  • default, number: order by the number assigned to the image when attached to an article
  • byDescription: order by the image description
  • byPhotographer: order by the photographer name
  • byDate: order by the image date
  • byLastUpdate: order by the image last update time

Example:

Taken from Template Pack "The Custodian" (date 2011-03-15) file "article-gallery.tpl"

{{ list_article_images }}
 {{ if $gimme->current_list->count gt 1 }}
  {{ if $gimme->current_list->at_beginning }}
   <div id="article-gallery">
    <h4>{{ if $gimme->language->name == "English" }}Article gallery
        {{ else }}Mini galera{{ /if }}:
    </h4>
  {{ /if }}
     <div class="gallery-item">
      <a class="grouped_elements"
       href="{{ $gimme->article->image->imageurl }}" rel="group">
       <img alt="{{ $gimme->article->image->description }}"
       src="{{ $gimme->article->image->thumbnailurl }}" />
      </a>
     </div><!-- /.gallery-item -->
   {{ if $gimme->current_list->at_end }}
   </div><!-- /#article-gallery -->
   {{ /if }}
 {{ /if }}
{{ /list_article_images }}

Inside list_articles the following statements are forbidden:

  • set_language
  • set_default_language
  • unset_language
  • set_publication
  • set_default_publication
  • unset_publication
  • list_issues
  • set_issue
  • set_default_issue
  • set_current_issue
  • unset_issue
  • list_sections
  • set_section
  • set_default_section
  • unset_section
  • list_articles
  • set_article
  • set_default_article
  • unset_article
  • list_article_images

Inside the list, the current image is set to the current element of the list. The environment context is restored after the list processing.

List of Article Locations

Note: this works only in Newscoop 3.5.0 and newer versions.

Maps require jQuery: In order to use display maps you must include jQuery in the header of your document, with a link like this:

<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1/jquery.min.js">

Purpose:

Create a list of map locations related to the article currently defined in the template environment. If the article was not defined, the list is empty. The code between the "{{ list_article_locations }}" statement and "{{ /list_article_locations }} is repeated for every location in the list. Inside the list every location is represented by a map location object, (see "Article Location").

Syntax:

{{ list_article_locations [length="<integer_value>"]
                          [columns="<integer_value>"] }}
   <list_of_instructions>
{{ /list_article_images }}

Filters:

  • length="<integer_value>": <integer_value> specifies list_length and forces the list to have at most list_length items. If the list contains more items than list_length items the intervals of elements to be displayed can be switched using has_previous_elements and has_next_elements from the current_list object
  • columns="<integer_value>": <integer_value> specifies columns_number and sets an environment variable. This is incremented as if the items were placed in a table cell. The counting starts from one and the variable is incremented for every new element. When it reaches the maximum value it is reset to one. This is very useful in building tables of data. For details see current_list.

Example:

Ushahidi compatible KML format. You can use this as a feed to call as a layer in Ushahidi:

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://earth.google.com/kml/2.2">
<Document>
  <name>{{ $gimme->publication->name }}</name>
  <description><![CDATA[ .]]></description>
{{ list_articles}}
  {{ list_article_locations }}
    {{ if $gimme->location->enabled }}
  <Style id="style{{ $gimme->article->number }}-{{ $gimme->current_list->index }}">
    <IconStyle>
      <Icon>
       <href>http://www.sourcefabric.org/javascript/geocoding/markers/marker-gold.png</href>
      </Icon>
    </IconStyle>
  </Style>
    {{ /if }}
  {{ /list_article_locations }}
{{ /list_articles }}

{{ list_articles}}
  {{ list_article_locations }}
    {{ if $gimme->location->enabled }}
  <Placemark>
    <name>{{ $gimme->location->name }} @ {{
$gimme->article->name }}</name>
    <description></description>
    <styleUrl>#style{{ $gimme->article->number }}-{{
$gimme->current_list->index }}</styleUrl>
    <Point>
      <coordinates>{{ $gimme->location->longitude
}},{{ $gimme->location->latitude }},0.000000</coordinates>
    </Point>
  </Placemark>
    {{ /if }}
  {{ /list_article_locations }}
{{ /list_articles }}
</Document>
</kml>

Taken from Template Pack "The Journal" (date 2011-03-15) file "article-cont.tpl"

<p>
Location(s):
{{ list_article_locations }}
 {{ if $gimme->location->enabled }}
  {{ $gimme->location->name }}
   {{ if $gimme->current_list->at_end }}{{ else }}, {{ /if }}
 {{ /if }}
{{ /list_article_locations }}
</p>

Inside list_article_locations the following statements are forbidden:

  • set_language
  • set_default_language
  • unset_language
  • set_publication
  • set_default_publication
  • unset_publication
  • list_issues
  • set_issue
  • set_default_issue
  • set_current_issue
  • unset_issue
  • list_sections
  • set_section
  • set_default_section
  • unset_section
  • list_articles
  • set_article
  • set_default_article
  • unset_article
  • list_article_images

Inside the list, the current location is set to the current element of the list. The environment context is restored after the list processing.