Friday, December 8, 2006

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 part

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:


Master Pages e Content Place Holders

Uma das razões pelas quais customizar o aspecto do WSS v3 (operação também designada por branding) é muito mais simples do que na versão anterior, é o facto de este utilizar Master Pages. Basicamente, uma master page é um ficheiro .aspx (mas com extensão .master) que serve de base às páginas de um site (estas com extensão .aspx). Funcionam um pouco como os templates do Powerpoint em que podemos definir um Slide Master e depois, em cada novo slide que criarmos, só precisamos de preencher os espaços com conteúdos. Neste caso o que fazemos é criar uma master page, na qual colocamos controlos ASP.Net do tipo ContentPlaceHolder. Em todas as páginas que forem baseadas nessa master page, só precisamos de escrever o conteúdo desses place holders através também de um controlo ASP.Net: o Content.

Quando é pedida uma página destas ao servidor web, este encarregar-se-á de ir buscar a master page e preencher os espaços dos place holders com o código colocado página requisitada dentro dos controlos Content, criando assim a página final que é depois transmitida ao browser cliente. A grande vantagem deste mecanismo é a reutilização de todo o código que se repete em todas as páginas de um site facilitando muito a manutenção do mesmo.

Em SharePoint, um site utiliza duas master pages:

  • A Site Master Page, que é usada nas páginas de publishing e portanto normalmente alvo de mais customização; e
  • A System Master Page, que é usada nas páginas de configuração e listas que muita vezes não estão acessíveis aos utilizadores comuns do portal.

Uma das primeiras tarefas que são executadas no branding de um site em SharePoint é a criação de novas Master Pages que darão o aspecto desejado a todo o portal. No entanto, há que ter em conta que, ao mudarmos a master page de um site, todas as páginas existentes vão passar a usar a nova master page. Ou seja, vão colocar conteúdos nos place holders que esta define e que, se lá não estiverem, causarão um erro de execução no site.

Para poupar trabalho a quem queira saber quais são os place holders que tem que colocar (nem que seja num asp:panel invisível) nas suas master pages, coloco abaixo uma lista.

Na Site Master Page:

  • PlaceHolderPageTitle
  • PlaceHolderAdditionalPageHead
  • PlaceHolderLogin
  • PlaceHolderSearchArea
  • PlaceHolderTitleBreadcrumb
  • PlaceHolderLeftNavBar
  • PlaceHolderPageTitleInTitleArea
  • PlaceHolderMain
  • PlaceHolderPageImage
  • PlaceHolderBodyLeftBorder
  • PlaceHolderNavSpacer
  • PlaceHolderTitleLeftBorder
  • PlaceHolderTitleAreaSeparator
  • OSSConsole
  • PlaceHolderMiniConsole
  • PlaceHolderCalendarNavigator
  • PlaceHolderLeftActions
  • PlaceHolderPageDescription
  • PlaceHolderBodyAreaClass
  • PlaceHolderTitleAreaClass

Na System Master Page:

  • PlaceHolderPageTitle
  • PlaceHolderAdditionalPageHead
  • PlaceHolderSiteName
  • PlaceHolderSearchArea
  • PlaceHolderTopNavBar
  • WSSDesignConsole
  • SPNavigation
  • PlaceHolderTitleLeftBorder
  • PlaceHolderTitleBreadcrumb
  • PlaceHolderPageTitleInTitleArea
  • PlaceHolderMiniConsole
  • PlaceHolderTitleRightMargin
  • PlaceHolderTitleAreaSeparator
  • PlaceHolderLeftNavBarDataSource
  • PlaceHolderCalendarNavigator
  • PlaceHolderLeftNavBarTop
  • PlaceHolderLeftNavBar
  • PlaceHolderLeftActions
  • PlaceHolderNavSpacer
  • PlaceHolderLeftNavBarBorder
  • PlaceHolderBodyLeftBorder
  • PlaceHolderPageDescription
  • PlaceHolderMain
  • PlaceHolderBodyRightMargin
  • PlaceHolderFormDigest
  • PlaceHolderUtilityContent
  • PlaceHolderBodyAreaClass
  • PlaceHolderTitleAreaClass

Saturday, December 2, 2006

Tip #2: Alterar Templates e Layouts usados em Subsites

