Skip to main content

Category Trees

Category Tree is the structure where categories/subcategories are created for the products to go on sale. Category tree in Omnitron is formed by the combination of two different structures: CategoryTree and CategoryNode.

Campaigns

On the Catalogs page Products and Catalogs > Catalogs, the detail page is entered through a catalog.

The pen icon that appears when the relevant category point is hovered with the cursor is clicked on. This opens the Category Edit form. Clicking on the Campaigns tab, and then the Add Campaign button, allows adding campaigns. After filling in the required information, the Save button at the bottom is clicked on. Campaigns added here are reflected on the page of the relevant sales category.

Large Image

On the Catalogs page Products and Catalogs > Catalogs, the detail page is entered through a catalog.

The pen icon that appears when the relevant category point is hovered with the cursor is clicked on. This opens the Category Edit form. The Large Image tab is clicked on for the addition of large images. After filling in the required information, the Save button at the bottom is clicked on. The Large Image added here is reflected on the page of the relevant sales category.

Small Image

On the Catalogs page (Products and Catalogs > Catalogs), the detail page is entered through a catalog.

The pen icon that appears when the relevant category point is hovered with the cursor is clicked on. This opens the Category Edit Form. The Small Image tab is clicked on for the addition of small images. After filling in the required information, the Save button at the bottom is clicked on. The Small Image added here is reflected on the page of the relevant sales category.

Explanation

On the Catalogs page Products and Catalogs > Catalogs, the detail page is entered through a catalog.

The pen icon that appears when the relevant category point is hovered with the cursor is clicked on. This opens up the Category Edit Form. The details about the relevant category are entered in the description field and the Save button at the bottom is clicked on. The description added here is reflected on the page of the relevant sales category.

Model Structure

CategoryTree

Location: omnitron.catalogs.models.CategoryTree

  • name: CharField

    Contains the name of the category tree. Its maximum length is 64 characters.

  • category_root: OneToOneField

    Linked to the CategoryNode model. Indicates the root record of the created category tree. Only CategoryNodes with a depth of 1 can be pointed to.

CategoryNode

Inherited from omnicore.eav.models.Entity, from treebeard.mp_tree.MP_Node and omnicore.utils.models.UUIDStarterModel.

Location: omnitron.catalogs.models.CategoryNode

  • order: IntegerField

    Allows to determine the sorting of categories at the same level.

    It is 1 by default.

  • name: CharField

    It is the name of the category. Its maximum length is 64 characters.

  • remote_attributes: JSONField

    Category properties from integrations are hosted here.

  • sort_option: ForeignKey

    Indicates the sorting algorithm implemented for the relevant category.

  • marketplace_attribute_set: ForeignKey is linked to MarketPlaceAttributeSet. It is intended to contain the features of the category corresponding to the relevant category point in the sales channel.

Functions

● has_products() Returns boolean whether there is a product under the corresponding CategoryNode.

Serializer Structure

CategoryTree

Location: omnitron.catalogs.resources.serializers. CategoryTreeSerializer

Unlike the model structure, it contains pk, name and category_root. Category_root is read-only. The category_root field also sends the details of the underlying data.

CategoryNode

Location: omnitron.catalogs.resources.serializers.CategoryNodeSerializer

Pk, name, order, node, numchild, dept, attributes, attributes_kwargs, sort_option, uuid and path parameters. In addition, _path, attributes_kwargs and uuid are read-only and not required fields. It is presented as localized in attributes_kwargs and attributes in the presentation layer.

Service Structure

CategoryTree

Location: omnitron.catalogs.resources.service.CategoryTreeService

  • create_category_tree(name)

    This function allows creating a category tree. It first checks for an existing category tree with the same name. If there is a record with the same name, it returns CategoryTreeDuplicatedFieldException. First, a CategoryNode is created for the root record requirement. The CategoryNode is then assigned as the category_root of the CategoryTree to be created, and the CategoryTree is created with the input name.

  • delete_category_tree(instance)

    This function gets the CategoryTree object. Firstly, it calls delete_category_root_node function from CategoryNode service. After that it completes the deleting process of the given instance. These transactions are executed automatically. If an error occurred during the process, all of the changes revert back.

