List 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 }} and {{ /list_articles }} is repeated for every article in the list.
Syntax:
{{ list_articles [length="<integer_value>"]
[columns="<integer_value>"]
[ignore_publication="true"]
[ignore_issue="true"]
[ignore_section="true"]
[ignore_language="true"]
[location="<longitude, latitude>]
[constraints="<list_of_article_constraints>"]
[order="<order_condition>"] }}
<list_of_instructions>
{{ /list_articles }}
Filters:
- length="<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>" 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 using the current_list object, for example:
{{ 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
Constraints
<list_of_article_constraints> can include any of the following constraints:
-
- name <string_operator> <string_value>
- number <integer_operator> <integer_value>
- keyword <string_value>
- OnFrontPage <switch_operator> <switch_value>
- OnSection [<switch_operator> <switch_value>]
- upload_date <date_operator> <date_value>
- publish_date <date_operator> <date_value>
- public <switch_operator> <switch_value>
- type <switch_operator> <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 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 <switch_operator> relation with <switch_value> will be selected; for details see Creating articles within a section
- OnSection: articles having "Show article on section page" flag in <switch_operator> relation with <switch_value> will be selected; for details see Creating articles within a section
- public: articles having "Allow users without subscription..." flag in <switch_operator> relation with <switch_value> 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. The topic name must be written in the format <topic_name>:<language_code> - for example sports:en or health:en.
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="sports:en" }}
{{ list_articles }}
...
{{ /list_articles }}
This will list only articles having the topic 'sports'. The topic is automatically appended to the URL parameters so you don't have to set the topic in the current page.
- reads: you can set constraints based on the number of readers that viewed this article since it was published
- author: this works only in Newscoop 3.2.1 and newer versions. 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). 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"
Order
<order_condition> can include any of the following, in descending or ascending order:
- 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
- bycustom.<type>.<fieldname>.<defaultvalue> desc|asc
- byComments instructs 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
- bycustom type can be set in the second part after the dot: case insensitive strings set by "ci", case sensitive strings set by "cs", or numerical set by "num". The field name is the third part, such as "deck". The fourth part is a default value for articles that do not contain the field name. An example could be:
{{ list_articles ... order="bycustom.ci.deck.aaa desc" constraints="..." }} Note that the text area (i.e. multi-line text) data types usually contain some hidden html tags, which can affect the ordering, and that custom field ordering does not work for the (complex date) calendar-like fields of events.
- 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. bycustom was introduced in Newscoop 4.0.0.
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.
Exceptions:
<list_of_instructions> may contain any statement except those listed below. 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
The list_articles statement cannot be used inside list_subtitles, or list_search_results statements.
Example:
Taken from theme "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 }}