Navigation - Code Extractor

class Navigation

Maturity: 47

Represents navigation operations at the SharePoint site collection level, providing access to Quick Launch and Top Navigation Bar node collections.

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

Lines:
6 - 49

Complexity:
moderate

Purpose

This class manages navigation elements for SharePoint sites, allowing retrieval and configuration of navigation nodes in the Quick Launch sidebar and Top Navigation Bar. It provides property-based access to navigation collections and controls whether the site inherits navigation from its parent. The class extends Entity and integrates with SharePoint's REST API to manage site navigation structure.

Source Code

class Navigation(Entity):
    """Represents navigation operations at the site collection level."""

    @property
    def use_shared(self):
        """Gets a value that specifies whether the site inherits navigation."""
        return self.properties.get("UseShared", None)

    @use_shared.setter
    def use_shared(self, value):
        """Sets a value that specifies whether the site inherits navigation."""
        self.set_property("UseShared", value)

    @property
    def quick_launch(self):
        """Gets a value that collects navigation nodes corresponding to links in the Quick Launch area of the site."""
        return self.properties.get(
            "QuickLaunch",
            NavigationNodeCollection(
                self.context, ResourcePath("QuickLaunch", self.resource_path)
            ),
        )

    @property
    def top_navigation_bar(self):
        """Gets a value that collects navigation nodes corresponding to links in the top navigation bar of the site."""
        return self.properties.get(
            "TopNavigationBar",
            NavigationNodeCollection(
                self.context, ResourcePath("TopNavigationBar", self.resource_path)
            ),
        )

    def set_property(self, name, value, persist_changes=True):
        super(Navigation, self).set_property(name, value, persist_changes)

    def get_property(self, name, default_value=None):
        if default_value is None:
            property_mapping = {
                "TopNavigationBar": self.top_navigation_bar,
                "QuickLaunch": self.quick_launch,
            }
            default_value = property_mapping.get(name, None)
        return super(Navigation, self).get_property(name, default_value)

Parameters

Name	Type	Default	Kind
`bases`	Entity	-

Parameter Details

context: The client context object that provides connection and authentication to the SharePoint site. Required for making API calls to SharePoint services.

resource_path: The ResourcePath object that identifies the location of this navigation entity within the SharePoint site hierarchy. Used to construct paths to child navigation collections.

Return Value

Instantiation returns a Navigation object that represents the navigation configuration for a SharePoint site. The object provides access to navigation collections (QuickLaunch, TopNavigationBar) and navigation settings (UseShared). Properties return NavigationNodeCollection objects for managing navigation nodes, or boolean values for configuration settings.

Class Interface

Methods

`@property use_shared(self) -> bool` property

Purpose: Gets a value that specifies whether the site inherits navigation from its parent site

Returns: Boolean value indicating if navigation is inherited (True) or custom (False), or None if not set

`@use_shared.setter use_shared(self, value: bool) -> None` property

Purpose: Sets a value that specifies whether the site should inherit navigation from its parent site

Parameters:

value: Boolean value to set navigation inheritance - True to inherit, False for custom navigation

Returns: None - modifies the internal state of the Navigation object

`@property quick_launch(self) -> NavigationNodeCollection` property

Purpose: Gets the collection of navigation nodes corresponding to links in the Quick Launch area (left sidebar) of the site

Returns: NavigationNodeCollection object containing the Quick Launch navigation nodes

`@property top_navigation_bar(self) -> NavigationNodeCollection` property

Purpose: Gets the collection of navigation nodes corresponding to links in the top navigation bar of the site

Returns: NavigationNodeCollection object containing the top navigation bar nodes

`set_property(self, name: str, value: any, persist_changes: bool = True) -> None`

Purpose: Sets a property value on the Navigation object, optionally marking it for persistence to SharePoint

Parameters:

name: The name of the property to set (e.g., 'UseShared')
value: The value to assign to the property
persist_changes: Boolean indicating whether to mark this change for persistence (default True)

Returns: None - modifies the internal properties dictionary

`get_property(self, name: str, default_value: any = None) -> any`

Purpose: Retrieves a property value from the Navigation object with special handling for navigation collections

Parameters:

name: The name of the property to retrieve (e.g., 'TopNavigationBar', 'QuickLaunch', 'UseShared')
default_value: Optional default value to return if property is not found. If None, uses internal mapping for navigation collections

Returns: The property value if found, or the default value. For TopNavigationBar and QuickLaunch, returns NavigationNodeCollection objects

Attributes

Name	Type	Description	Scope
`context`	ClientContext	The SharePoint client context inherited from Entity base class, used for API communication	instance
`resource_path`	ResourcePath	The resource path identifying this navigation entity's location in the SharePoint hierarchy, inherited from Entity	instance
`properties`	dict	Dictionary storing the navigation properties and their values, inherited from Entity base class	instance

Dependencies

office365.runtime.paths.resource_path
office365.sharepoint.entity
office365.sharepoint.navigation.node_collection

Required Imports

from office365.runtime.paths.resource_path import ResourcePath
from office365.sharepoint.entity import Entity
from office365.sharepoint.navigation.node_collection import NavigationNodeCollection

Usage Example

from office365.sharepoint.client_context import ClientContext
from office365.sharepoint.navigation.navigation import Navigation

# Authenticate and get context
ctx = ClientContext(site_url).with_credentials(credentials)

# Get navigation from a web/site
web = ctx.web
nav = web.navigation
ctx.load(nav)
ctx.execute_query()

# Check if navigation is inherited
if nav.use_shared:
    print("Navigation is inherited from parent")

# Access Quick Launch nodes
quick_launch = nav.quick_launch
ctx.load(quick_launch)
ctx.execute_query()
for node in quick_launch:
    print(f"Quick Launch: {node.title}")