CategoryNode

Location: omnitron.catalogs.resources.service.CategoryNodeService

  • create_category_root_node(name, **kwargs)

    This function transfers the incoming data to the add_root function of the CategoryNode model. The add_root function is an inherited feature from MP_Node.

  • create_category_child_node(node, name, **kwargs)

    This function creates a subcategory point with the ’name’ given to the ’node’ with data provided as parameters. It is first checked whether the entered category point has a sub-category with the same name. Afterwards, the subcategory is created as an atomic operation and the attributes sent in kwargs are transferred to the subcategory.

  • update_category_node(node, name=None, **kwargs)

    In this function, it is primarily checked whether there is a record that has the same name as the node provided as a parameter, and is linked to the same category point. Based on the translations of attributes in kwargs, it is written in the relevant node. The sorting_option in kwargs is transferred to the node. It is recorded in the relevant node and returned.

  • delete_category_root_node(root)

    The has_products function is called over the CategoryNode model. If there are products in subcategories, *CategoryNodeDeleteException is thrown. If there is none, deletion takes place.

  • delete_category_child_node(node)

    If the node provided as a parameter is root, it throws a CategoryRootDeleteException. Then it is questioned whether there is a product under the node provided as a parameter.

    If there is any, it throws a CategoryNodeDeleteException . If it makes it through these checks, the relevant node is deleted.

  • move (node, target, pos)

    The move function inherited from MP_Node is called with the parameters supplied. The subcategories linked to the relevant node are then recorded.

View Structure

CategoryTree

Location: omnitron.catalogs.resources.views.CategoryTreeViewSet``GET, POST, PATCH, PUT and DELETE request types are allowed.

Like other viewsets, create, update and destroy are performed through the service. Details of the aforementioned “Service Structure” are available.

Category Tree Methods

GET All Category Trees

Sample HTTP request to get all category trees lists from the system.

‘content_type’ header represents the response type.

The ‘Authorization’ header is required for authentication. You can retrieve api_token by logging in.

Request

Path: /api/v1/category_tree/

import requests

url = "https://{customer_api_url}/api/v1/category_tree/"
api_token = "API TOKEN"

headers = {
'content-type': 'application/json',
'Authorization': 'Token {}'.format(api_token)
}

response = requests.get(url, headers=headers)
print(response.text)

Filters

All fields except the existing “category_root” can be used in the CategoryTree model.

Response

{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"pk": 1,
"name": "test catalog",
"category_root": {
"pk": 246,
"name": "test catalog",
"order": 1,
"numchild": 0,
"depth": 1
"attributes": {},
"attributes_kwargs": {},
"sort_option": null,
"uuid": "2798d37e-7a04-487f-a693-fa0c4b174656",
"path": "0001",
"created_date": "2021-10-06T13:48:07.643569Z",
"modified_date": "2021-11-01T13:54:52.526750Z"
}
}
]
}

POST Create Category Tree

Records new objects in the CategoryTree table. The CategoryTreeSerializer class defined at omnitron.catalogs.resources.serializers is used to validate the data.

‘content_type’ header represents the response type.

The ‘Authorization’ header is required for authentication. You can retrieve api_token by logging in.

Request

Path: /api/v1/category_tree/

import requests

url = "https://{customer_api_url}/api/v1/category_tree/"
api_token = "API TOKEN"

headers = {
'content-type': 'application/json',
'Authorization': 'Token {}'.format(api_token)
}

data = {
"name" : "new_tree"
}

response = requests.post(url, headers=headers, data=data)
print(response.text)

If there is another category tree with the same name, a 400 response status code is returned.

Response

