Adapt Your Add-ons and Themes to CS-Cart 4.18.1¶

Changed Functions¶

1. // Old:
   function fn_filter_uploaded_data($name, array $filter_by_ext = [], $show_default_error_notifications = true, $sanitaze_filename = true)
   // New:
   function fn_filter_uploaded_data($name, array $filter_by_ext = [], $show_default_error_notifications = true, $sanitaze_filename = true, $filter_by_file_size_bytes = false)
   

2. // Old:
   function fn_check_uploaded_data(array $uploaded_data, array $filter_by_ext)
   // New:
   function fn_check_uploaded_data(array $uploaded_data, array $filter_by_ext, $filter_by_file_size_bytes = false)
   

New Functions¶

1. Gets language direction:

   \Tygh\Template\IContext::getLanguageDirection()
   

2. Gets language direction:

   \Tygh\Template\Snippet\Table\ItemContext::getLanguageDirection()
   

3. Gets language direction:

   \Tygh\Template\Mail\Context::getLanguageDirection()
   

4. Gets language direction:

   \Tygh\Template\Internal\Context::getLanguageDirection()
   

5. Gets language direction:

   \Tygh\Template\Document\Order\Context::getLanguageDirection()
   

The display of dynamic actions is updated¶

The dynamic actions $navigation.dynamic.actions display is updated. They are now shown in the right upper corner of the page. From now on, dynamic actions are the preferred interface elements for displaying actions and subpages. Dynamic actions appear as buttons. When there are multiple dynamic actions, some of them are displayed in a drop-down menu.

Dynamic actions requirements:

• Use verbs in buttons titles. For example, use Add several products.
• The buttons should function both as standalone buttons and as items in the dropdown menu.

<?php

use Tygh\ Registry;

defined('BOOTSTRAP') or die('Access denied');

if ($mode === 'manage') {
    Registry::set('navigation.dynamic.actions', [
        'my_changes.test_button' => [
            'href' => 'categories.manage',
            'text' => __('my_changes.view_my_changes'),
        ]
    ]);
}

The display of the top and central menu is updated¶

• The process of extending of the top menu $navigation.static.top has been modified.
• The Add-ons menu $navigation.static.top.addons is now displayed beneath the central menu. The subitems submenu is now marked as deprecated. Use dynamic actions instead.
• The Administration menu $navigation.static.top.administration now appears on the new Settings (dispatch=administration.view) page. Dynamic actions are recommended instead of the subitems submenu.
• The Settings menu $navigation.static.top.settings now appears only on the Settings → General (dispatch=settings.manage) page. To display the menu items, use the setting type.
• The Design menu $navigation.static.top.design is now marked as deprecated. Extend the Website menu $navigation.static.central.website instead.
• Instead of the top menu, the top bar top_bar.tpl is now displayed. You can extend it using the menu:top_bar_right.
• The extension of the central menu $navigation.static.central has been updated. The central menu is now located in the sidebar. To expand it, use $navigation.static.central. The subitems submenu has been deprecated. Use dynamic actions instead. Use short titles of menu items (up to ~15 characters). The descriptions of the menu items are no longer displayed.

The dynamic sections have been deprecated¶

The dynamic sections $navigation.dynamic.sections have been deprecated. Use dynamic actions instead.

Gear buttons have been deprecated¶

Gear buttons in the right upper corner of the page have been deprecated. Use dynamic actions instead. Please note that dynamic actions can appear both as standalone buttons and as items in the dropdown menu.

Search filter extension through product list page template deprecated¶

Search filters on the product list page (?dispatch=products.manage) are now set using an array. Use the products:search_data hook to extend it. For example, to add a text field, use hook:

design/backend/templates/addons/my_changes/hooks/products/search_data.post.tpl

{$search_filters.data.my_changes_filter = [
    id => "my_changes_filter",
    type => "input",
    category => "secondary",
    label => __("my_changes_filter"),
    value => $search.my_changes_filter_value,
    placeholder => __("my_changes_filter_placeholder")
]}

{* Export *}
{$search_filters = $search_filters scope=parent}

Hooks products:simple_search, companies:products_advanced_search, products:search_form, products:search_in_orders and products:advanced_search for extending the products list page have been deprecated. The products:select_search hook have been deprecated, use the products:sort_by_content hook instead.

The example of connecting search filters can be found in the Search filters on the product list page section.

Saved searches¶

To display saved searches, use the saved_search parameter. An example of saved searches for a product list page:

design/backend/templates/views/products/manage.tpl

{$search_form_dispatch = $dispatch|default:"products.manage"}
{$saved_search = [
    dispatch => $search_form_dispatch,
    view_type => "products"
]}
{include file="common/mainbox.tpl"
    ...
    saved_search=$saved_search
}

Extending dashboard analytics blocks through template hooks has been deprecated¶

Now extending Dashboard analytics blocks should be done through a schema.

<?php

use Tygh\Enum\DashboardSections;

defined('BOOTSTRAP') or die('Access denied');

$schema[DashboardSections::TERTIARY]['my_changes'] = [
    'id' => 'my_changes',
    'title' => __('my_changes.dashboard.my_changes'),
    'position' => 100,
    'dispatch' => 'products.manage',
    'content_data_function' => 'fn_my_changes_get_dashboard_block_data'
];

return $schema;

<?php


if (!defined('BOOTSTRAP')) { die('Access denied'); }


function fn_my_changes_get_dashboard_block_data()
{
    $content_data = [
        'id' => 'my_changes',
        'title' => __('my_changes.dashboard.title'),
        'title_button' => [
            'href' => 'products.manage',
            'name' => __('my_changes.dashboard.title_button'),
        ],
        'number' => 1234,
    ];

    return $content_data;
}

Setup wizard has been deprecated¶

The Setup wizard has been deprecated. Use the Settings tab of your add-on instead. Learn more about scheme 3.0 structure.

Icon display has been updated¶

Icons must now be connected through the component common/icon.tpl. Other methods are considered deprecated and will no longer work. The Font Awesome icon library has been replaced with CS-Cart’s custom icons. Now, instead of an icon font, vector SVG icons are used. Connection parameters for icons have changed. Connecting icons using the class parameter (e.g., class="icon-warning-sign") is deprecated. It is necessary to use the source parameter (e.g., source="warning_sign") with a value in snake_case and without the icon- prefix. See the example of connecting an icon in SVG icons section.

Page width has been updated¶

Top and central menu are now displayed on the left. Consequently, the available width for displaying page content has decreased. Please check the display of your pages on small screens.

The width restriction for page display has been removed. Now, the site is displayed across the entire available width of the window. Please check the appearance of interface elements on large screens.

Less style variables have been updated¶

Some Less style variables (colors, sizes, etc.) have been modified or removed. Now, CS-Cart’s Less-variables align with Bootstrap 2’s.

Instead of hardcoding values in styles, use Less variables and CSS custom properties from css/config.less for styles in your add-ons. For obtaining other values, utilize Less functions. For example, functions like spin(desaturate(lighten(@textColor, 30%), 25%), -15%) create the Text muted color. For more information about lessphp and Less, refer to their documentation. For details on removed Less variables, see Deleted style variables section.

Deleted Functions¶

1. fn_master_products_generate_navigation_sections

New Hooks¶

1. Executes after getting dashboard block data, allows editing it:

   fn_set_hook('get_dashboard_block_data', $content_data, $this);
   

2. Executes after filling content information for block with sales statistics, allows editing it:

   fn_set_hook('get_dashboard_sales_block_data', $content_data, $this);
   

3. Executes after filling content information for block with products statistics, allows editing it:

   fn_set_hook('get_dashboard_products_block_data', $content_data, $this);
   

4. Executes after filling content information for block with orders statistics, allows editing it:

   fn_set_hook('get_dashboard_orders_block_data', $content_data, $this);
   

5. Executes after filling content information for block with orders by statuses statistics, allows editing it:

   fn_set_hook('get_dashboard_orders_by_statuses_block_data', $content_data, $this);
   

6. Executes after filling content information for block with vendor balance, allows editing it:

   fn_set_hook('get_dashboard_vendor_balance_block_data', $content_data, $this);
   

7. Executes after filling content information for block with vendor activity statistics, allows editing it:

   fn_set_hook('get_dashboard_vendor_with_sales_block_data', $content_data, $this);
   

8. Executes after filling content information for block with companies or vendors statistics, allows editing it:

   fn_set_hook('get_dashboard_stores_block_data', $content_data, $this);
   

9. Executes after filling content information for block with users statistics, allows editing it:

   fn_set_hook('get_dashboard_customers_block_data', $content_data, $this);
   

10. Executes after filling content information for block with last logs, allows editing it:

    fn_set_hook('get_dashboard_logs_block_data', $content_data, $this);
    