# Access Top Navigation Bar nodes
top_nav = nav.top_navigation_bar
ctx.load(top_nav)
ctx.execute_query()
for node in top_nav:
    print(f"Top Nav: {node.title}")

# Set navigation to not inherit
nav.use_shared = False
nav.update()
ctx.execute_query()

Best Practices

Always load the Navigation object using ctx.load() and ctx.execute_query() before accessing its properties to ensure data is retrieved from SharePoint
Use the use_shared property to check inheritance before modifying navigation to avoid unintended changes to parent site navigation
Access navigation collections (quick_launch, top_navigation_bar) through properties rather than directly manipulating the properties dictionary
Call update() and execute_query() after modifying navigation properties to persist changes to SharePoint
Handle navigation node collections as separate entities that may require their own load/execute cycles
Be aware that navigation changes may require appropriate SharePoint permissions (typically Manage Web permission level)
The class follows lazy loading pattern - navigation collections are only instantiated when accessed

Similar Components

AI-powered semantic similarity - components with related functionality:

class NavigationNodeCollection 79.7% similar

A collection class for managing SharePoint navigation nodes, providing methods to add, retrieve, and manipulate navigation nodes within a SharePoint site's navigation structure.
From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/sharepoint/navigation/node_collection.py
class NavigationService 76.3% similar

NavigationService is a REST-based service class for managing SharePoint navigation operations, including global navigation, menu states, and publishing navigation providers.
From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/sharepoint/navigation/navigation_service.py
class HomeSiteNavigationSettings 72.0% similar

A class representing SharePoint home site navigation settings, providing functionality to manage global navigation configuration for a SharePoint home site.
From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/sharepoint/navigation/home_site_navigation_settings.py
class SuiteNavData 69.0% similar

A SharePoint entity class representing Suite Navigation Data, which manages navigation information for the SharePoint suite bar.
From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/sharepoint/portal/suite_nav_data.py
class MenuState 68.5% similar

A class representing a SharePoint menu tree structure that can be displayed in the Quick Launch navigation area of a SharePoint site.
From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/sharepoint/navigation/menu_state.py

← Back to Browse

Assistant

Hi! I can help improve this code. Tell me what you'd like to enhance (e.g., "add error handling", "optimize performance", "improve readability", "add type hints").

Code Comparison

Original Code

                            class Navigation(Entity):
    """Represents navigation operations at the site collection level."""

    @property
    def use_shared(self):
        """Gets a value that specifies whether the site inherits navigation."""
        return self.properties.get("UseShared", None)

    @use_shared.setter
    def use_shared(self, value):
        """Sets a value that specifies whether the site inherits navigation."""
        self.set_property("UseShared", value)

    @property
    def quick_launch(self):
        """Gets a value that collects navigation nodes corresponding to links in the Quick Launch area of the site."""
        return self.properties.get(
            "QuickLaunch",
            NavigationNodeCollection(
                self.context, ResourcePath("QuickLaunch", self.resource_path)
            ),
        )

    @property
    def top_navigation_bar(self):
        """Gets a value that collects navigation nodes corresponding to links in the top navigation bar of the site."""
        return self.properties.get(
            "TopNavigationBar",
            NavigationNodeCollection(
                self.context, ResourcePath("TopNavigationBar", self.resource_path)
            ),
        )

    def set_property(self, name, value, persist_changes=True):
        super(Navigation, self).set_property(name, value, persist_changes)

    def get_property(self, name, default_value=None):
        if default_value is None:
            property_mapping = {
                "TopNavigationBar": self.top_navigation_bar,
                "QuickLaunch": self.quick_launch,
            }
            default_value = property_mapping.get(name, None)
        return super(Navigation, self).get_property(name, default_value)
                        

Improved Code

🔍 Code Extractor

class Navigation

Purpose

Source Code

Parameters

Parameter Details

Return Value

Class Interface

Methods

`@property use_shared(self) -> bool` property

`@use_shared.setter use_shared(self, value: bool) -> None` property

`@property quick_launch(self) -> NavigationNodeCollection` property

`@property top_navigation_bar(self) -> NavigationNodeCollection` property

`set_property(self, name: str, value: any, persist_changes: bool = True) -> None`

`get_property(self, name: str, default_value: any = None) -> any`

Attributes

Dependencies

Required Imports

Usage Example

Best Practices

Tags

Similar Components

class NavigationNodeCollection 79.7% similar

class NavigationService 76.3% similar

class HomeSiteNavigationSettings 72.0% similar

class SuiteNavData 69.0% similar

class MenuState 68.5% similar

class Navigation

Purpose

Source Code

Parameters

Parameter Details

Return Value

Class Interface

Methods

@property use_shared(self) -> bool property

@use_shared.setter use_shared(self, value: bool) -> None property

@property quick_launch(self) -> NavigationNodeCollection property

@property top_navigation_bar(self) -> NavigationNodeCollection property

set_property(self, name: str, value: any, persist_changes: bool = True) -> None

get_property(self, name: str, default_value: any = None) -> any

Attributes

Dependencies

Required Imports

Usage Example

Best Practices

Tags

Similar Components

class NavigationNodeCollection 79.7% similar

class NavigationService 76.3% similar

class HomeSiteNavigationSettings 72.0% similar

class SuiteNavData 69.0% similar

class MenuState 68.5% similar

✨ Improve Code: Navigation

Code Comparison

`@property use_shared(self) -> bool` property

`@use_shared.setter use_shared(self, value: bool) -> None` property

`@property quick_launch(self) -> NavigationNodeCollection` property

`@property top_navigation_bar(self) -> NavigationNodeCollection` property

`set_property(self, name: str, value: any, persist_changes: bool = True) -> None`

`get_property(self, name: str, default_value: any = None) -> any`