Procedimiento para personalizar el elemento web de consulta de contenido mediante propiedades personalizadas
Última modificación: miércoles, 22 de septiembre de 2010
Hace referencia a: SharePoint Server 2010
Puede usar el elemento web de consulta de contenido para crear vistas de datos personalizadas que se consultan desde varios orígenes y presentar todos esos datos en un solo lugar. Después de agregar el elemento web de consulta de contenido a una página web, puede personalizar el comportamiento de consultas, las listas personalizadas y los tipos de contenido del elemento web al establecer propiedades personalizadas. Hay 60 propiedades y métodos disponibles para la clase ContentByQueryWebPart, muchos de los cuales se pueden personalizar. En este tema se presentan algunas de las propiedades y se incluyen ejemplos de sintaxis y uso en formato de lenguaje de marcado de aplicaciones de colaboración (CAML) que se pueden agregar a un archivo .webpart.
Algunas propiedades del elemento web de consulta de contenido de Microsoft SharePoint Server 2010 se heredan de Microsoft SharePoint Foundation, y otras son exclusivas de SharePoint Server 2010. Este tema se centra en las propiedades presentadas en SharePoint Server 2010. A continuación se muestran dos categorías básicas de las propiedades del elemento web de consulta de contenido de SharePoint Server 2010:
Propiedades que establecen o invalidan un aspecto del comportamiento subyacente del elemento web. En algunos casos, estas propiedades también afectan a la interfaz de usuario (UI).
Propiedades que modifican la UI del elemento web sin establecer ni reemplazar el comportamiento subyacente.
Propiedades que modifican la UI y el comportamiento
Las propiedades del primer grupo, como las invalidaciones, suelen ser más eficaces ya que se pueden usar para modificar el comportamiento del elemento web. Si un usuario intenta modificar la UI o establecer otra propiedad que pueda afectar al comportamiento al que afecta esta propiedad, dicha propiedad "gana" en la UI; invalida otra configuración y determina el comportamiento del elemento web Consulta de contenido. Estas propiedades resultan útiles cuando se desea hacer lo siguiente:
Agregar campos persistentes y opciones de campo
Invalidar el comportamiento predeterminado de las consultas en todas las listas para que los cambios del campo y las opciones de campo de la UI se mantengan y no puedan reemplazarse ni romperse por otros cambios.
Cambiar el nombre de los nombres de columna compuestos y largos por nombres de variables de transformación XSLT más comunes y evitar crear transformaciones XSLT personalizadas para cada esquema
En la tabla 1 se describen algunas de las propiedades que modifican la interfaz de usuario y el comportamiento.
Tabla 1. Propiedades que modifican la interfaz de usuario y el comportamiento
Propiedad |
Descripción |
|---|---|
Solicita campos adicionales, lo que es necesario debido a que el elemento web de consulta de contenido no devuelve todos los campos de todos los elementos de forma automática. Debe solicitar que los campos se representen en una transformación XSLT. Esta propiedad es aditiva, lo que significa que se puede agregar más de un CommonViewField a un elemento web de consulta de contenido y extender sus propiedades base, como FieldDescription y FieldLabel. |
|
Omite los límites del comportamiento de la consulta impuestos por la interfaz de usuario del elemento web de consulta de contenido. Permite especificar la parte de la consulta de una consulta en todas las listas en CAML. Cuando se establece la propiedad QueryOverride, la interfaz de usuario para filtrar, ordenar, y agrupar aparece atenuada en el panel de herramientas. Por ejemplo, el elemento web de consulta de contenido admite tres filtros de manera predeterminada y puede resultar conveniente agregar más y asegurarse de que el comportamiento y los campos personalizados se guarden en la interfaz de usuario. |
|
Determina si la consulta en todas las listas debe realizar recursividad en los subsitios. De manera predeterminada, SharePoint Server 2010 realiza recursividad en los subsitios, lo que significa que el sitio primario y sus sitios secundarios se muestran. Cuando se establece la propiedad WebsOverride, el elemento web de consulta de contenido no realiza recursividad y solo muestra los resultados del sitio especificado. |
|
Invalida el comportamiento de la lista en SharePoint Server 2010 y admite varios tipos de listas, como bibliotecas de páginas, el tipo base de listas generales y tipos de lista específicos. Puede usar esta propiedad personalizada para establecer cualquier tipo de lista, incluso los que no se recogen en la UI porque la plantilla no está definida en la raíz o es un tipo base. Los tipos de listas se definen en el tema de referencia sobre el elemento de lista del SDK de Windows SharePoint Services 3.0. |
|
Proporciona al elemento web de consulta de contenido la posibilidad de solicitar un conjunto de campos de la consulta especificada, en lugar de realizar la solicitud automática en SharePoint Server 2010 para los campos base. |
|
Proporciona al elemento web de consulta de contenido la capacidad de cambiar el nombre de las columnas antes de pasar los datos a la transformación XSLT para su representación. |
Propiedades que modifican la interfaz de usuario sin invalidar el comportamiento
Como alternativa, es posible que necesite opciones de tamaño reducido para personalizar campos, opciones de campo, y opciones de organización y agrupación, así como opciones de filtros en la UI. Estas personalizaciones no afectan al comportamiento subyacente y se pueden invalidar por medio de propiedades del primer grupo que sí invalidan el comportamiento. Las personalizaciones de este tipo resultan útiles si desea hacer lo siguiente:
Ofrecer más opciones a través de un elemento web de consulta de contenido de las que se establecen inicialmente cuando se agrega una instancia del elemento web a la página
Afectar solo a un elemento web que no es probable que se invalide
Poner más opciones a disposición del usuario final
En la tabla 2 se describen algunas de las propiedades de este grupo.
Tabla 2. Propiedades que no invalidan el comportamiento
Propiedad |
Descripción |
|---|---|
Incluye uno o más campos adicionales (propiedad AdditionalFilterFields) u opciones de ordenación y agrupación (propiedad AdditionalGroupAndSortFields) que no suelen aparecer en la UI de las listas desplegables de filtro. Esto puede resultar útil si un campo no se aprovisiona como una columna de sitio sino que está presente en algunas listas y debe estar disponible en la UI. Cuando se establece esta propiedad, la UI ofrece esta columna para el filtrado. |
|
Incluye funcionalidad para filtrar otros valores distintos de los que admite la UI. Estas propiedades sirven para rellenar previamente algunos valores de la UI, como cuando se agrega el elemento web por primera vez a la página. Por ejemplo, es posible que desee especificar valores predeterminados, y filtrarlos por el rango de fechas relativo a la fecha actual. |
Enfoques para personalizar un elemento web Consulta de contenido
Existe más de una forma de establecer o modificar las propiedades personalizadas en un elemento web de consulta de contenido, y el método elegido dependerá de los objetivos que se persiguen, el lugar del sitio donde se encuentra y el proceso de diseño del sitio web. Por ejemplo, si personaliza un diseño de página existente, puede usar Microsoft SharePoint Designer 2010 y personalizar el elemento web de consulta de contenido mientras personaliza el diseño de página. Si crea un elemento web de consulta de contenido nuevo y personalizado para un diseño de página existente, puede usar SharePoint Designer 2010 para agregar o modificar propiedades personalizadas.
Para modificar las propiedades personalizadas de un elemento web de consulta de contenido existente, puede exportar el archivo .webpart, hacerle una copia y cambiar el nombre del original, modificar las propiedades personalizadas en la copia del archivo .webpart y, a continuación, importarlo en una zona de elementos web de la página. Al cambiar el nombre del archivo .webpart original se garantiza que existirá una copia del archivo .webpart original para futuros escenarios de actualización.
Para exportar un archivo .webpart, establezca sus propiedades personalizadas y, a continuación, impórtelo
Inicie sesión en el sitio web.
En el menú Acciones del sitio, haga clic en Editar página.
Busque el elemento web de consulta de contenido en la página y, a continuación, en el menú Edición del elemento web, haga clic en Exportar.
Guarde el archivo .webpart.
Cambie el nombre del archivo .webpart y, a continuación, use el editor de textos o SharePoint Designer 2010 para abrir el archivo con el nombre cambiado.
Nota
Al cambiar el nombre del archivo .webpart original se garantiza que existe una copia del archivo .webpart original para futuros escenarios de actualización.
Agregue o modifique las propiedades y los valores de propiedad y, a continuación, guarde los cambios.
En el menú Página, elija Agregar elementos web y, a continuación, haga clic en Examinar.
Seleccione el elemento web que va a importar de la Lista de elementos web y, a continuación, haga clic en Aceptar.
Arrastre el elemento web a una zona de elementos web de la página.
Ejemplo
Descripción
En esta sección se describen las propiedades personalizadas y se incluyen ejemplos de formato y código para instrucciones de la propiedad personalizadas y consultas CAML de un elemento web de consulta de contenido. Primero se introduce información de campo base de formato y sugerencias para usar la propiedad CommonViewFields. A continuación, se presenta una consulta CAML completa y, posteriormente, se ofrece un tutorial sobre las propiedades QueryOverride, ListsOverride, WebsOverride y ViewFieldsOverride que ésta establece. Puede agregar cada uno de los valores de propiedad presentados en la consulta CAML a su instrucción <property value> correspondiente en el archivo .webpart. Por último, se presenta la propiedad DataColumnRenames y las propiedades de opciones de ordenación, agrupación y filtro.
Propiedad CommonViewFields
Puede usar dos formatos al personalizar la propiedad CommonViewFields. Puede especificar los campos por su nombre interno o por una combinación de nombre de campo y nombre interno, como se indica a continuación:
Nombre interno de campo
Nombre interno de campo, tipo de campo
La notación que se usa para los caracteres especiales distingue el nombre interno del nombre usado en la UI. Por ejemplo, un espacio entre palabras se representa mediante _x0020_ en el nombre interno. Puede ver el nombre interno al ver el parámetro de encadenamiento de consulta de una página Columna de sitio, o mediante el código de elemento web después de crear el campo. Puede ver el código de elemento web al establecer el elemento web para filtrar por campo, al exportar el elemento web y, a continuación, ver las propiedades de filtro.
Nota
Para obtener una lista de field types adicionales que puede solicitar la propiedad CommonViewField, vea la enumeración de SPFieldType en el SDK de SharePoint Foundation 2010. SharePoint Server 2010 incluye cuatro campos adicionales (HTML, Image, Link y SummaryLink) que se pueden solicitar. Las delimitaciones que recoge este tema identifican los tipos de datos puede incluir una propiedad CommonViewFields.
También puede combinar definiciones CommonViewFields en instrucciones compuestas, lo cual resulta útil para establecer más de un campo en una instrucción de propiedad. Use un punto y coma para separar los campos al combinar definiciones en una instrucción. Por ejemplo:
Nombre interno de campo; Nombre interno de campo, tipo de campo
CommonViewFields es una propiedad aditiva, lo que significa que se puede agregar un campo de vista común sobre los campos base que siempre solicita el elemento web de consulta de contenido. Los campos base solicitan columnas predeterminadas mediante GUID y aparecen en la interfaz de usuario como los nombres de columna de sitio. En la Tabla 3 se enumeran los tipos y nombres de campo base.
Tabla 3. Tipos y nombres de campo base
Nombre |
Tipo |
|---|---|
Title |
Text |
FileRef |
Lookup |
ID |
Counter |
Modified |
DateTime |
Author |
"User" |
Editor |
User |
Created |
DateTime |
PublishingRollupImage |
Image |
Level |
"Number" |
Note |
"Note" |
En el siguiente ejemplo, la propiedad CommonViewFields establece el GUID, que SharePoint Server 2010 usa de forma interna para hacer referencia al nombre interno del campo, al tipo de campo, al nombre interno de CommonViewField y a su tipo base, seguido por el GUID del tipo base.
<property name="CommonViewFields" type="string">_Level,Number;PublishingRollupImage;</property>
Propiedades QueryOverride, ListsOverride, WebsOverride y ViewFieldsOverride
Cada propiedad de invalidación (QueryOverride, ListsOverride, WebsOverride y ViewFieldsOverride) invalida un comportamiento del elemento web de consulta de contenido predeterminado. Para invalidar un comportamiento, genere una consulta CAML que defina las condiciones que desea establecer.
Nota
Para obtener más información sobre los comandos y la sintaxis de CAML, vea Esquemas Core del Lenguaje de marcado de la aplicación de colaboración (CAML) en el SDK de SharePoint Foundation 2010.
En el siguiente ejemplo se muestra cómo establecer las propiedades personalizadas para el elemento web de consulta de contenido mediante una consulta CAML. La consulta CAML hace lo siguiente:
Recupera un campo Created
Establece la consulta de modo que recupere elementos actualizados en los últimos siete días y los ordena en orden descendente
Especifica el tipo de lista desde el que se realizará la consulta
Recupera datos de forma recursiva del sitio web especificado y sus sitios secundarios
Recupera valores para un campo específico que se mostrarán para cada elemento
Se muestra la consulta completa, y se describe en detalle en las siguientes secciones.
1 <ViewFields>
2 <FieldRef Name="Title" Nullable="True" Type="Text"/>
3 <FieldRef Name="Comments" Nullable="True" Type="Note"/>
4 </ViewFields>
5 <Lists ServerTemplate="850"></Lists>
6 <Webs Recursive="True" />
7 <RowLimit>15</RowLimit>
8 <![CDATA[
9 <Where>
10 <Gt>
11 <FieldRef Name="Created" Nullable="True" Type="DateTime"/>
12 <Value Type="DateTime"><Today OffsetDays="-7"/></Value>
13 </Gt>
14 </Where>
15 <OrderBy>
16 <FieldRef Name="Created" Nullable="True" Type="DateTime"
17 Ascending="FALSE"/>
18 </OrderBy>]]>
Propiedad QueryOverride
Las líneas 8 a 19 definen la propiedad QueryOverride.
8 <![CDATA[
9 <Where>
10 <Gt>
11 <FieldRef Name="Created" Nullable="True" Type="DateTime"/>
12 <Value Type="DateTime"><Today OffsetDays="-7"/></Value>
13 </Gt>
14 </Where>
15 <OrderBy>
16 <FieldRef Name="Created" Nullable="True" Type="DateTime"
17 Ascending="FALSE"/>
18 </OrderBy>
19 </Query>]]>
En el ejemplo anterior:
Las líneas 8 a 10 definen la consulta y abren la cláusula <where>.
La línea 11 se refiere a un campo de tipo base con el nombre "Created", y su tipo de campo DateTime.
La línea 12 establece el valor de este campo en DateTime y establece un desplazamiento de -7, lo que significa que se resta 7 a la fecha por la que la consulta realiza el filtrado.
Las líneas 13 y 14 cierran la cláusula <where>.
La línea 15 abre la cláusula <OrderBy>, que determina el criterio de ordenación para los campos especificados.
Las líneas 16 y 17 establecen el criterio de ordenación para el campo "Created". El elemento web muestra estos datos en orden descendente.
Propiedad ListsOverride
También puede usar una consulta CAML para recuperar elementos de listas de SharePoint Foundation 2010 y SharePoint Server 2010. En la tabla 4 se muestran tres ejemplos de instrucciones CAML que recuperan elementos de distintos tipos de lista.
Tabla 4. Tres ejemplos de instrucciones CAML que recuperan elementos de distintos tipos de lista
Tipo de lista |
Property (Instrucción) |
|---|---|
Bibliotecas de páginas |
|
Tipo base Lista general |
|
Un tipo de lista específico |
|
En el ejemplo, la línea 5 define la propiedad ListsOverride.
5 <Lists ServerTemplate="850"></Lists>
En este caso, la consulta usa ServerTemplate="850" para invalidar la lista actual en uso. Puede buscar una enumeración de tipos de lista disponibles en la propiedad Lists del SDK de SharePoint Foundation 2010.
Propiedad WebsOverride
Puede usar CAML para establecer la propiedad WebsOverride para recuperar elementos de forma recursiva, como se muestra en el siguiente código de ejemplo.
<![CDATA[
<Webs Recursive="True"/>
]]>
O bien, puede recuperar elementos solo de los sitios especificados.
<![CDATA[
<Webs/>
]]>
En la línea 6 del ejemplo, establecemos la propiedad para que recupere elementos de forma recursiva.
6 <Webs Recursive="True"/>
Propiedad ViewFieldsOverride
Para mostrar valores para cualquier elemento en el elemento web, establezca la propiedad ViewFieldsOverride para que recupere datos de un tipo determinado de un campo especificado, como se muestra en el siguiente ejemplo de código.
<![CDATA[
<FieldRef Name="Comments" Nullable="True" Type="Note"/>
<FieldRef Name="Created" Nullable="False" Type="User"/>
]]>
Al establecer Nullable="True" se devuelven elementos que no tienen esta columna.
En la muestra de código, las líneas 1 a 4 establecen la propiedad ViewFieldsOverride:
1 <ViewFields>
2 <FieldRef Name="Title" Nullable="True" Type="Text"/>
3 <FieldRef Name="Comments" Nullable="True" Type="Note"/>
4 </ViewFields>
La línea 1 abre la cláusula <ViewFields>, que establece la propiedad ViewFieldsOverride.
Las líneas 2 y 3 se refieren al campo Title (un campo de texto) y al campo Comments (un campo de nota).
La línea 4 cierra la sección <ViewFields>.
Propiedad DataColumnRename
La propiedad DataColumnRename sirve para cambiar el nombre de las columnas mediante programación. Esta propiedad puede ayudar a minimizar la personalización de esquemas y XSLT, o a realizar operaciones de cambio de nombre personalizadas o masivas. Por ejemplo, puede cambiar el nombre de un nombre de columna compuesto como KBArticleTitle por un nombre de variable de transformación XSLT común como Title, y eliminar la necesidad de crear una transformación XSLT personalizada para cada esquema personalizado.
Separe los valores de cambio de nombre de columnas mediante punto y comas y use el formato originalName,newName.
<![CDATA[<property name="DataColumnRenames" type="string">KBArticleTitle,Title</property>]]
Nota
Si cambia el nombre de una columna por un nombre que ya existe, la operación de cambio de nombre produce un error.
Opciones de ordenación, agrupación, filtro y campo adicional
Establezca las propiedades de este grupo para agregar campos, agrupaciones, opciones de ordenación y agrupación, filtros y opciones de filtros. Puede especificar campos por su nombre interno, GUID, una combinación de nombre interno y nombre para mostrar, o GUID y nombre para mostrar.
Defina las propiedades AdditionalFilterFields y AdditionalGroupAndSortFields mediante uno de los siguientes formatos:
internalName
internalName,DisplayName
GUID
GUID,DisplayName
También puede combinar las definiciones de AdditionalFilterFields y AdditionalGroupAndSortFields en instrucciones compuestas, lo cual resulta útil para establecer más de un campo en una instrucción de propiedad. Use punto y coma para separar los campos al combinar definiciones en una instrucción, como se muestra a continuación:
internalName;GUID; internalName,DisplayName;GUID,DisplayName
Al establecer la propiedad AdditionalFilterFields se puede agregar un campo de filtro Created a la UI, como se muestra en el siguiente ejemplo de código.
<![CDATA[<property name="AdditionalFilterFields" type="string">Created</property>]]
Al establecer la propiedad AdditionalGroupAndSortFields, se puede agregar una opción Created a las listas de agrupación y ordenación de la interfaz de usuario.
<!CDATA[<property name="AdditionalGroupAndSortFields" type="string">Created</property>]]
Propiedades de filtro
Puede usar propiedades personalizadas para extender los valores de filtro que admite la UI. Al establecer o modificar cualquiera de las propiedades de operador de campo de encadenamiento de filtro, valor de filtro, tipo de filtro o campo de filtro se agrega o cambia el comportamiento del filtro en la UI.
Nota
Las propiedades de filtro no invalidan la UI, sino que rellenan previamente la UI con valores predeterminados.
Las propiedades de valor de filtro, tipo de filtro y campo de filtro siempre son del tipo string:
<property name="FilterField1" type="string" />
<property name="FilterType1" type="string" />
<property name="FilterValue1" type="string" />
<property name="FilterOperator1" type="Microsoft.SharePoint.Publishing.WebControls.ContentByQueryWebPart+FilterFieldQueryOperator, Microsoft.SharePoint.Publishing, Version=12.0.0, Culture=neutral" PublicKeyToken=71e9bce111e9429c"/>
El siguiente código de filtro de ejemplo muestra un filtro Created en formato DateTime y los elementos que se crearon después del 25 de octubre de 2011:
<property name="FilterField1" type="string">Created</property>
<property name="FilterType1" type="string">DateTime</property>
<property name="FilterValue1" type="string">Today-7</property>
<property name="FilterOperator1" type="Microsoft.SharePoint.Publishing.WebControls.ContentByQueryWebPart+FilterFieldQueryOperator, Microsoft.SharePoint.Publishing, Version=12.0.0, Culture=neutral" PublicKeyToken=71e9bce111e9429c"/>
Use el siguiente formato para establecer el parámetro type en las instrucciones de propiedad de operador de encadenamiento de filtros y operador de filtro: PropertyName, namespace, Version, Culture, PublicKeyToken.
<property name="FilterOperator1" type="Microsoft.SharePoint.Publishing.WebControls.ContentByQueryWebPart+FilterFieldQueryOperator, Microsoft.SharePoint.Publishing, Version=12.0.0, Culture=neutral" PublicKeyToken=71e9bce111e9429c"/>
<property name="Filter1ChainingOperator" type="Microsoft.SharePoint.Publishing.WebControls.ContentByQueryWebPart+FilterField, Microsoft.SharePoint.Publishing, Version=12.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c">Eq</property>
Los valores válidos para las propiedades de encadenamiento de filtros y operador de filtro son distintas, como se muestra a continuación:
Las propiedades de operador de filtro muestran los botones Y y O en la UI.
Las propiedades de encadenamiento de filtros rellenan el segundo campo en las listas Mostrar los elementos cuando de la sección Filtros adicionales de la UI.
En la tabla 5 se proporcionan los valores válidos para las propiedades de operador de filtro.
Tabla 5. Valores válidos para las propiedades de operador de filtro
Valor |
Valor para mostrar |
|---|---|
And |
Y |
Or |
O |
En la tabla 6 se proporcionan los valores válidos para las propiedades de operador de encadenamiento de filtro.
Tabla 6. Valores válidos para las propiedades de operador de encadenamiento de filtro
Valor |
Valor para mostrar |
|---|---|
Eq |
es igual a |
Neq |
es distinto de |
Gt |
es mayor que |
Geq |
es mayor que o igual a |
Lt |
es menor que |
Leq |
es menor que o igual a |
BeginsWith |
comienza por |
Contains |
contiene |
Vea también
Tareas
Procedimiento para personalizar XSL para el elemento web de consulta por contenido
Procedimiento para mostrar campos personalizados en un elemento web de consulta de contenido
Procedimiento para personalizar RSS para el elemento web de consulta de contenido