11. Executes when changing order status before products are recalculated:

    fn_set_hook('change_order_status_pre', $order_id, $status_to, $status_from, $force_notification, $place_order, $order_info, $allow_status_update);
    

12. Executes after updating data about the availability of products in warehouses:

    fn_set_hook('warehouses_recalculate_destination_products_stocks', $this, $params, $product_condition);
    

13. Executes after deleting product stocks:

    fn_set_hook('warehouses_remove_product_stocks_post', $this, $product_id);
    

14. Executes before updating/creating a banner:

    fn_set_hook('banners_update_banner_pre', $data, $banner_id, $lang_code);
    

Changed Hooks¶

1. // Old:
   fn_set_hook('create_order_details', $order_id, $cart, $order_details, $extra);
   // New:
   fn_set_hook('create_order_details', $order_id, $cart, $order_details, $extra, $k, $v);
   

2. // Old:
   fn_set_hook('add_to_cart', $cart, $product_id, $_id);
   // New:
   fn_set_hook('add_to_cart', $cart, $product_id, $_id, $_data);
   

3. // Old:
   fn_set_hook('filter_uploaded_data_post', $name, $filter_by_ext, $filtered, $udata_local, $udata_other, $utype);
   // New:
   fn_set_hook('filter_uploaded_data_post', $name, $filter_by_ext, $filtered, $udata_local, $udata_other, $utype, $filter_by_file_size_bytes);
   

4. // Old:
   fn_set_hook('check_uploaded_data_pre', $uploaded_data, $filter_by_ext, $result, $processed);
   // New:
   fn_set_hook('check_uploaded_data_pre', $uploaded_data, $filter_by_ext, $result, $processed, $filter_by_file_size_bytes);
   

5. // Old:
   fn_set_hook('check_uploaded_data_post', $uploaded_data, $filter_by_ext, $result, $processed);
   // New:
   fn_set_hook('check_uploaded_data_post', $uploaded_data, $filter_by_ext, $result, $processed, $filter_by_file_size_bytes);
   

Components Updated¶

<?php
defined('BOOTSTRAP') or die('Access denied');

/** @var array $schema */
$schema['my_changes.manage']['my_changes.test_button'] = [
    'href' => 'categories.manage',
    'text' => __('my_changes.actions.view_my_changes'),
    'text_mobile' => __('my_changes.actions.view_my_changes_mobile'),
    'id' => 'my_changes_id',
    'class' => 'my-changes-class',
    'data' => [
        'data-ca-my-changes-param-1' => 'my_value_1',
        'data-ca-my-changes-param-2' => 'my_value_2',
    ],
    'wrapper_class' => 'my-changes-wrapper-class',
    'position' => 100
];

return $schema;

{$search_filters.data.my_changes_filter = [
    id => "my_changes_filter",
    type => "input",
    category => "secondary",
    label => __("my_changes_filter"),
    value => $search.my_changes_filter_value,
    placeholder => __("my_changes_filter_placeholder"),
    is_enabled => true,
    is_hidden => false,
    content => "HTML content",
    data => [
        name_from => "my_changes_filter_from",
        value_from => $search.my_changes_filter_from,
        label_from => __("my_changes_filter_from"),
        name_to => "my_changes_filter_to",
        value_to => $search.my_changes_filter_to,
        label_to => __("my_changes_filter_to")
    ],
    nested_data => [
        my_changes_filter_param => [
            key => "my_changes_filter_param",
            label => __("my_changes_filter_param"),
            value => true,
            is_checked => ($search.my_changes_filter_param === "YesNo::YES"|enum)
        ]
    ]
]}

{* Export *}
{$search_filters = $search_filters scope=parent}

{$search_filters.my_changes_query = [
    id => "my_changes_query",
    type => "input",
    category => "primary",
    label => __("search_my_changes"),
    value => $search.my_changes_query,
    priority => 1000
]}

{* Export *}
{$search_filters = $search_filters scope=parent}

<?php

use Tygh\Enum\DashboardSections;

defined('BOOTSTRAP') or die('Access denied');

$schema[DashboardSections::TERTIARY]['my_changes'] = [
    'id' => 'my_changes',
    'title' => __('my_changes.dashboard.my_changes'),
    'position' => 100,
    'dispatch' => 'products.manage',
    'content_data_function' => 'fn_my_changes_get_dashboard_block_data'
];

return $schema;

<?php

if (!defined('BOOTSTRAP')) { die('Access denied'); }

