How to inject your own custom buttons

[edwardlee-msft]

We are pleased to present to you, Custom Button injection!

A very desirable feature that would allow contoso to add their own functional buttons into our composites. Rather than having to build out their communication experience using components, we want to make sure the ease of entry in injecting customer's own features is simple and achievable.

The goal is to allow customers to inject custom buttons into the control bar. The buttons would be populated into pre-designated area groups. As of now, custom buttons can be injected in 3 possible areas; the primary, the secondary, and the overflow.

There would also be a limit set on how many buttons are presented on the screen depending on the view (desktop/mobile). This would also imply a responsive design where any buttons that do not appear on the primary or the secondary control bar would be moved into the overflow menu.

At this moment, a custom button functionality is up to the Customer's imagination. Opening up a new tab, opening a pop up, a new window, creating alerts, etc.. We do not limit the customers ability, but we are exploring ideas where these buttons can trigger composite specific events, like possibly opening a custom side pane window in the composite with Customer provided view. Stay tuned for exciting future additions!

What the code could look like

1. import CustomCallControlButtonCallback, CustomCallControlButtonProps, CustomCallControlButtonCallbackArgs
2. Create an onFetchCustomButtonProps prop object. Will look similar to { onFetchCustomButtonProps: <Array_of_CustomControlButtonCallback> }
   Replace <Array_of_CustomControlButtonCallback> with CustomCallControlButtonCallback[]
3. Create an array of custom buttons using CustomCallControlButtonProps
4. Place props under Composite options->CallControls->onFetchCustomButtonProps

Example of a list of Custom Buttons:

const onFetchCustomButtonPropsExample: CustomCallControlButtonCallback[] = [
  (args: CustomCallControlButtonCallbackArgs): CustomCallControlButtonProps => {
    return {
      placement: 'primary',
      // Icon registered by the composites.
      iconName: 'Link',
      strings: {
        label: 'Feedback',
        tooltipContent: 'Feedback'
      },
      onItemClick: () => {
        window.open('https://feedback.azure.com/d365community/forum/81ff6d2b-0c25-ec11-b6e6-000d3a4f0858', '_blank')?.focus();
      }
    };
  },
  (args: CustomCallControlButtonCallbackArgs): CustomCallWithChatControlButtonProps => {
    return {
      placement: 'secondary',
      // Icon registered by the composites.
      iconName: 'Link',
      strings: {
        label: 'Storybook',
        tooltipContent: 'Storybook'
      },
      onItemClick: () => {
        window.open('https://azure.github.io/communication-ui-library', '_blank')?.focus();
      }
    };
  },
  (args: CustomCallControlButtonCallbackArgs): CustomCallWithChatControlButtonProps => {
    return {
      placement: 'overflow',
      // Icon registered by the composites.
      iconName: 'Link',
      strings: {
        label: 'Info',
        tooltipContent: 'Information'
      },
      onItemClick: () => {
        window.open('https://docs.microsoft.com/en-us/azure/communication-services/concepts/ui-library/ui-library-overview', '_blank')?.focus()
      }
    };
  }
]; 

export const CustomButtonInjectionExample = (): JSX.Element => {
  // Complete adapter options here
  const adapter = ...;

  return (
    <CallComposite
      adapter={adapter}
      options={{
        callControls: {
          onFetchCustomButtonProps: onFetchCustomButtonPropsExample
        }
      }}
    />
  );
};

Want to give it a try in our Call Composites? It's as easy as following the steps below

1. Follow the Setting Up guide to create a react app with our ui-library-quickstart-composites.
2. Apply this gist over the src/App.tsx file
3. Replace Authentication information in App.tsx
4. run npm start

Here's what your custom buttons could look like!

FAQ

Q. How many buttons can be injected?
A. In desktop: primary = 3 custom buttons, secondary = 2 custom buttons
In Mobile: primary = 1 custom button, secondary = 0 custom buttons, overflow = ∞
Q. What Icons can be used?
A. Non-default icons that are already registered by the composites. Can be found in the storybook icons page. Replace the icons with your own images. You can also register your own icons to use in the Composites.
Q. Where do custom buttons go once injected into areas?
A. For Primary, they are injected at the right-end (left-end if rtl) of the area group but before the EndCallButton.
For Secondary, they are injected at the left-end (right-end if rtl) of the area group.
For Overflow, they are injected at the end of the overflow menu
Q. What about feature x, feature y, and feature z?
A. We are still hard at work on improving this specific feature. Lots of new and exciting additions will be made and are already being discussed/planned. Look out for the next big update 💯 !

Would you like to provide feedback? Please leave them below as a comment or through the feedback page and we will get back to you as soon as we can.

[nasu38yen]

Thank you for providing this feature. It was helpful.
By the way, I need to change the color of the inserted button's icon depending on its state.
How can I specify the color of the icon?

[edwardlee-msft]

Hi nasu38yen,

To change the color of an icon, you would need to register new icons into our composite with your desired color and then using a state manager, change to the icon with the color.

Something similar to our example here:
https://azure.github.io/communication-ui-library/?path=/docs/icons--page#custom-icons-1

[lovedota]

Hi @edwardlee-msft
Can a button have a Contextual Menu like this design ?

[alkwa-msft]

@lovedota I believe this APi is only in our composites which have limited styling capabilities such as changing the background color. This API is designed to allow people to functionality put in their own call control buttons, icons, labels. For a further in-depth customization we may recommend to use UI components to gain a much finer grain control on how the UI is being rendered.

Something else to potentially consider is if your less concerned about the background color of the advisor tools button here you could just create an advisors tool button and the callback could do anything even potentially creating an absolute positioned UI element.

[alkwa-msft]

This can also be helpful for others debugging to grab the call Id right from the UI

1. Create the reference to the adapter before creating the actual adapter so we can reference it in our callbacks.

let callAdapter;

2. Create the callbacks and use the callAdapter reference if you want to grab the callId once the call is connected.
   In this example I am adding in some buttons that can help debug a call

const customButtonDebuggingSupport = [
  function(args) {
    return {
      placement: 'overflow',
      // Icon registered by the composites.
      iconName: 'InfoSolid',
      strings: {
        label: 'Get Call ID',
        tooltipContent: 'Fetch the current Call ID'
      },
      onItemClick: function() {
        const callId = args.callId; // Assuming args contains callId
        alert('Current Call ID: ' + callAdapter?.call?.id);
      }
    };
  },
];

3. Create the adapter as usual.

callAdapter = await callComposite.loadCallComposite(
  {
    ...// info to start/join your call
  },
  target, // which DOM element should be the container
  { options: { 
      callControls: {
        onFetchCustomButtonProps: customButtonDebuggingSupport // we want to add our custom buttons to our call control bar
      }
    }
  }
);

In this example I have chosen to put the icons in the overflow.

and when clicking on the button I will get my call id