Information of the created CategoryTree object is returned. The features are described above. The status code will be 201.

{
"pk": 2,
"name": "new_tree",
"category_root": {
"pk": 247,
"name": "new_tree",
"order": 1,
"numchild": 0,
"depth": 1,
"attributes": {},
"attributes_kwargs": {},
"sort_option": null,
"uuid": "06e18786-74c6-4c3c-a8dc-60e7a5dd494a",
"path": "0002",
"created_date": "2022-12-21T07:50:08.386058Z",
"modified_date": "2022-12-21T07:50:08.386095Z"
}
}

Incorrect Response Example

CategoryTree model has a name field and its property is unique=True, which means the category name field must be unique. Otherwise it will display an error as shown below.

{
"name": [
"category tree with this name already exists."
]
}

PATCH - PUT Update Category Tree

If not found, it returns a 404 response status code.

If a record with an existing “name” is being attempted, this returns a 400 response status code.

Path: /api/v1/category_tree/{pk}/

{
"name" : "new_tree__"
}

Response


{
"pk": 6,
"name": "new_tree__",
"category_root": {
"pk": 247,
"name": "new_tree",
"order": 1,
"numchild": 0,
"depth": 1,
"attributes": {},
"attributes_kwargs": {},
"sort_option": null,
"uuid": "06e18786-74c6-4c3c-a8dc-60e7a5dd494a",
"path": "0003",
"created_date": "2022-12-21T07:50:08.386058Z",
"modified_date": "2022-12-21T07:50:08.386095Z"
}

}

Incorrect Response Example

If an existing tree name is inserted during the update, it will again throw a unique error for the name field.

{
"name": [
"category tree with this name already exists."
]
}

DELETE Category Tree

If the category tree is not found, it returns a 404 response status code.

If the category tree with provided ID is linked to a catalog or if there are products linked to the category tree, a 400 response status code will be returned.

Path: /api/v1/category_tree/{pk}/

Response

Status: 204

Incorrect Response Example

If the shop is still used by some catalog(s), the status code (406) is returned. This means Not Acceptable for deletion.

{
"non_field_errors": "Shop is still being used by some catalog(s).",
"error_code": "category_600_6"
}

GET Category Tree

Tree returns the relevant category tree with its sub branches. If the category tree with provided ID is not available, it returns a 404 response status code.

Path: /api/v1/category_tree/{pk}/tree/

Response

