For Developers

Work with Data Structures

Display Content

To display a content of a particular property, wrap it in two double brackets {{ }}:

{{ product.name }}

dump

Dump displays information about a data structure (parameter, object or property) in a template. It is mostly used when you need to know a structure in order to be able to work with it. To use it correctly, insert the dump mark into the page code, save and display the project preview (otherwise you are not able to see the results)

  • {{ dump() }} - dump without defined parameter. It returns all available prameters and variables set in the template code.

  • {{ dump(component.product) }} - use this piece of code in the Product Detail View of the Product Catalog Component Page and all parameters connected to a particular product will be displayed.

Twig Filters and Functions

The BizBox Editor uses the Twig template engine. You can use Twig Tags, Filters, Functions, Tests and Operators as defined in the twig documentation. Apart from that you can use special Filters and Functions used only in BizBox.

BizBox Twig Filters

  • arrayPad - filter fills the array to the required length with the specified character. If the length is longer than required, it does nothing. If you want to fill the beginning of the array, enter the length value in a minus value. Example: {{ [ ‘first’, ‘second’ ] | arrayPad( 5, ‘value’ ) | join( ‘, ‘ ) }}.

  • decodeEntities - decodes HTML entities to characters.

  • jsonDecode - filter returns array/object representation of a JSON. Example: {{ data | jsonDecode }})

  • ksort - sorts the array by key values.

  • lastProjectHash - The function returns an MD5 hash from the value returned by the key provider for the last published project. This is a variable that will invalidate the cache.

  • localDate - Displays date in format according to the localization settings.

  • localDatetime - Displays date and time in format according to the localization settings.

  • localMoney - Displays sum of money in format according to the localization settings. If you don’t want to display decimal places in case they are 0 (such as 45.00 EUR), you can use a special filter. Example: {{ 2.00|localMoney( ‘CZK’, 2, true ) }}. This piece of code will display only the “2” without “.00” for the CZK currency according to the current localization settings. This filter can also be used as follows only for one currency: {{ product.price.taxInclusiveUnitPriceRounded|localMoney(product.price.currency.iso, 2, product.price.currency.iso == ‘CZK’ ) }} this filter will hide the .00 in all Cultures only for the CZK currency.

  • localNumber - Displays number in format according to the localization settings.

  • localSort - Sorts a field according to the localization settings.

  • localTime - Displays time in format according to the localization settings.

  • mailLink - generates an HTML link for e-mail address from an inserted text, the optional parameter of this filter is used as a subject of the e-mail message.

  • mergeHash - Merges 2 fields using NetteUtilsArrays::mergeTree.

  • nbsp - Inserts a non-breaking space. It is used to force the browser not to break the line between certain words and characters. This filter is implemented only for 2 languages:

    • Czech - non-breaking spaces will be inserted between characters “a” and “i” and the following word.

    • English - non-breaking space will be inserted between “a”, “an” and “the” and the following word.

  • randomSubset(number of items) - this function selects defined number of items from the defined array (items will not be repeated). This filter does not keep the keys of the input array. If there are less items in the input array than the number if items required, all available items will be returned in random order.

  • sortByField(item, direction) - sorts the array of hashes or objects according to item, direction is an optional parameter, allowed values are asc and desc.

  • localSortByField(item, direction) – it works the same as the sortByField filter, but uses sorting according to the currently set locale.

  • truncate - Shortens (by cutting of) a string according to the parameter of length (can be used for HTML).

  • webalize - converts a string to lower-case, remove accents and omits all other characters (adjusts a string to the shape used in the URL addresses).

  • webLink(protocol) - generates an HTML link from defined text and inserts a protocol. The protocol parameter is optional, implicit value is http.

Note

To each date and/or time on which is the localDatetime, localDate or localTime filter applied, is set its time zone according to the account settings.

Note

The nbsp filter is automatically used with the current language (which is taken from the context). Remember that you have to use the RAW filter in order to display the HTML nbsp mark correctly as a non-breaking space.

Example of usage in the template code: {{ ‘Some text that contains a great example of using the non-breaking space.’|nbsp|raw }}

You can also specify the language as follows: {{ ‘Some text that contains a great example of using the non-breaking space.’ | nbsp(‘cs’) | raw }}

BizBox Twig Functions

fileExists()

This function is used to check the existence of a file in File Manager.

getLink

getLink is used only in case you need the enhanced functionality for the link to a page or component:

  • {{ getLink( ‘index’, ‘ww-en’, true, true ) }} - A link to page with Internal Name ‘index’ from culture ‘ww-en’. Third parameter (true) generates absolute URL. Fourth parameter (true) includes GET parameters to the link (such as culture switcher, filters and ordering).

  • {{ getLink( “catalogue:detail( ‘productCode’: ‘abcd’, ‘category’: ‘internal-name’ )” ) }} - A link to a component page: views - detail (product detail) with particular parameters (product code and category).

getFiles

getFiles - an array of files in particular folder in the File Manager, according to the defined path. You are able to work with this list of files (iterate for example).

  • {% set files = getFiles( ‘/website/images’ ) %} - Generates an array of files in the “images” folder according to the defined path.

getFolders

getFolders - an array of folders in the particular folder in the File Manager, according to the defined path. You are able to work with this list of files (iterate for example).

  • {% set folders = getFolders( ‘/website’ ) %} - Generates an array of folders from the “website” folder (as is defined in the path).

