What is the purpose of widgetUtils.findObject function in the Aikau framework?

The widgetUtils.findObject function is a core utility within the Aikau framework, specifically used for customizing existing pages in Alfresco Share. When an extension module is processed, this function is used to traverse the JSON model of an out-of-the-box page to locate a specific target widget, typically by its id. Once the widget is found, the extension can then modify it, for example, by adding new child widgets (like a new menu item) or altering its configuration. This is the standard, non-intrusive method for extending default Aikau pages.

A. When creating entirely new pages, you define the complete widget structure, so there is no pre-existing model to search through with this function.

B. This function is designed to find a single, specific widget object that matches a criterion, not to retrieve a comprehensive list of all widgets.

D. The function operates within the JSON model of a single page to find widgets, not to discover or list the Aikau pages within the application.

1. Official Alfresco Documentation (5.2): The "Add new menu item to Share header" tutorial explicitly demonstrates this use case. The controller logic uses widgetUtils.findObject(model.jsonModel, "id", "HEADERAPPMENUBAR") to locate the main menu bar widget in the existing page model before adding a new item to it.

Source: Alfresco Content Services 5.2 Documentation, "Share Header" section within Share Extension Points. (While the direct link may change, this is a canonical example found in the 5.x era developer guides for Share customization).

2. Official Alfresco Aikau Tutorial: In tutorials covering Aikau development and customization, the primary example for page modification involves finding a component to extend. The widgetUtils.findObject is presented as the key helper function for this task.

Source: Alfresco Aikau Tutorial, Section on "Customizing Existing Pages". The example shows finding the alfresco/documentlibrary/AlfDocumentList to add custom actions. (Reference from historical Alfresco University courseware and developer series on Aikau).