[
{
"pk": 1,
"name": "new_tree",
"order": 1,
"numchild": 8,
"depth": 1,
"attributes": {},
"attributes_kwargs": {},
"sort_option": 1,
"uuid": "cf108732-fa7c-4f0f-9bea-fb59691a9d7c",
"path": "0001"
},
{
"pk": 4,
"name": "Test Child",
"order": 1,
"numchild": 12,
"depth": 2,
"attributes": {
"campaigns": [],
"big_image": {
"url": "test-child",
"image": "cms/2021/02/08/
e1f3fb64-98f2-4f8e-ad0a-4178a775c087.jpg",
"title": "Test Child"
},
"small_image": {
"url": "test-child",
"image":
"cms/2021/02/08/7bcbcec5-b468-475b-b45e-e9f567151a94.jpg",
"title": "Household Linen"
},
"description": ""
},
"attributes_kwargs": {
"campaigns": [],
"big_image": {
"value": {
"image":{
"url": "/media/cms/2021/02/08/e1f3fb64-98f2-4f8e-ad0a-4178a775c087.jpg",
"value": "cms/2021/02/08/e1f3fb64-98f2-4f8e-ad0a-4178a775c087.jpg",
"data_type":"image"
}

},
"data_type": "nested"
},
"small_image": {
"value": {
"image": {
"url": "/media/cms/2021/02/08/7bcbcec5-b468-475b-b45e-e9f567151a94.jpg",
"value": "cms/2021/02/08/7bcbcec5-b468-475b-b45e-e9f567151a94.jpg",
"data_type": "image"
}

},
}]

Tree Detailed

Returns the relevant category tree with its sub branches in a more detailed manner. If the category tree is not found, it returns a 404 response status code.

GET Category Tree Detail

Retrieves detailed information about category_tree. Shows details of sort option information and sorting algorithm information, as well as the associated child information in a list.

Request


import requests

url = "https://{customer_api_url}/api/v1/category_tree/{PK}/tree_detailed/"
api_token = "API TOKEN"

headers = {
'content-type': 'application/json',
'Authorization': 'Token {}'.format(api_token)
}

response = requests.get(url, headers=headers)
print(response.text)

Path: /api/v1/category_tree/{pk}/tree_detailed/

Response


[
{
"pk": 1,
"name": "Shop",
"order": 1,
"numchild": 8,
"depth": 1,
"attributes": {},
"attributes_kwargs": {},
"sort_option": {},
"uuid": "cf108732-fa7c-4f0f-9bea-fb59691a9d7c",
"path": "0001",
"children": [
{
"pk": 43,
"name": "Test Child",
"order": 1,
"numchild": 12,
"depth": 2,
"attributes": {
"campaigns": [],
"big_image": {
"url": "test-child",
"image": "cms/2021/02/08/e1f3fb64-98f2-4f8e-ad0a-4178a775c087.jpg",
"title": "Test Child"
},
"small_image": {
"url": "test-child",
"image": "cms/2021/02/08/7bcbcec5-b468-475b-b45e-e9f567151a94.jpg",
"title": "Test Child"
},
"description": ""
},
"attributes_kwargs": {
"campaigns": [],
"big_image": {
"value": {
"image": {
"url":
"/media/cms/2021/02/08/e1f3fb64-98f2-4f8e-ad0a-4178a775c087.jpg",
"value": "cms/2021/02/08/e1f3fb64-98f2-4f8e-ad0a-4178a775c087.jpg",

"data_type": "image"}
},
"data_type": "nested"
},
"small_image": {
"value":{
"image": {
"url": "/media/cms/2021/02/08/7bcbcec5-b468-475b-b45e-e9f567151a94.jpg",
"value": "cms/2021/02/08/7bcbcec5-b468-475b-b45e-e9f567151a94.jpg",

"data_type": "image"

}
"data_type": "nested"
}
},
"sort_option": 12,
"uuid": "9ea60027-c3a0-4cc3-9acc-6ecc462b1589",
"path": "00010001"
}
]
},
{

"pk": 43,
"name": "Test Child",
"order": 1,
"numchild": 12,
"depth": 2,
"attributes": {
"campaigns": [],
"big_image": {
"url": "test-child",
"image": "cms/2021/02/08/e1f3fb64-98f2-4f8e-ad0a-4178a775c087.jpg",
"title": "Test Child"
},
"small_image": {
"url":"test-child",
"image": "cms/2021/02/08/7bcbcec5-b468-475b-b45e-e9f567151a94.jpg",
"title": "Test Child"
},
"description": ""
},
"attributes_kwargs": {
"campaigns": [],
"big_image": {
"value": {
"image": {
"url": "/media/cms/2021/02/08/e1f3fb64-98f2-4f8e-ad0a-4178a775c087.jpg",
"value": "cms/2021/02/08/e1f3fb64-98f2-4f8e-ad0a-4178a775c087.jpg",

"data_type":"image"}
},
"data_type": "nested"
},
"small_image": {
"value": {
"image": {
"url": "/media/cms/2021/02/08/7bcbcec5-b468-475b-b45e-e9f567151a94.jpg",
"value": "cms/2021/02/08/7bcbcec5-b468-475b-b45e-e9f567151a94.jpg",
"data_type": "image"}
},
"data_type":"nested"}
},
"sort_option": {},
"uuid": "9ea60027-c3a0-4cc3-9acc-6ecc462b1589",
"path": "00010001",
"children": []
}
]