getSubset

getSubset method allows you to get a limited set of entities according to the specified parameters. It is most commonly used for orders pagination in the user portal:

user.orders.getSubset()

Available parameters (at least one is required):

  • limit - limit the number of returned records

  • offset - defines from which the record is about to begin

  • order - determining the direction of sorting (asc, desc)

  • filter - determining filter values

Available filter values:

  • A filter is an array of hashes, where each hash defines one constraint.

  • All constraints in the filter are evaluated using the AND operator, ie all constraints must apply simultaneously.

  • Hash keys: property - specifying the property (or path to it); value - the value of the desired property can be a scalar value or an array with the list of values; op - operator, which compares the value, the key is optional, the default operator is “=”.

  • Also the abbreviated notation is supported (the key in the filter array is property), the value is the tested value (array or scalar), and the operator is “=”.

Example:

{% set pagedOrders = user.orders.getSubset({'limit':5}) %}

nextWorkingDay

nextWorkingDay returns the next working day for the defined time and state (specified by ISO 3166-2). Optionally a number of days other than the default 1 can be specified.

Example:

{% set today = nextWorkingDay( now | date_modify( "- 1 days"), 'CZ' ) | localDate  %}

Examples:

<a href="{{ switchCulture('cz-cs') }}">CZ</a>
<a href="{{ switchCulture('sk-sk') }}">SK</a>

qrCode

The optional options parameter is a hash of options: qrCode( content, options ) generates a QR code from the specified content in the content parameter.

  • error - specification of the QR code security level against errors, available values are: “L”, “M”, “Q” or “H”. The default value is “L”.

  • width - width of the generated QR code in pixels, by default it is 200.

The result is a PNG image returned as a data-URI, which can be inserted directly into the img tag.

Example:

{% set spd = ecommerce.placedOrder.getSPayD( { 'message': 'Invoice payment '~order.orderNumber, 'variableSymbol':order.variableSymbol } ) %}
<img src="{{ qrCode( spd, { 'error': 'M', 'width': 200 } ) }}" />

switchCulture

switchCulture - generates a link to the current page (all parameters from the request will be preserved) in requested culture. First parameter is the requested culture code.

Examples:

<a href="{{ switchCulture('cz-cs') }}">CZ</a>
<a href="{{ switchCulture('sk-sk') }}">SK</a>

FieldVal

fieldVal - returns the value of a selected item (request parameter name). It the first parameter is NULL, optional parameters are searched and the first with an existing value is used:

fieldVal( 'item', parameter1, parameter2, ... )

Use this function in forms (checkout for example) to pre-fill its fields values. Example of usage in the checkout widget for the first name field:

<input name="firstName" type="text" value="{{ fieldVal( 'firstName',  ecommerce.checkout.firstName, user.profile.defaultBillingAddress.firstName, user.profile.firstName ) }}">

Widget

widget - generates a link to run a widget inserted in <form action>.

Example:

<form method="post" action="{{ widget('ecommerce.checkout', {'onSuccess': 'checkout-overview', 'onRecalculate': 'cart' }) }}">

Component Pages

Article Component Filters

component.articleList.filter:

  • fulltext - text for fulltext search

  • tags - tags search

Parameters:

  • Filters: filter

  • Sorting: orderBy

  • Items per Page: perPage

  • Current Page: page

Photoalbum Component Filters

component.imageList.filter:

  • keywords - according to keywords used for searching; or NULL if the filter has not been set

Parameters:

  • Filters: filter

  • Sorting: orderBy

  • Items per Page: perPage

  • Current Page: page

Product Catalog Component Filters

Parameters:

  • Filters: filter

  • Sorting: orderBy

  • Items per Page: perPage

  • Current Page: page

  • Group Variants: groupVariants – support for setting up product grouping that overrides the Component’s Group Product Variants setting. A value of “1” or “true” forces the grouping of variants under the master products. Any other value (eg “0” or “false”, but also “water”) will force the return of the individual variants. If the “groupVariants” parameter is not specified, the component works according to the Group Product Variants setting.

component.productList.filter:

  • categories, brands, manufacturers and extra entities - search according to particular categories/brands/manufacturers/extra entities: found - array; list of found objects; input - array; list of input values (useful if a non-existent tag is provided); use the internal name of a particular entity.

  • fulltext - text for fulltext search

  • tags - search according to tags

  • scheduled deliveries: system.withScheduledDelivery key with the value true (value does not matter now, only the existence of the key is checked).

Manufacturers and Brands

In a components (category view) parameters component.productList.brands and component.productList.manufacturers are available. It contains information about all brands and manufacturers from your product catalog.

To search for all products by particular brand or manufacturer use:

  • /brand/brandInternalName

  • /manufacturer/manufacturerInternalName

For usual searching the variant search/searchQuery is available (the URL is generated in this form).

Tags

This is the link to Search View of your Products Catalog Component that displays only products which have assigned the particular tag. Use it for filtering and searching in your Product Catalog:

{{ getViewLink( 'componentInternalName:tag', {'tag': 'tag (object)' } ) }}

You can also display all products tagged with a particular tag using this URL:

/tag/tagInternalName

Note

It is possible to filter in the Product Catalog component according to the tag in the URL address and in the filters; E.g. URL address ‘/tag/action’ and filter for ‘new’ and ‘discount’ tags will find all products that have the ‘action’ tag and one of the ‘new’ or ‘discount’ filters.

