Posted in SharePoint, Web Parts

Customização da Content Query Web Part

Uma das web parts mais flexíveis fornecidas pelo SharePoint 2007 é a Content Query Web Part. Alguns exemplos de aplicações para esta web part:

  • Mostrar conteúdos de uma lista com uma apresentação diferente da oferecida pela List Web Part
  • Mostrar conteúdos provenientes de um ou mais subsites ou listas, definindo ordenação, filtragem e agrupamentos específicos
  • Ter mais de uma forma de apresentar os mesmos conteúdos

Tudo isto sem ter que fazer uma linha de código e configurando separadamente acesso a dados e apresentação.

No que respeita ao acesso a dados, a configuração é bastante linear bastando indicar o site ou lista de onde se pretende obter o conteúdo e indicar qual o seu content type. O resto é praticamente o mesmo que definir uma vista numa lista comum, configurando filtros, ordenação e agrupamento, bem como número limite de itens.

A configuração da apresentação assenta na selecção de dois estilos:

  • O Group Style, que é utilizado no cabeçalho dos agrupamentos de itens (se for definido um agrupamento)
  • O Item Style, que é utilizado para representar cada item

Como é provável que nenhuma das opções para estes estilos seja exactamente o que procuramos para mostrar a informação na web part, o SharePoint permite que se altere a forma como a web part o faz através da configuração de três ficheiros XSL-T: ContentQueryMain.xsl, Header.xsl e ItemStyle.xsl. Qualquer um destes ficheiros pode ser encontrado acedendo à pasta /Style Library/XSL Style Sheets, usando o SharePoint Designer ou Site Actions > Manage Content and Structure ou ainda, Site Actions > Site Settings > Content and Structure.

O ficheiro ContentQueryMain.xsl contém o XSL principal que executado para formatar a web part, e em grande parte dos casos não precisará de ser alterado.

Group Style

O ficheiro Header.xsl contém um conjunto de templates XSL que correspondem às opções disponíveis na caixa de selecção Group Style. Para criar um novo Group Style basta criar um novo template neste ficheiro. O template seleccionado será chamado no início de cada agrupamento de dados (group by).

Exemplo de um template de Group Style:

<xsl:template name="MyGroupStyle" match="*[@GroupStyle=’MyGroupStyle’]" mode="header">
  <div class="MyStyle">
    <xsl:call-template name="OuterTemplate.GetGroupName">
      <xsl:with-param name="GroupName" select="@*[name()=$Group]"/>
      <xsl:with-param name="GroupType" select="$GroupType"/>
    </xsl:call-template>
  </div>
</xsl:template>

Este template limita-se a representar o nome do grupo (corresponde ao valor do campo pelo qual é feito o agrupamento) usando um estilo MyStyle definido na CSS do site.

Item Style

O ficheiro ItemStyle.xsl contém um conjunto de templates XSL que correspondem às opções disponíveis na caixa de selecção Item Style. Para criar um novo Item Style basta criar um novo template neste ficheiro. O template seleccionado será chamado para cada item de lista apresentado na web part.

Exemplo de um template de Item Style:

<xsl:template name="MyItemStyle" match="Row[@Style=’MyItemStyle’]" mode="itemstyle">
  <xsl:variable name="SafeLinkUrl">
    <xsl:call-template name="OuterTemplate.GetSafeLink">
      <xsl:with-param name="UrlColumnName" select="'LinkUrl'"/>
    </xsl:call-template>
  </xsl:variable>
  <xsl:variable name="DisplayTitle">
    <xsl:call-template name="OuterTemplate.GetTitle">
      <xsl:with-param name="Title" select="@Title"/>
      <xsl:with-param name="UrlColumnName" select="'LinkUrl'"/>
    </xsl:call-template>
  </xsl:variable>
  <xsl:variable name="LinkTarget">
    <xsl:if test="@OpenInNewWindow = 'True'" >_blank</xsl:if>
  </xsl:variable>
  <div id="itemlink" class="ItemLinkStyle">
    <a href="{$SafeLinkUrl}" target="{$LinkTarget}" title="{@LinkToolTip}">
      <xsl:value-of select="$DisplayTitle"/>
    </a>
  </div>
  <div id="itemdescription" class="DescriptionStyle">
    <xsl:value-of disable-output-escaping="yes" select="@MyCustomField"/>
  </div>
</xsl:template>

Analisando este template podemos retirar as seguintes conclusões:

  • O template chama-se MyItemStyle.
  • A variável SafeLinkUrl é definida para guardar o URL do item em causa. Este URL é obtido chamando o template OuterTemplate.GetSafeLink.
  • A variável DisplayTitle é definida para guardar o título do item em causa. O título é obtido chamando o template OuterTemplate.GetTitle.
  • A variável LinkTarget é definida para guardar o valor do atributo target da tag a no HTML final.
  • Para obter o valor de uma variável local deve usar-se a notação $nome-variável
  • Para obter o valor de um campo do item deve usar-se a notação @nome-campo
  • O atributo disable-output-escaping define se o conteúdo da variável deve ser escrito sem qualquer transformação, ou se os caracteres como "<" devem ser escritos como entidades "&lt;"

Notas

No último exemplo é usado um campo customizado do item a representar na web part. Porque é um campo customizado, a Content Query Web Part não conseguirá obter o seu valor e mostrá-lo. Para isso é necessário alterar a configuração da web part para que esta passe conhecer o tal campo:

  1. No menu da web part, seleccionar Export… e guardar o ficheiro .webpart
  2. Editar o ficheiro .wepart
  3. Alterar o elemento
    <property name="CommonViewFields" type="string"> para
    <property name="CommonViewFields" type="string">MyCustomField</property>.
  4. Caso existam mais campos customizados, então deve ser adicionados a este elemento, separados por caracteres ponto-e-vírgula.
  5. Importar o ficheiro .webpart (pode ser feito acedendo a Site Actions > Site Settings > Galleries > Web Parts e pressionando o botão Upload)
  6. Usar a nova versão da web par

Atenção: Quando se colocam campos (site columns) neste elemento tem que ser usado o Internal Name dos mesmos. O Internal Name é o nome inicial que foi dado ao campo, mesmo que depois disso tenha sido renomeado. Adicionalmente todos os caracteres especiais (espaços e acentos) são substituídos pelos códigos dos mesmos (por exemplo, os espaços são substituídos por _x0020_), por isso, o mais simples é não usar caracteres especiais nos nomes dos campos.

O que escrevi aqui decorre directamente da minha experiência com esta web part, mas encontrei alguns recursos que podem ser úteis:

Read here this post in english.

andrevala