🔍 Code Extractor

A collection class for managing sort criteria in SharePoint search queries, allowing addition and removal of sort specifications for search results.

Purpose

SortCollection is a specialized Entity class that manages sorting specifications for SharePoint search results. It provides methods to add sort criteria based on managed properties and directions (ascending, descending, or FQL formula), and to clear all sort specifications. The class integrates with SharePoint's Client Object Model to execute sort operations through service queries.

Source Code

class SortCollection(Entity):
    """Contains information about how to sort the search results."""

    def add(self, property_name, direction):
        """
        Adds a new element of type Microsoft.SharePoint.Client.Search.Query.Sort to the collection and returns
        a reference to the added Microsoft.SharePoint.Client.Search.Query.Sort.

        :param str property_name: f direction is equal to SortDirection.Ascending or SortDirection.Descending, then
            this element specifies the name of the managed property to sort the search results on
        :param int direction: The direction in which to sort on the property specified in the strProperty element.
            MUST be a SortDirection data type as specified in section 3.1.4.7.4.4. If the direction element is
            not specified, the protocol server MUST use SortDirection.Ascending as the default. If direction is equal
            to SortDirection.FQLFormula, then the strProperty MUST specify the formula that MUST be used for sorting
            the search results, as specified in section 3.1.4.7.4.4. If QueryProperties.ResultsProvider
            (as specified in section 2.2.4.11) is SearchServer.SharepointSearch and direction is set to
            SortDirection.FQLFormula, the value of strProperty MUST be ignored by the protocol server.
        """
        payload = {"strProperty": property_name, "direction": direction}
        qry = ServiceOperationQuery(self, "Add", None, payload)
        self.context.add_query(qry)
        return self

    def clear(self):
        """Deletes all the elements in the collection."""
        qry = ServiceOperationQuery(self, "Clear")
        self.context.add_query(qry)
        return self

    @property
    def items(self):
        return self.properties.get("Items", ClientValueCollection(Sort))

    @property
    def entity_type_name(self):
        return "Microsoft.SharePoint.Client.Search.Query.SortCollection"

Parameters

Parameter Details

bases: Inherits from Entity class, which provides base functionality for SharePoint client objects including context management and property handling

Return Value

Instantiation returns a SortCollection object that can manage sort criteria. The add() and clear() methods return self for method chaining. The items property returns a ClientValueCollection of Sort objects representing the current sort specifications.

Class Interface

Methods

Attributes

Dependencies

• office365.runtime.client_value_collection
• office365.runtime.queries.service_operation
• office365.sharepoint.entity
• office365.sharepoint.search.query.sort.sort

Required Imports

from office365.runtime.client_value_collection import ClientValueCollection
from office365.runtime.queries.service_operation import ServiceOperationQuery
from office365.sharepoint.entity import Entity
from office365.sharepoint.search.query.sort.sort import Sort

Usage Example

from office365.sharepoint.client_context import ClientContext
from office365.sharepoint.search.query.sort.sort_collection import SortCollection
from office365.sharepoint.search.query.sort.sort_direction import SortDirection

# Assuming context is already created and authenticated
ctx = ClientContext(site_url)
sort_collection = SortCollection(ctx)

# Add sort by title ascending
sort_collection.add('Title', SortDirection.Ascending)

# Add sort by modified date descending
sort_collection.add('LastModifiedTime', SortDirection.Descending)

# Execute the query
ctx.execute_query()

# Access the sort items
for sort_item in sort_collection.items:
    print(f"Property: {sort_item.property}, Direction: {sort_item.direction}")

# Clear all sorts
sort_collection.clear()
ctx.execute_query()

Best Practices

• Always call context.execute_query() after adding or clearing sort specifications to commit changes to SharePoint
• Use method chaining for adding multiple sort criteria: sort_collection.add('Title', 0).add('Modified', 1)
• Ensure the managed property names used in add() exist in the SharePoint search schema
• When using SortDirection.FQLFormula, provide a valid FQL formula in the property_name parameter
• Be aware that FQL formula sorting may be ignored if ResultsProvider is set to SearchServer.SharepointSearch
• Clear the collection before rebuilding sort criteria to avoid accumulating unwanted sorts
• Access the items property only after executing queries to ensure the collection is populated

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• class Sort 78.5% similar

  A class representing sort criteria for SharePoint search results, specifying which property to sort on and the sort direction.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/sharepoint/search/query/sort/sort.py

• class ReorderingRuleCollection 70.5% similar

  A SharePoint entity class that represents a collection of reordering rules for search results, inheriting from the Entity base class.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/sharepoint/search/reordering_rule_collection.py

• class EntityCollection 62.5% similar

  EntityCollection is a generic collection class for managing SharePoint entity sets, extending ClientObjectCollection with SharePoint-specific functionality.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/sharepoint/entity_collection.py

• class FormCollection 62.1% similar

  A collection class that manages and provides access to SharePoint list forms, inheriting from EntityCollection[Form].

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/sharepoint/forms/collection.py

• class ListItemCollection 62.0% similar

  A collection class for managing SharePoint list items, providing methods to retrieve items by various identifiers and URLs.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/sharepoint/listitems/collection.py