Compartir vía

Agregar una representación personalizada del lado cliente a un complemento de SharePoint hospedado en SharePoint

  • Artículo

Este es el octavo de una serie de artículos sobre los conceptos básicos de desarrollo de Complementos de SharePoint hospedados en SharePoint. Primero debe familiarizarse con los Complementos de SharePoint y los artículos anteriores de esta serie, los cuales puede encontrar en Introducción a la creación de Complementos de SharePoint hospedados en SharePoint | Siguientes pasos.

Nota:

Si ha estado trabajando en esta serie sobre complementos hospedados por SharePoint, hay una solución de Visual Studio que puede usar para continuar con este tema. También puede descargar el repositorio que encontrará en SharePoint_SP-hosted_Add-Ins_Tutorials y abrir el archivo BeforeClientRenderedControl.sln.

Importante

Las personalizaciones basadas en JSLink (representación del cliente) no se admiten en la experiencia moderna. Esto incluye listas y bibliotecas modernas, así como la compatibilidad de JSLink en los elementos web de vista de lista de las páginas modernas. La representación del lado cliente es compatible con las experiencias clásicas de SharePoint Online o local.

Puede usar un poco de JavaScript del lado cliente para personalizar la representación de elementos web, la mayoría de tipos de campos (columnas) y otros controles, asignando un archivo de JavaScript a la propiedad JSLink del control, como SPField.JSLink. De esta forma, también puede agregar lógica de validación del lado cliente. En este artículo, vamos a personalizar la representación de un campo en una lista del complemento de SharePoint Orientación de los empleados utilizando la representación del lado cliente.

Nota:

  • Si el usuario final tiene JavaScript deshabilitado en el explorador, SharePoint revertirá a la representación y la validación del lado servidor.
  • La propiedad JSLink no es compatible con las listas de Encuesta o Eventos. Un calendario de SharePoint es una lista de eventos.

Crear y registrar código de JavaScript

  1. En el Explorador de soluciones, haga clic con el botón derecho en el nodo Scripts y, después, seleccione Agregar>Nuevo elemento>Web.

  2. Seleccione Archivo JavaScript y asígnele el nombre OrientationStageRendering.js.

  3. La representación personalizada del campo debería ocurrir automáticamente, así que utilice el código siguiente para agregar un método anónimo al JavaScript que se ejecuta automáticamente cuando se carga el archivo:

    (function () {

})();

  4. En el cuerpo de este método (entre los caracteres { }), agregue el siguiente código para crear objetos JSON (notación de objetos Javascript) para el contexto de reemplazo de representación, las plantillas en el contexto y las plantillas para los campos.

    var customRenderingOverride = {};