function fn_my_changes_get_dashboard_block_data()
{
    $content_data = [
        'id' => 'my_changes',
        'preheader' => __('my_changes.dashboard.preheader'),
        'is_selected_date' => false,
        'title' => __('my_changes.dashboard.title'),
        'title_button' => [
            'href' => 'products.manage',
            'name' => __('my_changes.dashboard.title_button'),
        ],
        'number' => 1234,
        'number_dynamics' => 15,
        'use_price_for_number' => false,
        'content' => [
            '<strong>Hello</strong>',
            '<em>world!</em>',
        ],
        'content_tpl' => [
            'addons/my_changes/views/my_changes/components/my_changes_component.tpl'
        ],
        'buttons' => [
            'button_1' => [
                'name' => __('my_changes.dashboard.button_1'),
                'href' => 'products.manage',
                'class' => 'my-changes-button-1',
            ],
        ],
        'graph' => [
            'content' => [
                [
                    'date' => '2024, (0-0), 30',
                    'prev' => 150,
                    'cur' => 200
                ],
                [
                    'date' => '2024, (0-0), 31',
                    'prev' => 160,
                    'cur' => 300,
                ],
            ]
        ],
        'bar_chart' => [
            'id' => 'bar_chart',
            'title' => __('my_changes.dashboard.bar_chart'),
            'content' => [
                [
                    'id' => 'bar_1',
                    'name' => __('products'),
                    'href' => 'products.manage',
                    'type' => 'primary',
                    'value' => 10,
                    'is_price' => false,
                    'total' => 100,
                    'ratio' => 10,
                ],
                [
                    'id' => 'bar_1',
                    'name' => __('categories'),
                    'href' => 'categories.manage',
                    'value' => 70,
                    'is_price' => false,
                    'total' => 100,
                    'ratio' => 70,
                ],
            ]
        ],
        'resource_list' => [
            'title' => __('my_changes.dashboard.resource_list'),
            'content' => [
                [
                    'id' => 'resource_list',
                    'href' => 'products.manage',
                    'name' => __("my_changes.dashboard.resource_list_name"),
                    'label_text' => __("my_changes.dashboard.resource_list_label_text"),
                    'label_class' => 'my-changes-resource-list',
                    'value_href' => 'products.manage',
                    'value' => '100',
                    'use_price_for_value' => false,
                    'description' => __("my_changes.dashboard.resource_list_description"),
                    'description_href' => 'products.manage',
                    'small_text' => __("my_changes.dashboard.resource_list_small_text"),
                    // 'image' => [],
                ]
            ]
        ],
        'resource_list_tabs' => [
            'id' => 'resource_list_tabs',
            'content' => [
                'resource_list_tabs_1' => [
                    'id' => 'resource_list_tabs_1',
                    'title' => __('resource_list_tabs_1'),
                    'content' => [
                        // Same thing as $content_data['resource_list']['content']
                    ]
                ],
            ]
        ],
        'scripts' => [
            'js/addons/my_changes/func.js'
        ],
    ];

    return $content_data;
}

<h3>My changes test</h3>

{include_ext file="common/icon.tpl"
    source="warning_sign"
    tone="warning"
    color="#f00"
    accessibility_label="No user"
    show_icon=$is_show_user_require_warning_icon
    class="user-require-warning"
    id="user_warning_icon"
    render="inline"
    data=[
        "data-ca-param-1" => "value_1",
        "data-ca-param-2" => "value_2"
    ]
}

{include_ext file="common/icon.tpl" source="addons/my_changes/icons/my_icon.svg"}

<svg viewBox="0 0 20 20" xmlns="http://www.w3.org/2000/svg"><path d="m0 0h20v20h-20z"/></svg>

New Hooks¶

1. index:head
2. menu:top_bar_right
3. banners:status

Deleted Hooks¶

1. index:analytics_data: use dashboard/blocks schema instead.

Deprecated Hooks¶

1. products:action_buttons: use dynamic actions instead.
2. products:simple_search on the product list: use products:search_data instead.
3. companies:products_advanced_search on the product list: use products:search_data instead.
4. products:search_form on the product list: use products:search_data instead.
5. products:search_in_orders on the product list: use products:search_data instead.
6. products:advanced_search on the product list: use products:search_data instead.
7. products:select_search on the product list: use products:sort_by_content instead.

Deleted Template Variables¶

1. enable_sticky_scroll
2. navigation_accordion
3. addons vendor_data_premoderation: vendor_data_premoderation
4. addons vendor_plans: plan_usage and plan_data

