🔍 Code Extractor

A class representing a SharePoint menu tree structure that can be displayed in the Quick Launch navigation area of a SharePoint site.

Purpose

MenuState encapsulates the configuration and structure of a SharePoint navigation menu tree. It manages menu nodes, audience targeting, URL prefixes, and site-relative paths. This class is used to define and configure navigation menus that appear in SharePoint's Quick Launch area, supporting hierarchical menu structures with audience targeting capabilities and various URL resolution strategies including site-relative and site-collection-relative URLs.

Source Code

class MenuState(ClientValue):
    """A menu tree which can be shown in the Quick Launch of a site."""

    def __init__(
        self,
        audience_ids=None,
        friendly_url_prefix=None,
        nodes=None,
        simple_url=None,
        site_prefix=None,
    ):
        """
        :param list[uuid] audience_ids:
        :param str friendly_url_prefix: Specifies the site collection relative URL for the root node of the menu tree.
        :param list[MenuNode] nodes: The child nodes of the root node of the menu tree.
        :param str simple_url: f the NodeType property (section 3.2.5.244.1.1.7) of the menu tree root node is set
            to "SimpleLink", this property represents the URL of the root node. The URL can be relative or absolute.
            If the value is a relative URL, it can begin with URL tokens "~site" and "~sitecollection".
            These tokens indicate that the URL is either relative to the site (2) or to the site collection
            respectively. If the NodeType property (section 3.2.5.244.1.1.7) of the menu tree root node is not set
            to "SimpleLink", this value MUST be NULL.
        :param str site_prefix: Defines the text that SHOULD be substituted for "~sitecollection/" in relative links
            (such as "~sitecollection/Pages/MyPage.aspx ").
        """
        self.AudienceIds = GuidCollection(audience_ids)
        self.FriendlyUrlPrefix = friendly_url_prefix
        self.Nodes = ClientValueCollection(MenuNode, nodes)
        self.SimpleUrl = simple_url
        self.SPSitePrefix = site_prefix

Parameters

Parameter Details

audience_ids: Optional list of UUIDs representing the audiences that should see this menu. Used for audience targeting to show/hide menus based on user group membership. Can be None if no audience targeting is needed.

friendly_url_prefix: Optional string specifying the site collection relative URL for the root node of the menu tree. This prefix is prepended to menu URLs to create complete paths. Can be None if not using friendly URLs.

nodes: Optional list of MenuNode objects representing the child nodes of the root node in the menu tree. These define the hierarchical structure of the menu. Can be None for an empty menu or will be converted to ClientValueCollection.

simple_url: Optional string representing the URL of the root node when NodeType is set to 'SimpleLink'. Can be relative or absolute. Relative URLs can use tokens '~site' (site-relative) or '~sitecollection' (site collection-relative). Must be NULL if NodeType is not 'SimpleLink'.

site_prefix: Optional string defining the text that should replace '~sitecollection/' in relative links. Used for URL token substitution when resolving site collection-relative URLs like '~sitecollection/Pages/MyPage.aspx'.

Return Value

Instantiation returns a MenuState object with initialized attributes: AudienceIds (GuidCollection), FriendlyUrlPrefix (str or None), Nodes (ClientValueCollection of MenuNode objects), SimpleUrl (str or None), and SPSitePrefix (str or None). The object represents a complete menu configuration ready to be used with SharePoint navigation APIs.

Class Interface

Methods

Attributes

Dependencies

• office365

Required Imports

from office365.runtime.client_value import ClientValue
from office365.runtime.client_value_collection import ClientValueCollection
from office365.runtime.types.collections import GuidCollection
from office365.sharepoint.navigation.menu_node import MenuNode

Usage Example

from office365.sharepoint.navigation.menu_state import MenuState
from office365.sharepoint.navigation.menu_node import MenuNode
import uuid

# Create menu nodes
node1 = MenuNode(title='Home', url='/sites/mysite/Pages/Home.aspx')
node2 = MenuNode(title='Documents', url='/sites/mysite/Documents')

# Create a menu state with audience targeting
audience_id = uuid.uuid4()
menu_state = MenuState(
    audience_ids=[audience_id],
    friendly_url_prefix='/sites/mysite',
    nodes=[node1, node2],
    simple_url=None,
    site_prefix='/sites/mysite'
)

# Access menu properties
print(f'Number of nodes: {len(menu_state.Nodes)}')
print(f'Site prefix: {menu_state.SPSitePrefix}')
print(f'Audience IDs: {menu_state.AudienceIds}')

# Create a simple link menu
simple_menu = MenuState(
    simple_url='~sitecollection/Pages/Welcome.aspx',
    site_prefix='/sites/mysite'
)

Best Practices

• Always provide site_prefix when using relative URLs with tokens like '~sitecollection/' to ensure proper URL resolution
• Use simple_url only when the menu root node type is 'SimpleLink', otherwise set it to None
• When using audience targeting, ensure audience_ids contains valid UUIDs that correspond to existing SharePoint audiences
• Initialize nodes as a list of MenuNode objects; they will be automatically converted to ClientValueCollection
• Use '~site' token for site-relative URLs and '~sitecollection' for site collection-relative URLs in simple_url
• This class inherits from ClientValue, making it serializable for SharePoint REST API operations
• The class is immutable after initialization in typical usage; create new instances for different menu configurations
• Ensure MenuNode objects are properly constructed before passing them to the nodes parameter
• When working with SharePoint navigation, this object is typically used in conjunction with SharePoint context and navigation service classes

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• class Navigation 68.5% similar

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

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

• class MenuNode 66.1% similar

  Represents a navigation node in a hierarchical navigation tree structure, typically used in SharePoint or similar content management systems.

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

• class NavigationService 64.8% 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 58.1% 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 NavigationNodeCollection 57.1% 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