Tutorial: Enlazar controles de contenido a elementos XML personalizados
Actualización: noviembre 2007
Se aplica a |
---|
La información de este tema sólo se aplica a los proyectos y versiones especificados de Visual Studio Tools para Office de Microsoft Office. Tipo de proyecto
Versión de Microsoft Office
Para obtener más información, consulte Características disponibles por aplicación y tipo de proyecto. |
En este tutorial se muestra cómo se enlazan los controles de contenido de una personalización en el nivel del documento de Word 2007 a los datos XML almacenados en el documento.
Word 2007 permite almacenar datos XML, lo que se conoce como elementos XML personalizados, en un documento. Es posible controlar la presentación de estos datos enlazando los controles de contenido con objetos de los elementos XML personalizados. En el documento de ejemplo de este tutorial se muestra información sobre los empleados que está guardada en un elemento XML personalizado. Al abrir el documento, los controles de contenido muestran los valores de los elementos XML. Todos los cambios que se realicen en el texto de los controles de contenido se guardarán en el elemento XML personalizado.
Este tutorial ilustra las tareas siguientes:
Agregar controles de contenido al documento de Word en un proyecto en el nivel del documento en tiempo de diseño.
Crear un archivo de datos XML y un esquema XML que defina los elementos que se van a enlazar a los controles de contenido.
Asociar en esquema XML al documento en tiempo de diseño.
Agregar el contenido del archivo XML a un elemento XML personalizado del documento en tiempo de ejecución.
Enlazar los controles de contenido a objetos del elemento XML personalizado.
Enlazar un objeto DropDownListContentControl a un conjunto de valores que se definen en el esquema XML.
Nota: |
---|
Es posible que su equipo muestre nombres o ubicaciones diferentes para algunos de los elementos de la interfaz de usuario de Visual Studio incluidos en las instrucciones siguientes. La edición de Visual Studio que se tenga y la configuración que se utilice determinan estos elementos. Para obtener más información, vea Valores de configuración de Visual Studio. |
Requisitos previos
Necesita los componentes siguientes para completar este tutorial:
Visual Studio Tools para Office (componente opcional de Visual Studio 2008 Professional y Visual Studio Team System).
Microsoft Office Word 2007.
Visual Studio Tools para Office se instala de forma predeterminada con las versiones mostradas de Visual Studio. Para comprobar si está instalado, consulte Instalar Visual Studio Tools para Office.
Crear un nuevo proyecto de documento de Word
Cree el documento de Word 2007 que utilizará en el tutorial.
Para crear un nuevo proyecto de documento de Word 2007
Cree un proyecto de documento de Word con el nombre EmployeeControls mediante la plantilla de proyecto de documentos de Microsoft Office System 2007. Crear un nuevo documento para la solución. Para obtener más información, consulte Cómo: Crear proyectos de Visual Studio para Office.
Visual Studio abre el nuevo documento de Word en el diseñador y agrega el proyecto EmployeeControls al Explorador de soluciones.
Agregar controles de contenido al documento
Cree una tabla que contenga tres tipos diferentes de controles de contenido donde el usuario pueda ver o modificar la información sobre un empleado.
Para agregar controles de contenido al documento
En el documento de Word que se hospeda en el diseñador de Visual Studio, en el cinta de opciones, haga clic en la ficha Insertar.
En el grupo Tablas, haga clic en Tabla e inserte una tabla con dos columnas y tres filas.
En la primera columna, escriba texto de modo que se asemeje a la columna siguiente:
Nombre del empleado
Fecha de contratación
Puesto
En la segunda columna de la tabla, haga clic en la primera fila (junto a Nombre del empleado).
En la cinta de opciones, haga clic en la ficha Desarrollador.
Nota: Si la ficha Desarrollador no está visible, debe mostrarla primero. Para obtener más información, consulte Cómo: Mostrar la ficha Programador en la cinta de opciones.
En el grupo Controles, haga clic en el botón Texto para agregar un control PlainTextContentControl en la primera celda.
En la segunda columna de la tabla, haga clic en la segunda fila (junto a Fecha de contratación).
En el grupo Controles, haga clic en el botón Selector de fecha para agregar un control DatePickerContentControl en la segunda celda.
En la segunda columna de la tabla, haga clic en la tercera fila (junto a Puesto).
En el grupo Controles, haga clic en el botón Lista despegable para agregar un control DropDownListContentControl en la última celda.
Ésta es todas la interfaz de usuario de este proyecto. Si ejecuta el proyecto ahora, puede escribir texto en la primera fila y seleccionar una fecha en la segunda fila. El paso siguiente consiste en asociar los datos que desea mostrar con el documento en un archivo XML.
Crear el archivo de datos XML
Normalmente, obtendrá los datos XML para almacenar en un elemento XML personalizado de un origen externo, como un archivo o una base de datos. En este tutorial, creará un archivo XML con los datos de empleado marcados con los elementos que enlazará a los controles de contenido del documento. Para que los datos estén disponibles en tiempo de ejecución, incruste el archivo XML como un recurso en el ensamblado de personalización.
Para crear el archivo de datos
En el menú Proyecto, haga clic en Agregar nuevo elemento.
Aparecerá el cuadro de diálogo Agregar nuevo elemento.
En el panel Plantillas, seleccione Archivo XML.
Denomine el archivo employees.xml y, a continuación, haga clic en Agregar.
El archivo employees.xml se abre en el Editor de código.
Reemplace el contenido del archivo employees.xml por el siguiente texto.
<?xml version="1.0" encoding="utf-8" ?> <employees xmlns="https://schemas.microsoft.com/vsto/samples"> <employee> <name>Karina Leal</name> <hireDate>1999-04-01</hireDate> <title>Manager</title> </employee> </employees>
En el Explorador de soluciones, haga clic en employees.xml.
En la ventana Propiedades, seleccione la propiedad Acción de compilación y, a continuación, cambie el valor a Recurso incrustado.
En este paso, el archivo XML se incrusta como recurso en el ensamblado cuando se genera el proyecto. De este modo, puede obtener acceso al archivo XML en tiempo de ejecución.
Crear un esquema XML
Si desea enlazar un control de contenido a un único objeto de un elemento XML personalizado, no es necesario utilizar un esquema XML. Sin embargo, para enlazar el control DropDownListContentControl a un conjunto de valores, debe crear un esquema XML que valide el archivo de datos XML que creó anteriormente. El esquema XML define los valores posibles del elemento title. Enlazará el control DropDownListContentControl a este elemento posteriormente en este tutorial.
Para crear un esquema XML
En el menú Proyecto, haga clic en Agregar nuevo elemento.
Aparecerá el cuadro de diálogo Agregar nuevo elemento.
En el panel Plantillas, seleccione Esquema XML.
Asigne al esquema el nombre employees.xsd y haga clic en Agregar.
Se abre el diseñador de esquemas.
En el Explorador de soluciones, haga clic con el botón secundario del mouse en employees.xsd y, a continuación, en Ver código.
Reemplace el contenido del archivo employees.xsd por el siguiente esquema.
<?xml version="1.0" encoding="utf-8" ?> <xs:schema xmlns="https://schemas.microsoft.com/vsto/samples" targetNamespace="https://schemas.microsoft.com/vsto/samples" xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified"> <xs:element name="employees" type="EmployeesType"></xs:element> <xs:complexType name="EmployeesType"> <xs:all> <xs:element name="employee" type="EmployeeType"/> </xs:all> </xs:complexType> <xs:complexType name="EmployeeType"> <xs:sequence> <xs:element name="name" type="xs:string" minOccurs="1" maxOccurs="1"/> <xs:element name="hireDate" type="xs:date" minOccurs="1" maxOccurs="1"/> <xs:element name="title" type="TitleType" minOccurs="1" maxOccurs="1"/> </xs:sequence> </xs:complexType> <xs:simpleType name="TitleType"> <xs:restriction base="xs:string"> <xs:enumeration value ="Engineer"/> <xs:enumeration value ="Designer"/> <xs:enumeration value ="Manager"/> </xs:restriction> </xs:simpleType> </xs:schema>
En el menú Archivo, haga clic en Guardar todo para guardar los cambios realizados en los archivos employees.xml y employees.xsd.
Asociar el esquema XML al documento
Debe asociar el esquema XML al documento para enlazar el control DropDownListContentControl a los valores válidos del elemento title.
Para asociar el esquema XML al documento
Active EmployeeControls.docx en el diseñador.
En la cinta de opciones, haga clic en la ficha Desarrollador.
En el grupo XML, haga clic en Esquema.
En el cuadro de diálogo Plantillas y complementos, haga clic en la ficha Esquema XML y, a continuación, haga clic en Agregar esquema.
Vaya al esquema employees.xsd que creó anteriormente y que se encuentra en el directorio del proyecto, y haga clic en Abrir.
Haga clic en Aceptar en el cuadro de diálogo Configuración del esquema.
Haga clic en Aceptar para cerrar el cuadro de diálogo Plantillas y complementos.
Se abre el panel de tareas Estructura XML.
Cierre el panel de tareas Estructura XML.
Agregar un elemento XML personalizado al documento
Antes de poder enlazar los controles de contenido a los elementos del archivo XML, debe agregar el contenido del archivo XML a un nuevo elemento XML personalizado del documento.
Para agregar un elemento XML personalizado al documento
En el Explorador de soluciones, haga clic con el botón secundario en ThisDocument.cs o ThisDocument.vb y, a continuación, haga clic en Ver código.
Agregue las declaraciones siguientes a la clase ThisDocument. Este código declara varios objetos que utilizará para agregar un elemento XML personalizado al documento.
<Cached()> _ Public employeeXMLPartID As String = String.Empty Private employeeXMLPart As Office.CustomXMLPart Private Const prefix As String = "xmlns:ns='https://schemas.microsoft.com/vsto/samples'"
[CachedAttribute()] public string employeeXMLPartID = string.Empty; private Office.CustomXMLPart employeeXMLPart; private const string prefix = "xmlns:ns='https://schemas.microsoft.com/vsto/samples'";
Agregue el método siguiente a la clase ThisDocument. Este método obtiene el contenido del archivo de datos XML que se incrusta como recurso en el ensamblado y devuelve el contenido como una cadena XML.
Private Function GetXmlFromResource() As String Dim asm As System.Reflection.Assembly = _ System.Reflection.Assembly.GetExecutingAssembly() Dim stream1 As System.IO.Stream = asm.GetManifestResourceStream( _ "EmployeeControls.employees.xml") Using resourceReader As System.IO.StreamReader = _ New System.IO.StreamReader(stream1) If resourceReader IsNot Nothing Then Return resourceReader.ReadToEnd() End If End Using Return Nothing End Function
private string GetXmlFromResource() { System.Reflection.Assembly asm = System.Reflection.Assembly.GetExecutingAssembly(); System.IO.Stream stream1 = asm.GetManifestResourceStream( "EmployeeControls.employees.xml"); using (System.IO.StreamReader resourceReader = new System.IO.StreamReader(stream1)) { if (resourceReader != null) { return resourceReader.ReadToEnd(); } } return null; }
Agregue el método siguiente a la clase ThisDocument. El método AddCustomXmlPart crea un nuevo elemento XML personalizado que contiene una cadena XML que se pasa al método.
Para garantizar que el elemento XML personalizado sólo se crea una vez, el método únicamente crea el elemento XML personalizado si no existe en el documento ningún elemento XML personalizado con un GUID que coincida. La primera vez que se llama a este método, guarda el valor de la propiedad Microsoft.Office.Interop.Word.CustomXMLPart.Id en la cadena employeeXMLPartID. El valor de la cadena employeeXMLPartID se conserva en el documento porque se declaró mediante el atributo CachedAttribute.
Private Sub AddCustomXmlPart(ByVal xmlData As String) If xmlData IsNot Nothing Then employeeXMLPart = Me.CustomXMLParts.SelectByID(employeeXMLPartID) If (employeeXMLPart Is Nothing) Then employeeXMLPart = Me.CustomXMLParts.Add(xmlData) employeeXMLPart.NamespaceManager.AddNamespace("ns", _ "https://schemas.microsoft.com/vsto/samples") employeeXMLPartID = employeeXMLPart.Id End If End If End Sub
private void AddCustomXmlPart(string xmlData) { if (xmlData != null) { employeeXMLPart = this.CustomXMLParts.SelectByID(employeeXMLPartID); if (employeeXMLPart == null) { employeeXMLPart = this.CustomXMLParts.Add(xmlData, missing); employeeXMLPart.NamespaceManager.AddNamespace("ns", @"https://schemas.microsoft.com/vsto/samples"); employeeXMLPartID = employeeXMLPart.Id; } } }
Enlazar controles de contenido a objetos del elemento XML personalizado
Para enlazar cada control de contenido a un objeto del elemento XML personalizado, utilice la propiedad XMLMapping de cada control de contenido.
Para enlazar los controles de contenido a objetos del elemento XML personalizado
Agregue el método siguiente a la clase ThisDocument. Este método enlaza cada control de contenido con un objeto del elemento XML personalizado y establece el formato de presentación de la fecha de DatePickerContentControl.
Private Sub BindControlsToCustomXmlPart() Dim xPathName As String = "ns:employees/ns:employee/ns:name" Me.PlainTextContentControl1.XMLMapping.SetMapping(xPathName, _ prefix, employeeXMLPart) Dim xPathDate As String = "ns:employees/ns:employee/ns:hireDate" Me.DatePickerContentControl1.DateDisplayFormat = "MMMM d, yyyy" Me.DatePickerContentControl1.XMLMapping.SetMapping(xPathDate, _ prefix, employeeXMLPart) Dim xPathTitle As String = "ns:employees/ns:employee/ns:title" Me.DropDownListContentControl1.XMLMapping.SetMapping(xPathTitle, _ prefix, employeeXMLPart) End Sub
private void BindControlsToCustomXmlPart() { string xPathName = "ns:employees/ns:employee/ns:name"; this.plainTextContentControl1.XMLMapping.SetMapping(xPathName, prefix, employeeXMLPart); string xPathDate = "ns:employees/ns:employee/ns:hireDate"; this.datePickerContentControl1.DateDisplayFormat = "MMMM d, yyyy"; this.datePickerContentControl1.XMLMapping.SetMapping(xPathDate, prefix, employeeXMLPart); string xPathTitle = "ns:employees/ns:employee/ns:title"; this.dropDownListContentControl1.XMLMapping.SetMapping(xPathTitle, prefix, employeeXMLPart); }
Ejecutar el código al abrir el documento
Cree el elemento XML personalizado y enlace los controles personalizados a los datos cuando se abra el documento.
Para ejecutar el código al abrir el documento
Agregue el código siguiente al método ThisDocument_Startup de la clase ThisDocument. Este código obtiene la cadena XML del archivo employees.xml, agrega la cadena XML a una nuevo elemento XML personalizado del documento y enlaza los controles de contenido a los objetos del elemento XML personalizado.
Dim xmlData As String = GetXmlFromResource() If xmlData IsNot Nothing Then AddCustomXmlPart(xmlData) BindControlsToCustomXmlPart() End If
string xmlData = GetXmlFromResource(); if (xmlData != null) { AddCustomXmlPart(xmlData); BindControlsToCustomXmlPart(); }
Probar el proyecto
Al abrir el documento, los controles de contenido muestran los datos de los objetos del elemento XML personalizado. Puede hacer clic en el control DropDownListContentControl para seleccionar uno de los tres valores válidos del elemento title, que se definen en el archivo employees.xsd. Si modifica los datos de algún control de contenido, los nuevos valores se guardarán en el elemento XML personalizado del documento.
Para probar los controles de contenido
Presione F5para ejecutar el proyecto.
Compruebe que la tabla del documento se parece a la tabla siguiente. Cada una de las cadenas de la segunda columna se obtiene de un objeto del elemento XML personalizado del documento.
Nombre del empleado
Karina Leal
Fecha de contratación
April 1, 1999
Puesto
Administrador
Haga clic en la celda situada a la derecha de la celda Nombre del empleado y escriba un nombre diferente.
Haga clic en la celda situada a la derecha de la celda Fecha de contratación y seleccione una fecha diferente en el selector de fecha.
Haga clic en la celda situada a la derecha de la celda Puesto y seleccione un nuevo elemento de la lista desplegable.
Guarde y cierre el documento.
En el Explorador de Windows, abra la carpeta \bin\Debug situada en la ubicación de su proyecto.
Haga clic con el botón secundario del mouse en EmployeeControls.docx y, a continuación, haga clic en Cambiar nombre.
Llame al archivo EmployeeControls.docx.zip.
El documento EmployeeControls.docx se guarda en el formato XML abierto. Al cambiar el nombre de este documento por la extensión de nombre de archivo .zip, puede examinar el contenido del documento. Para obtener más información acerca del formato XML abierto, vea el artículo técnico Introducción a los formatos XML abiertos.
Haga doble clic en el archivo EmployeeControls.docx.zip.
Haga doble clic en la carpeta customXml.
Haga clic con el botón secundario en item2.xml y, a continuación, haga clic en Abrir.
Este archivo contiene el elemento XML personalizado que agregó al documento.
Compruebe que los elementos name, hireDate y title contienen los nuevos valores que especificó en los controles de contenido del documento.
Cierre el archivo item2.xml.
Pasos siguientes
Puede obtener más información acerca de cómo se utilizan los controles de contenido en los temas siguientes:
Utilizar todos los controles de contenido disponibles para crear una plantilla. Para obtener más información, consulte Tutorial: Crear una plantilla mediante controles de contenido.
Modificar los datos de los elementos XML personalizados mientras el documento está cerrado. La próxima vez que el usuario abra el documento, los controles de contenido que están enlazados a los elementos XML mostrarán los nuevos datos. Para obtener más información, consulte Cómo: Agregar elementos XML personalizados a documentos sin iniciar Microsoft Office.
Utilizar controles de contenido para proteger elementos de un documento. Para obtener más información, consulte Cómo: Proteger elementos de documentos mediante controles de contenido.
Vea también
Tareas
Cómo: Agregar controles de contenido a documentos de Word
Cómo: Proteger elementos de documentos mediante controles de contenido
Conceptos
Información general sobre elementos y controles Host
Limitaciones de programación de elementos y controles Host
Agregar controles a documentos de Office en tiempo de ejecución
Métodos auxiliares para controles host