Realçar o conteúdo e aprimorar a funcionalidade dos suplementos do SharePoint hospedados pelo SharePoint com o controle de texto explicativo

O controle de chamada do SharePoint fornece uma maneira flexível de envolver o usuário e mostrar a funcionalidade do suplemento hospedado no SharePoint. Você pode configurá-lo de várias maneiras para se adequar à interface do usuário do suplemento. Você pode construir esse controle, adicioná-lo à sua página e personalizar sua aparência e comportamento.

Ao fazer pesquisas em um site do SharePoint, você verá exemplos do controle de chamada em ação porque ele aparece sempre que você passa o mouse sobre um resultado de pesquisa.

A figura a seguir mostra a chamada para um único resultado de pesquisa e mostra algumas das coisas típicas em um controle de conteúdo: um título, algumas informações sobre o item na página e ações (Abrir e Enviar) que você pode assumir no item.

Nesse caso, as informações e as ações são relativamente simples, mas você já pode ver duas vantagens em usá-la. Primeiro, ele permite que você mostre informações adicionais sobre elementos em uma página quando necessário e, em segundo lugar, ele oferece uma maneira elegante de adicionar funcionalidade à página.

Exemplo do controle de texto explicativo em uma página de resultados de pesquisa do SharePoint

Disponibilizar o controle em sua página HTML, incluindo o arquivo callout.js

Este exemplo usa o SP.SOD.executeFunc método para garantir que o arquivo de script seja carregado antes de executar qualquer código que dependa dele.

SP.SOD.executeFunc("callout.js", "Callout", function () {
    });

A função que você passa para a SP.SOD.executeFunc função contém o código que você deseja executar após o carregamento do arquivo callout.js. Depois de carregar esses arquivos, você usará o CalloutManager objeto para criar um Callout objeto para cada elemento de página que precisa ter um controle de chamada associado a ele.

O CalloutManager é um singleton que armazena referências a cada Callout objeto em uma página dentro de uma matriz associativa.

O Callout objeto tem apenas dois membros necessários: ID e launchPoint. O ID membro é a chave mapeada para o Callout objeto no CalloutManager: CalloutManager["value of the callout's ID member"]. O launchPoint membro é um elemento de página HTML.

Você pode, por exemplo, criar ou obter um div elemento em sua página e passá-lo como um membro do Callout objeto. Por padrão, o controle de chamada é exibido sempre que um usuário seleciona o launchPoint elemento.

Este exemplo mostra como criar o controle de chamada mais simples possível com apenas os dois membros necessários e uma cadeia de caracteres de título.

var calloutPageElement = document.createElement("div");
var callout = CalloutManager.createNew({
   ID: "unique identifier",
   launchPoint: calloutPageElement,
   title: "callout title"
});

Essa chamada específica é exibida e exibe um título na parte superior do controle sempre que um usuário seleciona o elemento de página. Você usa os membros opcionais para personalizar a aparência, o comportamento, o posicionamento e as ações do controle de algumas maneiras muito poderosas. O controle de chamada também tem um método definido que você pode usar para definir um valor para qualquer parâmetro depois de criar uma instância do controle.

callout.set({openOptions:{event: "hover"}});

Você também pode definir valores para todos os membros de chamada em um CalloutOptions objeto e, em seguida, passar esse objeto para o createNew método.

var calloutPageElement = document.createElement("div");
var calloutOptions = new CalloutOptions();
calloutOptions.ID = unique identifier;
calloutOptions.launchPoint = calloutPageElement;
calloutOptions.title = callout title;
var callout = CalloutManager.createNew(calloutOptions);

Personalizar a aparência do controle de chamada

Você pode usar esses membros para controlar a exibição do texto explicativo.