Component Pages

Component pages consist of paricular blocks, views and layout.

To insert a block, you have to use this code:

{% include '@block/block-internal-name' %}

Instead of the block-internal-name insert the real name of a block you want to include into the component page.

To use a layout, define it as a usual block content:

{% block content %}
        <code>
                {% block view %}{% endblock %}
        </code>
{% endblock %}

The {% block view %}{% endblock %} defines where the content of a particular component view will be inserted.

A particular view has to be defined as a block content according to the layout content:

{% block view %}
        {% include '@block/category-menu' %}
{% endblock %}

The view from our example will be inserted in the layout (see above) and it will be consisted from the category-menu component block.

BizBox System Pages

BizBox offers you some system pages you can use. Those pages are generated by the system. You are not able to change them. The URL addresses of these pages are created with your domain and the name of the System Page.

Example: <http://yourDomain.com/specialpagename> or <http://yourDomain.bizboxlive.com/specialpagename>

Cart Operations

  • /systemaddtocart - System page used for adding a Product into shopping cart on another Website. This is used for example for shopping micro sites.

Finish Order Processing

  • /systemfinishorder - System page for finishing of an order’s checkout.

  • /systemfinishfailorder - System page for finishing of an order’s checkout in case some problem occurs during payment’s processing.

Payment Gateway Notification

These URL addresses needs to be (in most cases) set in configuration application of a particular Gateway.

There are 2 types of notification URLs: IPN and Notification Handler. IPN (Instant Payment Notification) receives a notification and the transaction’s details are available on the gateway itself. Notification Handler receives a complete transaction information with verified validity.

  • /skrillipn - IPN for Skrill Payment Gateway.

  • /paypalipn - IPN for PayPal Payment Gateway.

  • /sofortnotificationhandler - Notification Handler for Sofort Payment Gateway.

  • /systemnotificationhandler - Notification Handler for other Payment Gateways.

Actions to occur after successful finishing of an order

Systems actions that are able to perform after a successful finish and payment of an order.

  • /downloadinvoice - A page for downloading an invoice.

BizBox for Webmasters

This article contains a summary of the main activities, functions, filters and programming that are often used for web development in BizBox.

Displayed codes that you can use are in this article. Remember that you have to personalize it. For example, we are using the “nameOfYourWebsite” string which you have to change for the real name of your folder. Also, the names of files are only illustrative, you will need to change it according to your needs.

Reminder: All changes made to your website (in the CMS module, File Manager and Author Tools) are stored in Project. You can check these changes in Preview. In order to make the changes visible on the website for your visitors, you have to approve the Project.

CSS and JS files

CSS and JS files should be stored in your File Manager. The best practice is to create a new folder named the same as your website. Create two other folders, one for CSS (named simply ‘ccs’) and one for JS files (named ‘js’). To connect these styles with your website, edit the Website Template (go to the CMS module and run the Website Templates application). It there are no templates yet, create a new one. Directly into the code, insert this piece of code: <link rel=”stylesheet” type=”text/css” href=”{{ getFileLink( ‘/nameOfYourWebsite/css/style.css’ ) }}”. Instead of ‘style.css’ use the name of your CSS file.

For the JS file do something similar: <script src=”{{ getFileLink(‘/nameOfYourWebsite/js/scripts.js’) }}”/>.

When you need to edit a connected CSS or JS file, you have to go to the File Manager, locate the particular file and double-click on it. It will be automatically opened in a new window and you can edit and save it.

Note

To see the changes in your current Project, use the Preview button. If everything is OK, you have to approve the Project and the changes stored in it will be displayed on the live version of your website. If you want to throw the changes away, you have to delete the whole Project (or revert changes in the single Project mode).

CSS and Images

Sometimes you need to insert an image directly into the CSS codes. You can do it as follows:

background: url( "../images/template/logo.png" );

Resources

If you need to connect resources (such as jQuery), you have to link it in your website template:

<link type="text/css" rel="stylesheet" href="//code.jquery.com/ui/1.11.2/themes/smoothness/jquery-ui.css"/>
<link type="text/css" rel="stylesheet" href="//maxcdn.bootstrapcdn.com/bootstrap/3.3.1/css/bootstrap.min.css"/>
<script type="text/javascript" src="//code.jquery.com/jquery-2.1.3.min.js"></script>
<script type="text/javascript" src="//code.jquery.com/ui/1.11.2/jquery-ui.min.js"></script>
<script type="text/javascript" src="//maxcdn.bootstrapcdn.com/bootstrap/3.3.1/js/bootstrap.min.js"></script>

Special Parameters

  • bbResetZone - if the parameter bbResetZone is a part of the request, it deletes the currently set zone and currency from the session and thus forces a new detection.

  • bbSetZone – if the parameter bbSetZone is a part of the request, it sets the zone according to the internal name (sysid) of the zone specified in the parameter. It also checks if the current currency is available in the new zone. If not, it will be detected.

  • bbSetCurrency - if the parameter bbSetCurrency is a part of the request, the customer’s currency will be set according to it. The parameter value is the currency ISO code (you can use “EUR” or “eur” as well)

Translation Mark

A Translation Mark labels a part of the content that should be translated. This can typically be one sentence, phrase or even a single word. In the code this mark looks as follows:

