OverriddenByRibbonApi element

Specifies whether a Group, Button control, Menu control, or menu item will be hidden on application and platform combinations that support the API (Office.ribbon.requestCreateControls) that installs custom contextual tabs on the ribbon.

Add-in type: Task pane

Valid only in these VersionOverrides schemas:

• Taskpane 1.0

For more information, see Version overrides in the manifest.

Associated with these requirement sets:

• Ribbon 1.2 (Required for Excel, PowerPoint, and Word.)

If this element is omitted, the default is false. If it's used, it must be the first child element of its parent element.

Note

For a full understanding of this element, please read Implement an alternate UI experience when custom contextual tabs are not supported.

The purpose of this element is to create a fallback experience in an add-in that implements custom contextual tabs when the add-in is running on an application or platform that doesn't support custom contextual tabs. The essential strategy is that you duplicate some or all of the groups and controls from your custom contextual tab onto a custom core tab (that is, noncontextual custom tab). Then, to ensure that these groups and controls appear when custom contextual tabs are not supported, but do not appear when custom contextual tabs are supported, you add <OverriddenByRibbonApi>true</OverriddenByRibbonApi> as the first child element of the <Group>, <Control>, or menu <Item> elements. The effect of doing so is the following:

• If the add-in runs on an application and platform that support custom contextual tabs, then the duplicated groups and controls won't appear on the ribbon. Instead, the custom contextual tab will be installed when the add-in calls the requestCreateControls method.
• If the add-in runs on an application or platform that doesn't support custom contextual tabs, then the duplicated groups and controls will appear on the ribbon.

Examples

Overriding a group

<ExtensionPoint xsi:type="PrimaryCommandSurface">
  <CustomTab id="Contoso.TabCustom">
    <Group id="Contoso.CustomTab.group1">
      <OverriddenByRibbonApi>true</OverriddenByRibbonApi>
      <Control  xsi:type="Button" id="Contoso.MyButton1">
        <!-- Child elements omitted. -->
      </Control>
    </Group>
    <Label resid="customTabLabel"/>
  </CustomTab>
</ExtensionPoint>

Overriding a control

<ExtensionPoint xsi:type="PrimaryCommandSurface">
  <CustomTab id="Contoso.TabCustom">
    <Group id="Contoso.CustomTab.group2">
      <Control  xsi:type="Button" id="Contoso.MyButton2">
        <OverriddenByRibbonApi>true</OverriddenByRibbonApi>
        <!-- Other child elements omitted. -->
      </Control>
    </Group>
    <Label resid="customTabLabel"/>
  </CustomTab>
</ExtensionPoint>

Overriding a menu item

<ExtensionPoint xsi:type="PrimaryCommandSurface">
  <CustomTab id="Contoso.TabCustom">
    <Group id="Contoso.CustomTab.group3">
      <Control  xsi:type="Menu" id="Contoso.MyMenu">
        <!-- Other child elements omitted. -->
        <Items>
          <Item id="showGallery">
            <OverriddenByRibbonApi>true</OverriddenByRibbonApi>
            <!-- Other child elements omitted. -->
          </Item>
        </Items>
      </Control>
    </Group>
    <Label resid="customTabLabel"/>
  </CustomTab>
</ExtensionPoint>