O Administrador de um site tem a possibilidade de limitar quais os templates que podem ser utilizados para criar subsites e quais os layouts de páginas que podem ser utilizados para criar novas páginas. Essa configuração é feita acedendo a:

  1. Menu Site Actions
  2. Opção Site Settings
  3. Secção Look and Feel
  4. Opção Page layouts and site templates

Neste ecrã podemos indicar se os subsites podem usar todos os templates disponíveis ou apenas um conjunto limitado destes, e se as páginas criadas neste site podem usar todos os layouts disponíveis ou apenas um conjunto limitado destes.

Tip #1: Alterar o Nome a uma Site Column

Em Windows SharePoint Services v3.0, as site columns têm dois nomes:

  • o Internal Name que é o nome que lhe foi atribuído aquando da sua criação e que ficará sempre associado à site column; e
  • o nome actual da site column que inicialmente é o mesmo que o Internal Name mas pode ser alterado posteriomente.

Este facto pode causar alguns problemas se, quando estivermos escrever código que interaja com o object model ou a configurar alguma funcionalidade do SharePoint, for necessário identificar uma coluna pelo nome. Nesta situação, o SharePoint estará sempre à espera do Internal Name e não do nome actual.

Thursday, November 9, 2006

Customização dos Níveis no Menu de Navegação de Topo

O SharePoint cria em todas as site collections um menu de navegação de topo com 1 ou 2 níveis, dependendo do template do site utilizado e se a feature de Publishing Infrastructure está activada. No entanto, existem situações em que seria desejável poder ter mais que dois níveis nesse menu. Para aqueles que, como eu, procuraram essa opção em todos os ecrãs de configuração, posso dizer-vos que não existe... mas é possível fazer essa costumização, da seguinte forma:

  1. Utilizando o SharePoint Designer, abrir o site principal da site collection.

  2. Na árvore do site, aceder à pasta _catalogs\masterpages e editar a master page
    default.master. Esta master page existe fisicamente no sistema de ficheiros (e por essa razão é designada como file system page) e quando é editada no SharePoint Designer é automaticamente criada uma cópia editável da mesma que é depois guardada na base de dados, passando a ser uma database page. Este processo é conhecido como ghosting uma vez que a página passa a ser virtual deixando de existir fisicamente.

  3. No código da master page, procurar a tag relativa ao controlo do menu de navegação do topo:
    <SharePoint:AspMenu ID="TopNavigationMenu"...

  4. Alterar o valor do atributo MaximumDynamicDisplayLevels para 3 (ou para o número de níveis que se pretende visualizar no menu).

  5. Gravar a master page e fazer refresh ao site.

Nota 1: O passo 2 é importante porque, se for editada a versão física da master page existente normalmente na pasta c:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\GLOBAL, as alterações irão repercurtir-se em todos os sites existentes (baseados nessa master page) e sites criados posteriormente (baseados em templates do SharePoint). Normalmente não é esse o comportamento desejado.

Nota 2: Se, depois do processo apresentado, tentarmos alterar os itens do menu de navegação de topo, usando as opções de configuração do site (acessível através de Site Actions > All Site Settings > Navigation Settings) rapidamente chegaremos à conclusão que só é possível alterar manualmente os dois primeiros níveis do menu. Trata-se de uma limitação do controlo usado pelo SharePoint para editar o site map, que apenas permite a edição de dois níveis. Isto nada tem a haver com o facto de termos configurado o menu para mostrar mais do que dois níveis. Então como é que adiciono novas entradas ao menu de navegação de topo? Ver próxima nota...

Nota 3: O SharePoint cria automaticamente o site map que alimenta o menu, à medida que criamos novos conteúdos no portal. A única forma que temos de gerir esse menu é adicionar criteriosamente os conteúdos de forma a que o site map gerado automaticamente origine a estrutura de menu que desejamos. Para isso temos apenas que perceber as regras que regem esse processo e que são relativamente simples:

  1. A hierarquia de sites existente na site collection é mapeada directamente na hierarquia do menu de navegação de topo. Quer isto dizer que no primeiro nível do menu aparecem todos os subsites do site principal da site collection, no segundo nivel aparecem todos os subsites do site seleccionado no primeiro nível, e assim por diante.

  2. Cada site tem um conjunto de itens de navegação local, que correspondem a links para conteúdos locais a esse site (document libraries, listas, surveys, etc...) e são mostrado num menu de navegação lateral com dois níveis. No menu de navegação de topo, no mesmo nível em que são colocados os links para os subsites de um determinado site, são também colocados os itens do primeiro nivel da navegação local que correspondam a conteúdos e não a headings. Complicado? Talvez com um exemplo se perceba melhor...