{{_( ‘Price’ ) }}

Word „Price” is the content that can be translated. All these parentheses, braces, underscore and apostrophes are together creating the translation mark. If you don’t want to type all these marks, there is a button in the Code Editor which generates it automatically.

Note

You can also use a keyboard shortcut CTRL + G to insert a translation mark (G is for gettext).

System Messages

System Messages is an application located in the Administration module. It is used for your information about problems which occurs on your website. In case you struggle when creating a website and need to know if there are some warnings or errors, run this applicaion.

Typically you are creating a new online store. In the Preview mode you can place an order, but there is invoice in the purchase e-mail you have received. In such a case go to the System Messages application and see if there are come problems (for example you did not set up the Document Sequence for the invoice).

Run the application and there is a table with all errors, warnings and information from your account.

Web API

General

Requests beginning with /__api/* allows you to access particular data which you can use mostly for ajax applications. The returned answer is in JSON format and contains the following keys:

  • Success - A value is true or false. Signals if the request was successful. Apart from that you can test it with HTTP status (code 200 or 500).

  • Messages - Array of messages.

  • Errors - Array of errors.

Claims

If you allow your customers to upload attachments (Claim Attachments addon) to their claims, you can use this API for attachment download:

  • /__api/claim/getAttachment?attachmentId=attachmentID - instead of the attachmentID please use the real ID of a particular attachment you want to work with

Orders

In the customer order list and in the partner order list links to download e-shop documents that are connected to a particular order can be displayed.

  • /__api/order/getboughtcontent?orderId=<order id> - download all downloadable products from the order.

  • /__api/order/getboughtcontent?orderId=<order id>&document=<id product document> - download the defined document (product) from the order.

  • /__api/order/get-credit-note - credit note connected with particular order.

  • /__api/order/get-invoice - invoice connected with particular order.

  • /__api/order/get-order-document - order document connected with particular order.

  • /__api/order/get-packing-list - packing list connected with particular order.

  • /__api/order/get-proforma-invoice - proforma invoice connected with particular order.

  • /__api/order/get-partner-invoice - partner invoice connected with particular order.

  • /__api/order/get-partner-proforma-invoice - partner proforma invoice connected with particular order.

  • /__api/order/get-partner-credit-note - partner credit note connected with particular order.

  • /__api/order/has-serial-number - required parameter serialNumber contains the value of the controlled number. The key hasSerialNumber contains the result (true or false).

  • /__api/order/get-coupon-card - returns PDF of the coupon card (contains the purchased voucher code). Required parameter is dispatch which contains ID of the product dispatch (ID is available in order detail data). Optional parameter is accessToken (used to access the file for not logged users).

Requests are used to access particular documents. The required parameter is the orderId.

Example in the order list:

{% if proformaInvoices[order.id] != false %}
        <a target="_blank" href="/__api/order/get-proforma-invoice?orderId={{ order.id }}">
                {{ Proforma Invoice }}
        </a>
{% endif %}
  • /__api/order/get-order-attachment - returns an attachment of an order, required parameter is attachmentId.

  • /__api/order/get-order-product-attachment - returns an attachment to an ordered product, required parameter is productId.

  • /__api/order/get-order-temporary-attachment - returns an attachment of an order from a temporary storage, required parameter is key, its value is array arrachment (ecommerce.cart.attachments). Optional parameter is download (boolean value) which can be used to force downloading.

  • /__api/order/get-image - returns images connected to a particular order, required parameter is orderId or productId. Other parameters are orderID (ID of an order), productID (ID of a product on an order), page (page number used if there is more than 50 images for the order. Usually, it is possible to download 50 images at once).

  • /__api/order/disable-order-subscription - used to disable order subscription. Required parameter is the ID of an order (orderID) which subscriptions should be canceled: /__api/order/disable-order-subscription?orderId={{ orderId }}

Shopping Cart

  • /__api/cart - Returns information about shopping cart - key cart (price Info, items, delivery Method, payment Method) - analogical to the Cart form.

  • /__api/cart/summary - Returns basic information about shopping cart - key cart (price Info, total Items).

  • /__api/cart/items - Returns content of shopping cart (key items). Every record contains properties such as gross Price, quantity, name etc.

  • /__api/cart/empty - Empties shopping cart.

  • /__api/cart/add - Adds items to the shopping cart. Use the attachment parameter to define the attachment of the added product (the uploaded file will be inserted as product’s attachment). With the return parameter you can specify the data set of returning data:

    <script type="text/javascript">
            $(document).ready( function() {
                     var data = [ {
                      code: 'prod1', // product code
                      quantity: 2
                     } ];
    
                     $.ajax( '/__api/cart/add', {
                      data: {
                       items: JSON.stringify( data )
                      }
                     } );
            } );
    </script>
    
    For subscription products a :ref:`subscription start date<doc-subscription-start-date>` can be defined. Use the field startDate (it contains a date in the UTC timezone)::
    
            /__api/cart/add?items=[{"code":"00340","quantity":"1","startDate":"2018-01-01"}]&return=cart
    
    You can also use the *useAvailableQuantity* parameter (boolean value; set to FALSE as default); Set to TRUE: if the available product quantity is lower than the requested quantity, all available products will be added to the cart. Set to FALSE: if the available product quantity is lower than the requested quantity, no products will be added to the cart.::
    
            /__api/cart/add?items=[{"code":"02040","quantity":"60","useAvailableQuantity":true}]
    
    To add an Add-On product use the *accessories* parameter::
    
            /__api/cart/add?items=[{"code":"41111018","quantity":"1","accessories":[{"code":"9004111100"}]}]
    
  • /__api/cart/delete - Removes items form shopping cart. Example of use (you can use code or price List Item parameter):

    <script type="text/javascript">
            $(document).ready( function() {
             var data = [ {
              code: 'prod1', // product code
              quantity: 3
             } ];
    
             $.ajax( '/__api/cart/delete', {
              data: {
               items: JSON.stringify( data )
              }
             } );
            } );
    </script>
    
  • /__api/cart/update - Sets cart items quantity to requested value, return parameter can define the set of returned data. The key cart returns the cart content (the cartItemId key can be used instead of the code key):

    <script type="text/javascript">
    $(document).ready( function() {
            var data = [ {
                    code: 'prod1', // product code
                    quantity: 2
            } ];
    
            $.ajax( '/__api/cart/update', {
                    data: {
                            items: JSON.stringify( data )
                    }
            } );
    } );
    </script>
    
  • /__api/cart/addFromOrder - Creates a copy of an existing order. Required parameter is orderId=123, where 123 is order ID. The user must be logged in, otherwise the order data can not be obtained. Order products are searched by the product code. You can also use the Add from Order widget for this functionality.

  • /__api/cart/item/add - Adds one item in shopping cart. The code parameter has to contain a Code of a particular Product you want to add. You can also use the parameter quantity (optional) which determines the count of items that will be inserted in the shopping cart.

  • /__api/cart/item/delete - Removes one item from the shopping cart. The code parameter has to contain a Code of a particular Product you want to remove. You can also use the parameter priceListItem for that (this parameter identifies the item in the shopping cart). Optionally you can use the parameter quantity that defines the count of items that will be removed.

  • /__api/cart/item/update - Updates one item from the shopping cart. The code parameter has to contain a Code of a particular Product you want to update. You can also use the parameter priceListItem for that (this parameter identifies the item in the shopping cart). The quantity parameter has to contain the quantity of the Product.

  • /__api/cart/voucher/add - Inserts a voucher into the cart (parameter code carries a particular voucher code).

  • /__api/cart/voucher/delete - Removes a voucher from the cart (parameter code carries a particular voucher code).

  • /__api/cart/gifts/set - Used to select/add gifts to the cart:

    • gifts - JSON string containing encrypted definition array (objects) of gifts. Each element consists of parameters sale, products.

    • sale - the internal name of the gift settings. In the template (for the first gift) can be obtained as follows: ecommerce.cart.gifts[0].sale.sysid.

    • products - an array of objects with defined product (product) with its quantity (quantity).

    • product - the code of a product. In the template (for the first gift and first product) can be obtained as follows: ecommerce.cart.gifts[0].products[0].code.

    • returning parameter gifts - if you use is, information about the selected gifts will be a part of the answer.

    Example:

    /__api/cart/gifts/set?gifts=[{"sale":"fancy-gifts","products":[{"product":"CODE","quantity":2}]}]&return=gifts
    
    {
            "success": true,
            "messages": [],
            "errors": [],
            "gifts": [
                    {
                            "sale": "fancy-gifts",
                            "products": [
                                    {
                                            "product": "CODE",
                                            "quantity": 2
                                    }
                            ]
                    }
            ]
    }
    

Note

With Shopping Cart can be also used formatted values for these types: ‘taxInclusiveDiscount’, ‘taxExclusiveDiscount’, ‘taxExclusiveAmount’, ‘taxInclusiveAmount’, ‘taxExclusiveAmountRounded’, ‘taxInclusiveAmountRounded’, ‘taxAmount’, ‘taxAmountRounded’, ‘taxExclusiveTaxDocRoundAmount’, ‘taxInclusiveTaxDocRoundAmount’, ‘taxDocTaxRate’, ‘taxDocRoundTaxAmount’, ‘totalAmount’, ‘taxInclusiveUnitPrice’, ‘taxInclusiveUnitPriceRounded’, ‘taxExclusiveUnitPrice’, ‘taxExclusiveUnitPriceRounded’, ‘taxExclusiveItemAmount’, ‘taxInclusiveItemAmount’. For every value is used prefix ‘formatted’. Example: ‘formattedTaxInclusiveItemAmount’

Product

  • /__api/product/detail - Returns information about the Product (key product) - the required parameter is code (the code of a particular product).

  • /__api/product/getDetail - Returns information for the entered product code - the required parameter is code (the code of the product we want to get the information about). The return parameter specifies the items you want to return about the product. The product data (output) is stored under the key product. Only active products are returned:

    /__api/product/getDetail?code=41111022&return=id,isBuyable,inventory.availableAmount
    
  • /__api/product/getDetails - This API is used to get information about more products (for more info see the getDetail above. The ‘codes’ parameter should contain the list of products’ codes you want to get the information about:

    /__api/product/getDetails?codes=[%2241111022%22,%2241111048%22,%2241111012-M%22]&return=isBuyable,inventory.availableAmount
    
  • /__api/product/search - Returns information about found Products. Parameter required is text (the searched term).

  • /__api/product/stock - Returns information about stock (key product). Parameter required is code (one code or more codes separated by a comma). An array with particular keys code, availableAmount and scheduledDeliveries (data, quantity) are returned.

Wishlist

  • /__api/wishlist/add - Adds a Product in Wishlist. Required parameter is code (example: “/__api/wishlist/add?code=a” adds a Product with the Code “a”).

  • /__api/wishlist/delete - Removes a Product from Wishlist. Required parameter is code (example: “/__api/wishlist/delete?code=a” removes a Product with the Code “a”).

  • /__api/wishlist/empty - Empties the Wishlist (example: “/__api/wishlist/empty”).

  • /__api/wishlist/getproducts - Returns Products to Wishlist (example: “/__api/wishlist/getproducts”).

  • /__api/wishlist/getProductCodes - Returns a list of all products codes (products key) that are in the wishlist.

  • /__api/wishlist/summary - Returns information about the total count of items in Wishlist (key wishlist.totalItems).

Note

If a user is not logger in, the data from wishlist are stored only in his/her session (data are available only on the single device where the user worked). For loged users are stored permanently as a part of their user account (if the user loggs in, these data are available on every device).

Information about a Product in the Wishlist:

ecommerce.wishlist.hasProduct('product-code')

Instead of the product-code use the product code of a particular product for which you want to get the information if it is currently inserted in the wishlist (true/false). For more information see related wishlist help-site.

Comparator

  • /__api/comparator/add - Adds a Product in the Comparator. Required parameter is code (a Code of a particular Product). Example: “/__api/comparator/add?code=a” adds a Product with the Code “a”.

  • /__api/comparator/delete - Removes a Product from Comparator. Required parameter is code (a Code of a particular Product). Example: “/__api/comparator/delete?code=a” removes a Product with the Code “a”.

  • /__api/comparator/empty - Empties the Comparator.

  • /__api/comparator/getproducts - Returns Products to Comparator.

  • /__api/comparator/getProductCodes - Returns a list of all products codes (products key) that are in the comparator.

  • /__api/comparator/summary - Returns information about the total count of items in Comparator (key comparator.totalItems).

Note

If a user is not logged in, the data from comparator are stored only during his/her session (data are available only on the single device where the user worked). For loged users, it is stored permanently as a part of their user account (if the user loggs in, these data are available on every device).

Information about a Product in the Comparator:

ecommerce.comparator.hasProduct('product-code')

Instead of the product-code use the product code of a particular product for which you want to get the information if it is currently inserted in the comparator (true/false). For more information see related comparator help-site.

Eshop

Example:

/__api/EShop/welcome-voucher-add?email=support@bizbox.cz

It is validated that the email has not been used yet.

Delivery

  • /__api/czechpost/getparceldeliveryoffice - Search for particular Czech Post that is available for the packet “On the Post” service. Required parameter is “search” - the name or a part of the name of particular post or postal code. This is used only for the Czech Post to define the availability of the On the Post packet service.

  • /__api/pickuppoint/get-parcel-delivery-points - Search for particular pick up points. There is also the option to search in addresses. Typically, pickup points are only searched by name or postal code if the text is numeric. Address search is normally disabled and is set by the ‘searchAddresses’ parameter, which only checks for presence and does not have any value. Example:

    /__api/pickuppoint/get-parcel-delivery-points?search=jaromerice&service=ppl&country=CZ&searchAddresses
    

List of available service parameters:

Service Sysid

Service Name

czech-post

Česká pošta

zasilkovna

Zásilkovna

dpd

DPD

ulozenka

Uloženka

ppl

PPL ParcelShop

czech-post-balikovna

Česká pošta - Balíkovna

personal

Personal

gls

GLS ShopDelivery

ulozenkaPartner

Uloženka partner

mallBox

MALL box

slovenskaPostaExpresNaPostu

Slovenská Pošta - Expres na poštu

slovenskaPostaBalikobox

Slovenská Pošta - BalíkoBOX

depoSk

Depo SK

ulozenkaWedoSkCz

Uloženka - WEDO SK-CZ

inPostPaczkomaty

InPost - Paczkomaty

bgSpeedy

BG Speedy

frColissimo

FR Colissimo

hrCroatianPost

HR Croatian Post

esMrw

ES MRW

ptMrw

PT MRW

sePostNord

SE Post Nord

fiPostNord

FI Post Nord

siDpd

SI DPD

dkPostNord

DK Post Nord

eeOmniva

EE Omniva

eeOmnivaBox

EE Omniva Box

lvOmnivaBox

LV Omniva Box

ltOmnivaBox

LT Omniva Box

deHermes

DE Hermes

bgEcont

BG Econt

bgEcontBox

BG Econt Box

roSamedayBox

RO Sameday Box

grAcs

GR ACS

beBelgianPost

BE Belgian Post

nlDhl

NL DHL

itBartolini

IT Bartolini

hrOverseas

HR Overseas

siPost

SI Post

siPostBox

SI Post Box

uaNovaPoshta

UA Nova Poshta

frMondialRelay

FR Mondial Relay

plPolskaPosta

PL Polska Posta

ltLithuanianPostPox

LT Lithuanian Post Box

grBoxNowBox

GR Box Now Box

sps

SPS - Slovak Parcel Service

Product Catalog Component

Product Catalog Component Filters

  • /__api/productCatalog/filterStates - A request to get information about the current count of products, which meet particular filters. Only one parameter productFilters is used and it has to contain all user and system defined filters, which are currently applied on the Product List in the Product Catalog Component. Example: productFilters={“categoryWithChildren”:true,”category”:[“432”],”basic-color”:[“BTR”],”brand”:[“85”]}. In JSON answer under the key filterStates the overview of user filters and its items (value is the total count of product that meet applied filters. Example filterStates”:{“basic-color”:{“B00”:2,”BTR”:1},”brand”:{“bohemia”:1}} ) is defined.

  • /__api/productCatalog/productList - This request returns data about products (the structure is the same as in the Product Catalog Component). You are able to restrict such as in the filterStates request using the productFilters parameter. Supported filters ares the same as for filterStates. Example: /__api/productCatalog/productList?productFilters={%22priceMin%22:%22500%22,%22filter-color%22:[%22red%22]}

Note

If the Use New Component Parameters parameter is enabled on the website, the filter parameter is used.

List of supported filters

  • available - restriction on products that are currently on stock or their marketability type is set to always;

  • brand restriction on particular brands (array of IDs);

  • category - restriction on a particular category (array of IDs);

  • extraEntity - restriction on particular extra entities (array of IDs);

  • fulltext - full text search;

  • inStock - products with a stock supply larger than the specified quantity (products that are currently on stock);

  • manufacturer - restriction on particular manufacturers defined by its ID (array of IDs);

  • priceMin - products with a price not exceeding the value entered (inclusive);

  • priceMax - products with a price at least up to the value entered (inclusive);

  • productCode - products with defined codes (array of codes);

  • ratingCountMin - products that have at least the specified number of product ratings;

  • tag - restriction on particular tags (array of IDs);

  • All other filters are considered to be internal name (sysid) of a customProperty; filtering is applied according to its value. The customProperty filter can have prefixes min-, max- or like-. Then the operator is used instead of equality >= (min-), <= (max-) or LIKE (like-).

  • saleRateMin - allows you to select products by its discount rate. The value is the discount percentage; decimal numbers are supported;

  • stock - products that are available at the selected stock. Stock are always taken from the stock service of the current e-shop (value is the internal name of the stock);

  • system.new - the value can be anything but NULL, it does not matter because it works with the current time - displays newly added products (for last 60 days).

Product Catalog Component Filters

You can use the parameter productSorters to sort products on the web. The parameter specifies a sort key with a value of asc or desc for ascending or descending sorting.

Note

If the Use New Component Parameters parameter is enabled on the website, the orderBy parameter is used.

List of available sorters

  • category - sort by category

  • code - sort by product code

  • created - sort by creation date

  • inStock - sort by stock availability (yes / no)

  • name - sort by name

  • price - sort by price

  • rating - sort by product rating

  • ratingCount - sort by number of ratings

  • relevance - srot by relevance

  • relevanceInCategory - sort by relevance in a category

  • sales - sort by sales

  • stock - sort by stock condition

Note

For information about general sorting, see the component settings.

Paginator

  • Number of items on the page - The productsPerPage parameter is used to determine the number of items on the page.

    Note

    If the Use New Component Parameters parameter is enabled on the website, the perPage parameter is used.

  • Current Page - the current page is defined by the productPage parameter

    Note

    If the Use New Component Parameters parameter is enabled on the website, the page parameter is used.

Newsletter

  • /__api/newsletter/add-email - a method used to add an e-mail to a newsletter. Required parameters are: email (customer’s e-mail address) and newsletter (internal name of particular newsletter). Customer can request e-mail assign repeatedly, but the e-mail address itself will be added to the list only once.

  • /__api/newsletter/delete-email - a method used to remove a particular e-mail from a newsletter. Required parameters are: email (customer’s e-mail address), newsletter (internal name of a particular newsletter) and hash (generated to delete particular e-mail address).

Product Rating

  • /__api/productRating/add - used to add a rating for particular product. Required parameters are: product (a particular product code), rating (product rating), recommends (boolean value which defines if a customer recommends the product). Optional parameters are: pros, cons, title and comment.

  • /__api/productRating/comment-add - used to add a comment to an existing product rating. Required parameters are: replyTo (the ID of a comment to which is the user replying), comment (text of the comment), email (required only for a not logged user). Optional parameters are: name (name of the user who comments) - these parameters are ignored for logged in users.

  • /__api/productRating/vote-add - used to add a vote for an existing comment. Required parameters are: comment (the ID of a comment for which is the user voting), vote (positive/negative vote).

Photoalbum Component

  • /__api/imagealbum/getimages?albumId=1 - used to download images from particular album (defined by the albumId). Parameters: albumId - required; ID of the album; keyword - the keyword that the image must contain, unless all the images in the album are returned; page the batch number that will be downloaded, if omitted, the first batch is downloaded. Images are downloaded in batch sizes of 50, if a single image is returned, it is downloaded directly. This feature can be used only for albums with the Source Available setting enabled.

Customer Alerts

  • /__api/customerAlert/add - adding a customer alert; required parameter product must contain the product code for which the alert is to be added. If the user is not logged in, the email parameter is required.

  • /__api/customerAlert/remove -remove a customer alert; required parameter customerAlert must contain the ID of the customer alert you want to delete.

Shopping Lists

Note

All Shopping Lists actions are available only for logged-in users.

Note

The quantity must always be greater than or equal to 1.

  • /__api/shoppingList/getLists - Gets a list of all shopping lists.

  • /__api/shoppingList/getListsWithProduct - Gets a list of all shopping lists that contains particular product. Required parameter is product (the code of a product which will be searched on existing shopping lists).

  • /__api/shoppingList/getListsWithProducts - Gets a list of all shopping lists that contains particular products. Required parameter is products (JSON array - product codes which will be searched on existing shopping lists).

  • /__api/shoppingList/add - Add product to shopping list. Required parameters are shoppingListId (the ID of a particular shopping list) and product (the code of the product you want to update). Optional parameter is quantity (new product quantity; implicitly 1).

  • /__api/shoppingList/update - Change product in shopping list. Required parameters are shoppingListId (the ID of a particular shopping list), product (the code of the product you want to update) and quantity (product quantity).

  • /__api/shoppingList/remove - Removes product from the shopping list. Required parameters are shoppingListId (the ID of a particular shopping list) and product (the code of the product you want to remove).

  • /__api/shoppingList/addToCart - Adds products from the shopping list to the cart. Required parameter is shoppingListId (the ID of a particular shopping list).

Template and component

  • /__api/template/get - used for template rendering;

  • /__api/component/get-block - used for component block rendering;

Both accepts the optional format parameter; available values are:

  • xlsx, the result is an XLSX file.

  • pdf, the result is a PDF file.

Without a parameter or if there is no xlsx/PDF format, the result is always HTML. The filename can be specified with the optional filename parameter. If the parameter is missing, the file name consists of the internal name of the used template/block and the extension “.xlsx” or “.pdf”.

ARES

ARES is Administrativní registr ekonomických subjektů (it is used only in the Czech Republic).

  • /__api/ares/get?ico=27074358 - Allows you to retrieve information about the company according to the specified company ID.

Response:

{"success":true,"messages":[],"errors":[],"ares":{"identificationNumber":"27074358","taxIdenity":"CZ27074358","companyName":"Asseco Central Europe, a.s.","streetAddress":"Budějovická 778/3a","city":"Praha","postalCode":"14000"}}

Note

If the company ID is not found, the response has the “success” set to FALSE.

Blocks

Extend a template from another one

Using the twig, you can benefit from the extends tag. For more info see the twig documentation (tag extends or block).

Template is a piece of code (a visual part of a website) that is used as a design wrap of content (text, images, products, cart,…) you present on your website in a form of content of component pages.

A website template used as a visual wrap must have defined a place, where the content (particular content page or component page) will be placed.

Mark the particular place in the website template like this:

{% block content %}{% endblock %}

Between these marks will be the block (code content) of a page inserted. Remember that you have to mark the content of a page with these marks like this:

{% block content %}
        HTML code of a content page.
{% endblock %}

It means that in the beginning and ending of the page will be these marks.

Note

Remember that you must select the particular website template that will be used for the page in its settings (Template field on the General tab). Without it is BizBox unable to use required template.

Include

Include includes required content into the current page or template. For more information about include, please see the twig include documentation.

Include Template

You can also insert a template into your code:

{% include '@template/template-internal-name' %}

Instead of the template-internal-name use the real internal name of a template you want to insert. Always the latest (most current) version of the website template will be rendered. It can be both Website Template and Template.

Apart from that can be a Website Template or Template used as a storage for another codes you are using repeatedly on your website, such as side pannels (banners) or menus displayed only on specific pages. You will insert the mark where will be the template inserted directly into the code of the page.

Include Page

You can include an existnig page in to another page or template:

{% include '@page/page-internal-name' %}

Instead of the page-internal-name insert the real name of a page you want to include into your page or template.

Include Content

To include a content, use this construction:

{% include '@content/content-internal-name' %}

Instead of the content-internal-name insert the real name of a content you want to include into your page or template.

Template from String

To include a description (mostly used for products and its categories) that contains another twig macros of functions, you should use the template_from_string:

{{ include(template_from_string(component.product.description)) }}

This code includes a particular product description (used in the Product Catalog Component).

Images

To display an image, you have to use the Twig function getFileLink. It generates a link to a file from the File Manager. Second parameter is a bool value, which defines if into the final link will be generated unique link (default value is set to TRUE). Third parameter is bool value defining the usage of a CDN (defalut value is set to TRUE). Fourth parameter is a bool value which defines the generation of abslout URL address (default value is set to TRUE).

Example:

{{ getFileLink( '/folder/images/image.png' ) }}

Example used in a website code:

<img width="700" height="310" src="{{ getFileLink( '/folder/images/image.png' ) }}" alt="Image" />

Website Info

Pages URL

For all or your pages you can display or use their URL address (both absolute and relative). There are two types of parameters you can use for it:

  • {{ request.page.url }} – this is the relative URL address of a page. For example something like /products-catalog/products

  • {{ request.page.fullUrl }} – this is the absolute URL address of a page of even a view of a Component. For example it can look like http://bizboxlive.com/pricing

SEO Settings

You are able to set up the SEO settings for every page on your website, including the product details, articles and categories for products and articles.

Pages SEO Settings

Every page from your page tree (in the Website Editor) contain an SEO tab. Here you are able to set up the Title, Description, Keywords and other settings. Remember that these fields are translated and you are able to insert the translations for every culture from your Culture Tree (in case your website is multilingual). For more information about particular page types please visit the related help-sites.