customRenderingOverride.Templates = {};
customRenderingOverride.Templates.Fields = {
}

  5. En el cuerpo del objeto de plantilla Campos, agregue el siguiente JSON.

    "OrientationStage": { "View": renderOrientationStage }
    • El nombre de la propiedad OrientationStage identifica el campo que ha personalizado la representación.
    • El valor de la propiedad es otro objeto JSON.
    • La propiedad View identifica el contexto de la página en que se aplica la representación personalizada. En este caso, el objeto indica a SharePoint que use la representación personalizada en las vistas de lista. Otras opciones funcionarían con los formularios Editar, Nuevo y Mostrar.
    • El valor de la propiedad renderOrientationStage es el nombre del método de representación personalizada que va a crear en un paso posterior.

  6. Lo último que debe hacer el método anónimo es informar al administrador de plantillas de SharePoint sobre la invalidación de la representación. Agregue la siguiente línea al final del cuerpo del método.

    SPClientTemplates.TemplateManager.RegisterTemplateOverrides(customRenderingOverride);

    El método tendrá la siguiente apariencia.

    (function () {
  var customRenderingOverride = {};
  customRenderingOverride.Templates = {};
  customRenderingOverride.Templates.Fields = {
      "OrientationStage": { "View": renderOrientationStage }
  }

  SPClientTemplates.TemplateManager.RegisterTemplateOverrides(customRenderingOverride);
})();

  7. Agregue el método siguiente al archivo. Establece el color del valor de la columna Fase de orientación en rojo cuando el valor es Not Started y en verde cuando el valor es Completed. El objeto ctx es un objeto de contexto de cliente declarado por un script de SharePoint incluido.

    function renderOrientationStage(ctx) {
  var orientationStageValue = ctx.CurrentItem[ctx.CurrentFieldSchema.Name];
  if (orientationStageValue == "Not Started")  {
      return "<span style='color:red'>" + orientationStageValue + "</span>"
  }
  else if (orientationStageValue == "Completed") {
      return "<span style='color:green'>" + orientationStageValue + "</span>"
  }
  else {
      return orientationStageValue;
  }
}

  8. En el Explorador de soluciones, expanda Columnas de sitio y Fase de orientación y, después, abra el archivo elements.xml.

  9. Para indicar a SharePoint que use el código JavaScript personalizado, agregue un nuevo atributo (JSLink) al elemento Field y, después, asigne la siguiente dirección URL como su valor: ~site/Scripts/OrientationStageRendering.js.

    Nota:

    La propiedad JSLink siempre es un archivo, no un método. No hay ninguna forma de indicar a SharePoint qué método ejecutar y ese es el motivo por el cual el archivo contiene un método que se ejecuta automáticamente.

    La etiqueta inicial del elemento Field ahora será similar a la siguiente.

    <Field
      ID="{some_guid_here}"
      Name="OrientationStage"
      Title="OrientationStage"
      DisplayName="Orientation Stage"
      Description="The current orientation stage of the employee."
      Type="Choice"
      Required="TRUE"
      Group="Employee Orientation"
      JSLink="~site/Scripts/OrientationStageRendering.js">
<!-- child elements and end tag omitted -->

  10. Abra la página Default.aspx y agregue el siguiente código como último elemento secundario del elemento asp:Content que tiene ContentPlaceHolderID establecido en PlaceHolderMain.

    <p><asp:HyperLink runat="server" NavigateUrl="JavaScript:window.location = _spPageContextInfo.webAbsoluteUrl + '/Lists/NewEmployeesInSeattle/AllItems.aspx';"
      Text="List View Page for New Employees in Seattle" /></p>

Ejecutar y probar el complemento

  1. Use la tecla F5 para implementar y ejecutar el complemento. Visual Studio instala temporalmente el complemento en el sitio de SharePoint de prueba y ejecuta el complemento inmediatamente.

  2. La representación del lado cliente que haya configurado afecta a la representación del campo solo en la página de vista de lista, no en el elemento web de la vista de lista que se incluye en la página principal. Esto es así porque la configuración predeterminada del elemento web es la representación del lado servidor. Hay formas de cambiar esto, pero son de un nivel muy avanzado para este ejemplo sencillo. Por lo tanto, para ver la representación del lado cliente en acción, seleccione el vínculo en la parte inferior de la Página de vistas de listas para Nuevos empleados de Seattle.

  3. Cuando se abra la página de vista de lista, establezca el valor Fase de orientación para algunos elementos en No iniciada y establezca otros en Completada para ver la representación del color personalizado.

    Figura 1. Lista con la representación del lado cliente personalizada

    Lista de nuevos empleados de Seattle con valores de Fase de orientación de

  4. Para finalizar la sesión de depuración, cierre la ventana del explorador o detenga la depuración en Visual Studio. Cada vez que seleccione F5, Visual Studio retirará la versión anterior del complemento e instalará la más reciente.

  5. Trabajará con este complemento y con la solución de Visual Studio en otros artículos. Es recomendable que vuelva a retirar el complemento cuando deje de trabajar con él por un tiempo. Haga clic con el botón derecho en el proyecto en el Explorador de soluciones y seleccione Retirar.

Pasos siguientes

En el siguiente artículo de esta serie, creará un botón personalizado para la cinta de opciones en la web de host de un complemento de SharePoint.