====== Box article list ======

**Box_article_list** is a module that retrieves a list of articles from the database based on criteria (SQL query) constructed within [[devdoc:vte:params |<vte:params>]]
 list.

===== Examples =====
**Example 1:** Fetching latest 10 articles from categories 1, 3 and 5:
<code>
<vte:box module="box_article_list">
    <vte:params>
        <vte:param name="search_sort_by" value="created" />
        <vte:param name="search_order" value="descending" />
        <vte:param name="search_cid" value="1,3,5" />
        <vte:param name="search_limit" value="10" />
        <vte:param name="add_to_printed" value="true" />
        <vte:param name="exclude_printed" value="true" />
    </vte:params>
    <vte:template>
        <div class="box_body">
            <vte:foreach item = "article" from = "{article_list}">
                <vte:include file="{VIVVO_TEMPLATE_DIR}summary/default.tpl" />
            </vte:foreach>
        </div>
    </vte:template>
</vte:box>
</code>
 

**Example 2:** Fetching all articles scheduled for every Monday from September 1st to October 31th, in period 5:00 AM to 2:59 PM:
<code>
<vte:box module="box_article_list">
    <vte:params>
        <vte:param name="search_schedule_dow" value="1" />
        <vte:param name="search_schedule_month" value="9,10" />
        <vte:param name="search_schedule_hour" value="5,6,7,8,9,10,11,12,13,14" />
    </vte:params>
    <vte:template>
        <div class="box_body">
            <vte:foreach item = "article" from = "{article_list}">
                <vte:include file="{VIVVO_TEMPLATE_DIR}summary/default.tpl" />
            </vte:foreach>
        </div>
    </vte:template>
</vte:box>
</code>
<note important>Articles schedules are introduced in Vivvo 4.1.5</note>

===== Params =====

**Box parameters:**

^ Parameter name   ^Value       ^Description    ^
| add_to_printed   |0%%|%%1     | Flags articles as "dirty" or used; 0 - default    |
| exclude_printed  |0%%|%%1     | Instructs module not to use "dirty" articles; 0 - default    |
| TITLE            |string      | custom title for box, available in template via {TITLE}|
| BOX_ID           |string      | custom html id for box, available in template via {BOX_ID}|

**Search parameters:**

^ Parameter name         ^Value                               ^Description                                                      ^
| search_limit           |integer                             | max number of articles to retrieve                              |
| pg                     |integer                             | 0 - default                                                     |
| search_order           |'ascending' \\ 'descending'         | applies to search_sort_by                                       |
| offset                 |integer                             | query offset, 0 based                                           |
| fields                 |string                              | comma separated database fields                                 |          
| search_options         |array                               | compact form of search parameters                               |
| search_status          |-1 %%|%% 0 %%|%% 1 %%|%% 2          | -1: archived  \\  0: pending  \\  1: active  \\  2: headline |
|search_status_limit     |0 %%|%% 1                           | 0: all articles (default for administration) \\ 1: active and headline articles (default for front end)|
|search_id               |integer                             | article id                                                      |
|search_cid              |string                              |comma separated category ids                                     |
|search_author           |string                              |whole author name or a part of it                                |
|search_author_exact_name|0 %%|%% 1                           |0: search author name with like \\ 1:search exact author name \\ 0 default|
|search_query            |string                              |keywords, implemented trough mysql full text search (mysql limitation stands) or like for title only|
|search_title_only       |0 %%|%% 1                           |0: full text search against title, abstract and body \\ 1: title only search |
|search_search_date      |integer                             |number of days                                                   |
|search_before_after     |0 %%|%% 1                           |0: before \\ 1: after applies to search_search_date           |
|search_by_date          |integer                             |strtotime recognizable date format                               |
|search_by_year          |integer                             |year constrain                                                   |
|search_by_month  	 |integer  	                      |month constrain                                                  |
|search_by_day  	 |integer  	                      |day of month constrain                                           |
|search_tag  	         |string  	                      |tag name                                                         |
|search_tag_id  	 |integer  	                      |tag id                                                           |
|search_user_id  	 |integer  	                      |author id                                                        |
|search_related  	 |integer  	                      |article id                                                       |
|search_rss_feed  	 |integer  	                      |rss feed (0: no, 1: yes)                                         |
|search_image            |string                              |search by image name                                             |
|search_sefriendly       |string                              |article sefriendly url                                           |
|search_exclude_id  	 |string  	                      |comma separated article ids                                      |
|search_sort_by          | 'most_popular' \\ 'most_commented' \\ 'most_emailed' \\ 'id' \\ 'category_id' \\ 'user_id' \\ 'author' \\ 'title' \\ 'created' \\ 'last_read' \\ 'times_read' \\ 'today_read' \\ 'random' \\ 'status' \\ 'sefriendly' \\ 'order_num' \\ 'emailed' \\ 'vote_num' \\ 'vote_sum'                   |sort result by criteria                                          |
^  //The following parameters were added in Vivvo 4.1.5//  ^^^
|search_topic_id         |string                              |comma separated topic ids                                        |
|search_topic            |string                              |comma separated topic names                                      |
|search_schedule_id      |integer                             |schedule id                                                      |
|search_schedule_id_in   |string                              |comma separated schedule ids                                     |
|search_schedule_minute  |string                              |comma separated minutes (0 - 59)                                 |
|search_schedule_hour    |string                              |comma separated hours (0 - 23)                                   |
|search_schedule_dom     |string                              |comma separated days of month (1 - 31)                           |
|search_schedule_month   |string                              |comma separated months (1 - 12)                                  |
|search_schedule_dow     |string                              |comma separated days of week (1 - 7; 1 - Monday, 7 - Sunday)     |
|search_schedule_date    |int                                 |search by date (unix timestamp)                                  |
|search_schedule_year    |int                                 |search by year (i.e. 2009)                                       |
|search_schedule_duration    |int                             |search by duration                                               |
|search_schedule_duration_lt |int                             |search by duration (less than)                                   |
|search_schedule_duration_lte|int                             |search by duration (less than or equal to)                       |
|search_schedule_duration_gt |int                             |search by duration (greater than)                                |
|search_schedule_duration_gte|int                             |search by duration (greater than or equal to)                    |



**Assignments:**

^ Parameter name         ^Value         ^Description                    ^
|article_list_object  	 |object  	|ArticlesList object            |
|article_list  	         |array  	|each item is an Articles object|
|TITLE  	         |string  	|pass trough title parameter    |
|BOX_ID  	         |string  	|pass trough html id parameter  |