Membro	Objetivo	Valores válidos (padrão em negrito)
título	Exibir um título na parte superior do controle.	cadeia de caracteres, nula, cadeia de caracteres que contém HTML
conteúdo	Exiba HTML dentro do controle sempre que não houver valor para o contentElement membro.	cadeia de caracteres que contém HTML, nulo, deve ser nula se contentElement tiver um valor
contentElement	Exiba um elemento HTML dentro do controle quando não houver valor para o content membro.	Qualquer elemento HTML, nulo, deve ser nulo se content tiver um valor
contentWidth	Especifique a largura em pixels do contêiner do corpo da chamada. Esse contêiner também tem uma borda de 1 pixel e um preenchimento de 15 pixels em cada lado, portanto, o controle é 32 pixels maior que a largura do corpo especificada. A propriedade CSS overflow do controle é definida como , para hiddenque o conteúdo seja cortado se ele não se encaixar na largura especificada. Se você definir esse membro em uma chamada aberta, a alteração entrará em vigor imediatamente. Isso não é verdade para os outros membros.	Qualquer número entre 240 e 610, 350 (tornando o controle de 382 pixels de largura por padrão)
beakOrientation	Especifique a orientação do bico ou do ponteiro do controle de texto explicativo.	orientação topBottom orientação leftRight

Personalizar o comportamento do controle de chamada

Você pode usar os membros a seguir para controlar o comportamento da chamada. Comece com o membro importante openOptions porque ele permite especificar como o controle é aberto e fechado quando o usuário interage com ele na página.

Estes são os outros membros que você pode definir para controlar o comportamento do texto explicativo.

Usar os métodos de controle de chamada

Você pode usar esses métodos para personalizar o comportamento do controle de texto explicativo.

Adicionar ações ao controle de chamada

Você adiciona ações depois de criar uma instância do controle de chamada. Uma ação de chamada pode consistir em uma única ação ou um menu de ações. Você pode adicionar três ações a um controle de chamada. Depois de criar uma ação de chamada, adicione-a ao objeto com seu CalloutControladdAction método. Essa ação de exemplo abre uma nova janela no navegador depois que o usuário seleciona o texto.

//Create CalloutAction
var calloutAction = new CalloutAction({
            text: "Open window"
            onClickCallback: function() {                
                window.open(url);
            }
        });

//Add Action to an instance of the CalloutControl        
        myCalloutControl.addAction(calloutAction);

Você também pode definir valores para todos os CalloutAction membros em um CalloutActionOptions objeto e passar esse objeto para o CalloutAction construtor.

//Create CalloutAction
var calloutActionOptions = new CalloutActionOptions();
calloutActionOptions.text = "Open window";
actionOptions.onClickCallback = function() {
    window.open(url);
};
var calloutAction = new CalloutAction(calloutActionOptions);

//Add Action to an instance of the CalloutControl        
        myCalloutControl.addAction(calloutAction);

Você pode usar esses membros para definir o comportamento de uma ação de texto explicativo.

A próxima seção explica como criar um CalloutActionMenuEntry e adicioná-lo a um CalloutAction objeto.

Adicionar menus de ação ao controle de chamada

Quando uma ação de chamada contém um menu em vez de uma única ação, o usuário vê uma seta para baixo ao lado do texto de ação de chamada, como na figura a seguir.

Uma ação de chamada exibe um menu quando um usuário seleciona a seta ao lado do rótulo de ação

Você pode criar quantas entradas de menu desejar e adicioná-las à ação de chamada passando-as em uma matriz como o valor do menuEntries membro do CalloutAction objeto.

//Create two menu entries.
var menuEntry1 = new CalloutActionMenuEntry("Entry One", calloutActionCallbackFunction, "/_layouts/images/DOC16.GIF");
var menuEntry2 = new CalloutActionMenuEntry("Some Other Entry", calloutActionCallbackFunction, "/_layouts/images/XLS16.GIF");

//Add the menu entries to the callout action.
var calloutAction = new CalloutAction({
   text: "MENU W/ ICONS",
   menuEntries: [menuEntry1, menuEntry2]
})

//Add the callout action to the callout control.
callout.addAction(calloutAction);

O CalloutActionMenuEntry construtor usa três parâmetros. Os dois primeiros parâmetros são necessários. O terceiro é opcional, mas pode ser útil porque permite exibir um ícone com o texto.