Exemplo: considere-se uma site collection com dois sites, A e B. O site A tem dois subsites, A1 e A2, e três listas, L1, L2 e L3. Na navegação local do site A1, a lista L1 está colocada sob o heading Listas (portanto, no segundo nível), e as restantes estão no primeiro nível. Neste caso, o menu de navegação de topo mostra no primeiro nível um link para o site A e outro link para o site B. Seleccionando o site A no primeiro nível, é mostrado o segundo nível que tem quatro links: para o site A1, para o site A2, para a lista L2 e para a lista L3. A lista L1 está no segundo nível por isso não aparece.

Conclusão: este comportamento do SharePoint faz com que apenas exista um determinado nível no menu, se o nível anterior for um subsite. Não é possível fazer vários níveis de headings com links configuráveis manualmente, que seria a forma mais flexível e, para mim, mais desejável. Para quem precise mesmo de um comportamento mais flexível, é sempre possível configurar o controlo do menu para que deixe de usar o site map do SharePoint e passe a usar um ficheiro XML ou uma outra classe criada especificamente para o efeito.

Sunday, October 29, 2006

Diferenças entre WSS 3.0 e as várias versões do Office Sharepoint Server 2007

A equipa de desenvolvimento do Sharepoint colocou no blog oficial uma matriz com as diferenças entre WSS 3.0, Sharepoint Portal Server 2003 e as várias versões de Office Sharepoint Server 2007. Muito útil para quem tem dúvidas se necessita do MOSS ou se o WSS é suficiente.

Sunday, October 22, 2006

Usar WebDAV para inserir/obter conteúdos no Sharepoint

Uma forma muito fácil e útil de colocar e extrair conteúdos de um servidor baseado em Sharepoint é através de WebDAV.

O que é o WebDAV?

WebDAV significa Web-based Distributed Authoring and Versioning e é uma extensão ao protocolo HTTP para permitir a edição dos conteúdos localizados remotamente em servidores web. A ideia é tornar realidade a visão original da web, como sendo um meio editável e colaborativo, e não apenas destinado a consulta. Para saber mais sobre o protocolo em questão, visita o site http://www.webdav.org.

O que tem o WebDAV a ver com o Sharepoint?

Utilizando WebDAV torna-se possível aceder, através do Windows Explorer, aos documentos armazenados nas Document Libraries de Sharepoint e às paginas aspx que compõem um portal baseado em Sharepoint. Isto é especialmente útil para fazer uploads, movimentar documentos e outras tarefas de gestão de conteúdos.

Como se usa?

No servidor web é necessário activar a extensão WebDAV.
No caso de ser um servidor Windows 2003 Server a correr IIS, basta seguir dois passos:

  • Aceder à ferramenta de administração do IIS, e na zona das extensões, permitir a extensão WebDAV.
  • Aceder aos serviços do Windows, e verificar que o serviço Web Client está a correr com um utilizador com permissões para escrever nas pastas do servidor web.

Na máquina cliente é necessário possuir uma aplicação cliente ou um sistema operativo com suporte nativo para WebDAV (a maioria possui esse suporte). No caso do Windows, o próprio Windows Explorer é um cliente WebDAV.

Assim que ambas as condições sejam cumpridas, torna-se possível aceder aos ficheiros que estão no servidor web como se de um share de rede se tratasse, ou seja, através de um endereço do tipo: \\servidor\doclibname\.

Problemas...

Há um cuidado em especial que é preciso ter no uso de WebDAV: o nome do servidor e as respectivas pastas (ou document libraries) não devem conter caracteres especiais (como sinais + ou -, acentos, etc). Isto porque, apesar de o Windows Explorer lidar bem com isso, outros clientes WebDAV não o conseguirão fazer e substituirão os caracteres por códigos do tipo %2F. Quando isto acontecer o servidor rejeitará a ligação como se a path fosse inválida.