Loading...

Object selection standards

We no longer maintain the Knowledge Base since version 4.3.x. All the latest user and developer documentation for 4.3.x and newer versions is now available at docs.cs-cart.com.

  • This article applies to CS-Cart versions:
  • 3.0.x

Object selection standards

Logical part

Declaring a function

Selection (search for) of objects from the base should always be described as a function with the following format:

1
2
3
function fn_get_[object]($params, [$param2], [$paramN])
{
}

where

  • object – object name in a plural form
  • $params – array with the search parameters (in the general case $_REQUEST is passed there)
  • $paramN – additional parameters (for example, language, user information, etc.)

Body of the function

A function consists of a certain sequence of steps

  1. Initializing search filter
  2. Setting default values
  3. Setting the fields that will be selected
  4. Forming a request for sorting
  5. Forming a request for searching
  6. Connecting addons
  7. Pagination
  8. Request
  9. Returning a result

Let's consider the function step by step.

 

Initializing search filter

1
2
// Init filter
    $params = fn_init_filter('products', $params);

The first parameter – object  identifier, the second one – input parameters. The function returns filtered parameters.

 

Setting default values

1
2
3
4
5
6
// Set default values to input params
       $default_params = array (
               'page' => 1,
               ....
      );
      $params = array_merge($default_params, $params);

Default values are checked/set in this section.

 

Defining the fields that will be selected

1
2
3
4
5
6
7
8
9
10
11
12
// Define fields that should be retrieved
    $fields = array (
        "?:users.user_id",
        "?:users.user_login",
        "?:users.timestamp",
        "?:users.user_type",
        "?:users.active",
        "?:users.firstname",
        "?:users.lastname",
        "?:users.email",
        "?:users.company",
    );

Fields are defined as an array.

 

Forming a request for searching

1
2
3
4
5
$condition = $join= '';
 
    if (!empty($params['company'])) {
        $condition .= " AND ?:users.company LIKE '%$params[company]%'";
    }

2 string variables (if needed more than two) are initialized first:

  • condition – will contain conditions of the selection
  • join – additional tables for the selection
Then the value of each parameter is checked and a condition for search is formed.

Connecting addons

1
fn_set_hook('get_users', $params, $fields, $condition, $join);

Input parameters, fields for selection, conditions of the selection and additional tables are passed to the addon.

 

Forming a request for sorting

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
// Define sort fields
    $sortings = array (
        'id' => "?:users.user_id",
        'username' => "?:users.user_login",
        'email' => "?:users.email",
        'name' => array("?:users.firstname", "?:users.lastname"),
        'date' => "?:users.timestamp",
        'type' => "?:users.user_type",
        'active' => "?:users.active",
    );
 
    $directions = array (
        'asc' => 'asc',
        'desc' => 'desc'
    );
 
    if (empty($params['sort_order']) || empty($directions[$params['sort_order']])) {
        $params['sort_order'] = 'asc';
    }
 
    if (empty($params['sort_by']) || empty($sortings[$params['sort_by']])) {
        $params['sort_by'] = 'name';
    }
 
    $sorting = (is_array($sortings[$params['sort_by']]) ? implode(' ' . $directions[$params['sort_order']]. ', ', $sortings[$params['sort_by']]) : $sortings[$params['sort_by']]). " " .$directions[$params['sort_order']];
 
    // Reverse sorting (for usage in view)
    $params['sort_order'] = $params['sort_order'] == 'asc' ? 'desc' : 'asc';

All the fields, by which the sorting is possible, are defined first and after that directions of the sorting are defined (it is redundant but convenient for checking). Then it is checked whether the input parameters meet the set conditions and a string for sorting is formed (without ORDER BY!!!). Then the sorting direction is reversed (in order to be displayed in a template without unnecessary conditions).

 

Pagination

1
2
3
// Paginate search results
    $total = db_get_field("SELECT COUNT(DISTINCT(?:users.user_id)) FROM ?:users $join WHERE 1 $condition");
    $limit = fn_paginate($params['page'], $total, $items_per_page);

At first the total number of objects is chosen to the variable total, then conditions for selection are formed and written to the variable limit.

 

Request

1
$users = db_get_array("SELECT " . implode(', ', $fields) . " FROM ?:users $join WHERE 1 $condition GROUP BY ?:users.user_id ORDER BY $sorting $limit");

 

Returning a result

1
return array($users, $params);
The result is returned as an array, where:
  • The first element – array of the selected objects
  • The second element – input parameters (also the filtered ones)

It is possible to return some additional elements, but the first 2 are mandatory.

 

Getting data from function

1
2
3
4
list($events, $search) = fn_get_events($params);
 
    $view->assign('events', $events);
    $view->assign('search', $search);

We assign the result to arrays using the function list. Then search will be used in the search form (to set the search values).

Visual part

Template name

A template with a search form should have the following name:
1
[object, pl]_search_form.tpl
where object – object name in a plural form.

Template contents

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
{capture name="section"}
 
<form action="{$index_script}" name="orders_search_form" method="get">
 
<table cellpadding="10" cellspacing="0" border="0" width="100%">
<tr>
    <td class="nowrap search-field">
        <label for="cname">{$lang.customer}:</label>
        <div class="break">
            <input type="text" name="cname" id="cname" value="{$search.cname}" size="30" class="search-input-text" />
            {include file="buttons/search_go.tpl" search="Y" but_name="orders.search"}
        </div>
    </td>
    <td class="search-field">
        <label for="email">{$lang.email}:</label>
        <div class="break">
            <input type="text" name="email" id="email" value="{$search.email}" size="30" class="input-text" />
        </div>
    </td>
    <td class="nowrap search-field">
        <label for="total_from">{$lang.total}&nbsp;({$currencies.$primary_currency.symbol}):</label>
        <div class="break">
            <input type="text" name="total_from" id="total_from" value="{$search.total_from}" size="3" class="input-text-price" />&nbsp;&ndash;&nbsp;<input type="text" name="total_to" value="{$search.total_to}" size="3" class="input-text-price" />
        </div>
    </td>
    <td width="100%">
        <div class="buttons-container">
            {include file="buttons/button.tpl" but_text=$lang.search but_name="dispatch[orders.search]" but_role="submit"}
        </div>
    </td>
</tr>
</table>
 
{capture name="advanced_search"}
 
<div class="form-field">
    <label for="tax_exempt">{$lang.tax_exempt}:</label>
    <select name="tax_exempt" id="tax_exempt">
        <option value="">--</option>
        <option value="Y" {if $search.tax_exempt == "Y"}selected="selected"{/if}>{$lang.yes}</option>
        <option value="N" {if $search.tax_exempt == "N"}selected="selected"{/if}>{$lang.no}</option>
    </select>
</div>
 
<div class="form-field">
    <label>{$lang.order_status}:</label>
    {include file="orders_pages/order_status.tpl" status=$search.status display="checkboxes" name="status"}
</div>
 
{if !($search.tax_exempt || $search.status || $search.period || $search.order_id || $search.products)} {* FIXME: need another solution *}
    {assign var="hide" value=true}
{else}
    {assign var="hide" value=false}
{/if}
 
{/capture}
{include file="common_templates/advanced_search.tpl" content=$smarty.capture.advanced_search hide=$hide dispatch="orders.search"}
 
</form>
 
{/capture}
{include file="common_templates/section.tpl" section_title=$lang.search section_content=$smarty.capture.section}
  1. Search form should be inside the structure section
  2. Search form should have a short form plus a section of advanced search

 

<< Read previous Read next >>
Home / Docs / Appendix / Coding Standards / Object selection standards