• Passe uma cadeia de caracteres como o primeiro parâmetro para exibir um rótulo de texto para cada entrada de menu.

• Passe uma função como o segundo parâmetro para definir a ação que ocorre quando o usuário clica no texto de entrada de menu.

• Passe uma cadeia de caracteres que contém a URL do ícone que você deseja exibir à esquerda do rótulo de texto.

Use o CalloutManager para criar e gerenciar instâncias do controle de chamada

O CalloutManager objeto singleton armazena referências a cada Callout objeto em uma página. Ele armazena cada instância do controle de chamada em uma matriz associativa em que o ID valor de cada controle é a chave. O CalloutManager contém métodos que ajudam você a criar e gerenciar os Callout objetos que ele armazena.

Posicione o controle de chamada na página

A seção a seguir descreve como usar o calloutPositioningProxy objeto para gravar algoritmos de posicionamento para o controle de chamada.

Escrever algoritmos de posicionamento com calloutPositioningProxy

O calloutPositioningProxy objeto contém métodos e propriedades que você pode usar para substituir a lógica de posicionamento que o controle de chamada usa por padrão. Por exemplo, se você quiser que o controle apareça abaixo e à direita do elemento o launchPoint tempo todo, você escreverá um algoritmo de posicionamento que se pareça com o seguinte.

function alwaysGoDownAndRight(calloutPositioningProxy)  {
    calloutPositioningProxy.moveDownAndRight();
} 

Em seguida, você passaria essa função como o valor do Callout membro do positionAlgorithm objeto. Você pode fazer isso ao criar o Callout, ou posterior, definindo o valor.

callout.set({positionAlgorithm: alwaysGoDownAndRight});

Você sempre pode conferir a lógica de posicionamento padrão iniciando o console de JavaScript do navegador (as Ferramentas do Desenvolvedor do Internet Explorer F12, por exemplo).

CalloutOptions.prototype.positionAlgorithm.toString()

Você pode usar esses métodos no CalloutPositioningProxy objeto para escrever sua própria lógica de posicionamento.

Esse algoritmo de posicionamento faz com que o controle vá acima ou abaixo do texto. A isRTL propriedade do CalloutPositioningProxy informa se o texto está exibindo uma linguagem da direita para a esquerda. Verifique se essa propriedade é verificada para garantir que o controle esteja sempre posicionado corretamente em relação ao texto na página.

function examplePositionAlgorithm(calloutPositioningProxy) {
    if (!calloutPositioningProxy.isRTL) {
        calloutPositioningProxy.moveDownAndRight();
        if (calloutPositioningProxy.isCalloutTooFarBottom()) {
            calloutPositioningProxy.moveUpAndRight();
        }
    }
    else {
        calloutPositioningProxy.moveDownAndLeft();
        if (calloutPositioningProxy.isCalloutTooFarBottom()) {
            calloutPositioningProxy.moveUpAndLeft();
        }
    }
}
callout.set({positionAlgorithm: examplePositionAlgorithm});

Esse algoritmo de posicionamento altera a direção padrão do controle para downAndRight em vez de upAndRight, mas ele usa o algoritmo padrão se houver colisões.

function tryDownAndRightThenGoDefault(calloutPositioningProxy) {
    if (!calloutPositioningProxy.isRTL)
        calloutPositioningProxy.moveDownAndRight();
    else
        calloutPositioningProxy.moveDownAndLeft();
    
    if (calloutPositioningProxy.numberOfEdgesCollidingWithBoundingBox() > 0)
        return CalloutOptions.prototype.positionAlgorithm.apply(this, arguments);
};
callout.set({positionAlgorithm: tryDownAndRightThenGoDefault});

Confira também

• Criar componentes de experiência de usuário no SharePoint
• Exemplo de código: usar exibições de lista, chamadas e caixas de diálogo em suplementos hospedados pelo SharePoint
• Introdução à criação de Suplementos do SharePoint hospedados no SharePoint