Deleted style variables¶

1. @wide-width: use var(--content-width) instead.
2. @mainSidebarWidth: use var(--sidebar-width) instead.
3. @mainSidebarThinWidth: use 50px instead.
4. @headerOffset: use 89px instead.
5. @textMutedColor: use spin(desaturate(lighten(@textColor, 30%), 25%), -15%) instead.
6. @mainSidebarBackgroundColor: use #333940 instead.
7. @topPanelBackground: use #f9f9f9 instead.
8. @topPanelTextColorLight: use #daedf7 instead.
9. @topPanelDropdownBackgroundColor: use #4c6b8a instead.
10. @topPanelDropdownTextColor: use #272b31 instead.
11. @brandFontColor: use #fff instead.
12. @brandFontWeight: use 500 instead.
13. @topPanelMenuBackgroundStart: use @mainColor instead.
14. @topPanelMenuBackgroundEnd: use @mainColor instead.
15. @topPanelMenuBackgroundHoverStart: use @mainColor instead.
16. @topPanelMenuBackgroundHoverEnd: use @mainColor instead.
17. @topPanelMenuBackgroundActiveStart: use @mainColor instead.
18. @topPanelMenuBackgroundActiveEnd: use @mainColor instead.
19. @topPanelMenuBackgroundDisabled: use @gray instead.
20. @topPanelMenuCaret: use #fff instead.
21. @topPanelMenuDividerLeft: use transparent instead.
22. @topPanelMenuDividerRight: use transparent instead.
23. @topPanelBoxShadow: use 0 1px 4px rgba(0,0,0,0.1) instead.
24. @successColor: use @btnSuccessBackground instead.
25. @mutedBackground: use #f7f7f9 instead.
26. @mutedBorder use #e1e1e8 instead.
27. @btnPrimaryText: use #daedf7 instead.
28. @btnPrimaryBackgroundBorder: use @btnPrimaryBackground instead.
29. @successButton: use @btnSuccessBackground instead.
30. @textButtonColor: use @btnPrimaryBackground instead.
31. @textButtonCaretColor: use #1010107b instead.
32. @tabsBackgroundColor: use #f4f3f3 instead.
33. @tabsActiveBackgroundColor: use @mainColor instead.
34. @extraIconsSprite: use url(../media/images/exicons.png) instead.
35. @extraIconsSpriteWhite: use url(../media/images/exicons_white.png) instead.
36. @zIndexPopup: use 1500 instead.

Deleted CSS classes¶

1. btn-text: use btn-link instead.

JavaScript Changes¶

Changes to “Gear buttons have been deprecated”¶

This part of the Gear buttons have been deprecated section has been changed completely and is not relevant:

Gear buttons on the list of objects have been deprecated (for example, on the product list page). To perform the actions, use the Context menu. The appearance of gear buttons on the list of products and orders has changed (hooks products:list_extra_links and orders:list_extra_links).

Changes to “Search filter extension through product list page template deprecated”¶

1. This part of the Search filter extension through product list page template deprecated has been changed and is not relevant:

   Search filters on the product list are now set using an array. Use the products:search_data hook to extend it.

Instead, a new search filter is now only on the products list page (?dispatch=products.manage). For example, it is not used when you add a product while creating an order.

2. Your own filter my_changes_filter now needs to be placed in $search_filters.data instead of $search_filters. You should use the parameter category => "secondary".
3. Hooks: became irrelevant for all product lists (for example, search in the popup), except the product list page (?dispatch=products.manage).

Changes to “Dynamic actions in the header of the site”¶

The following changes in the Dynamic actions in the header of the site section have been made:

• The default type used now is always text.
• Setting dynamic actions should be done through schemas, not controllers.
• Use the text parameter up to 30 characters in length.
• Use the text_mobile parameter up to 20 characters in length.
• The raw parameter is not available anymore.

Changes to “Search filters on the product list page”¶

The following changes in the Search filters on the product list page section have been made:

• Now the template get_product_search_filters.tpl is used instead of products_search_form.tpl.
• Instead of the array $search_filters, now use the sub-array $search_filters.data.

Changes to “Context search”¶

The following changes in the Context search section have been made:

Now there is no need to include context_search.tpl in your template and pass the parameter to common/mainbox.tpl. It is enough to hook into addons/my_changes/hooks/products/search_data.post.tpl, create an array {$search_filters.my_changes_query = [ ... ]} and export $search_filters.