Combinar texto en un documento

Una aplicación útil de la API de Documentos de Google es combinar información de una o más fuentes de datos en un documento.

En esta página, se describe la forma en que puedes tomar datos de una fuente externa y, luego, insertarlos en un documento de plantilla existente.

Una plantilla es un tipo especial de documento que contiene el mismo texto fijo para todos los documentos creados a partir de ella, junto con marcadores de posición designados en los que se puede colocar otro texto dinámico. Por ejemplo, una plantilla de contrato puede tener contenido fijo, junto con espacios para el nombre, la dirección y otros detalles del destinatario. Luego, tu app puede combinar datos específicos del cliente en la plantilla para crear documentos terminados.

Existen varios motivos por los que este enfoque resulta útil:

• Los diseñadores pueden optimizar el diseño de un documento con facilidad usando el editor de Documentos de Google. Esto es mucho más sencillo que ajustar parámetros en tu app para establecer el diseño renderizado.

• Separar el contenido de la presentación es un principio de diseño conocido que proporciona muchos beneficios.

Una receta básica

A continuación, se muestra un ejemplo de cómo puedes usar la API de Documentos para combinar datos en un documento:

1. Crea tu documento con contenido de marcador de posición para ayudarte con el diseño y el formato. Se conservará el formato de texto que quieras reemplazar.

2. Para cada elemento que insertarás, reemplaza el contenido del marcador de posición por una etiqueta. Asegúrate de usar cadenas que no aparezcan normalmente. Por ejemplo, {{account-holder-name}} podría ser una buena etiqueta.

3. En tu código, usa la API de Google Drive para hacer una copia del documento.

4. En tu código, usa el método batchUpdate() de la API de Documentos con el nombre del documento y, luego, incluye un ReplaceAllTextRequest.

Los IDs de documentos hacen referencia a un documento y se pueden obtener de la URL.

https://docs.google.com/document/d/documentId/edit

Puedes realizar varios reemplazos en la misma solicitud de BatchUpdate para lograr una mayor eficiencia. Consulta las prácticas recomendadas para las solicitudes por lotes para saber cómo agrupar llamadas a la API.

Ejemplo

Considera el siguiente ejemplo, que reemplaza 2 campos en todas las pestañas de una plantilla por valores reales para generar un documento terminado.

Para realizar esta combinación, puedes usar el siguiente código.

Java

String customerName = "Alice";
DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy/MM/dd");
String date = formatter.format(LocalDate.now());

List<Request> requests = new ArrayList<>();
// One option for replacing all text is to specify all tab IDs.
requests.add(new Request()
        .setReplaceAllText(new ReplaceAllTextRequest()
                .setContainsText(new SubstringMatchCriteria()
                        .setText("{{customer-name}}")
                        .setMatchCase(true))
                .setReplaceText(customerName)
                .setTabsCriteria(new TabsCriteria()
                        .addTabIds(TAB_ID_1)
                        .addTabIds(TAB_ID_2)
                        .addTabIds(TAB_ID_3))));
// Another option is to omit TabsCriteria if you are replacing across all tabs.
requests.add(new Request()
        .setReplaceAllText(new ReplaceAllTextRequest()
                .setContainsText(new SubstringMatchCriteria()
                        .setText("{{date}}")
                        .setMatchCase(true))
                .setReplaceText(date)));

BatchUpdateDocumentRequest body = new BatchUpdateDocumentRequest();
service.documents().batchUpdate(documentId, body.setRequests(requests)).execute();

Node.js

  let customerName = 'Alice';
  let date = yyyymmdd()
  let requests = [
    // One option for replacing all text is to specify all tab IDs.
    {
      replaceAllText: {
        containsText: {
          text: '{{customer-name}}',
          matchCase: true,
        },
        replaceText: customerName,
        tabsCriteria: {
          tabIds: [TAB_ID_1, TAB_ID_2, TAB_ID_3],
        },
      },
    },
    // Another option is to omit TabsCriteria if you are replacing across all tabs.
    {
      replaceAllText: {
        containsText: {
          text: '{{date}}',
          matchCase: true,
        },
        replaceText: date,
      },
    },
  ];

  google.options({auth: auth});
  google
      .discoverAPI(
          'https://docs.googleapis.com/$discovery/rest?version=v1&key={YOUR_API_KEY}')
      .then(function(docs) {
        docs.documents.batchUpdate(
            {
              documentId: '1yBx6HSnu_gbV2sk1nChJOFo_g3AizBhr-PpkyKAwcTg',
              resource: {
                requests,
              },
            },
            (err, {data}) => {
              if (err) return console.log('The API returned an error: ' + err);
              console.log(data);
            });
      });

Python

customer_name = 'Alice'
date = datetime.datetime.now().strftime("%y/%m/%d")

requests = [
        # One option for replacing all text is to specify all tab IDs.
        {
        'replaceAllText': {
            'containsText': {
                'text': '{{customer-name}}',
                'matchCase':  'true'
            },
            'replaceText': customer_name,
            'tabsCriteria': {
                'tabIds': [TAB_ID_1, TAB_ID_2, TAB_ID_3],
            },
        }},
        # Another option is to omit TabsCriteria if you are replacing across all tabs.
        {
        'replaceAllText': {
            'containsText': {
                'text': '{{date}}',
                'matchCase':  'true'
            },
            'replaceText': str(date),
        }
    }
]

result = service.documents().batchUpdate(
    documentId=document_id, body={'requests': requests}).execute()

Nota: En el caso de los documentos con varias pestañas, ReplaceAllTextRequest se aplica de forma predeterminada a todas las pestañas. Consulta la documentación de la solicitud para obtener más información sobre cómo trabajar con pestañas.

Administrar plantillas

Para los documentos de plantillas que define y posee la aplicación, crea la plantilla con una cuenta dedicada que represente a la aplicación. Las cuentas de servicio son una buena opción y evitan complicaciones con las políticas de Google Workspace que restringen el uso compartido.

Cuando crees instancias de documentos a partir de plantillas, usa siempre credenciales de usuario final. Esto permite a los usuarios controlar por completo el documento resultante y evita problemas de ajuste de escala relacionados con límites por usuario en Drive.

Para crear una plantilla con una cuenta de servicio, sigue estos pasos con las credenciales de la aplicación:

1. Crea un documento con documents.create en la API de Documentos.
2. Actualiza los permisos para permitir que los destinatarios del documento lo lean con permissions.create en la API de Drive.
3. Actualiza los permisos para permitir que los autores de plantillas escriban en ellos con permissions.create en la API de Drive.
4. Edita la plantilla según sea necesario.

Para crear una instancia del documento, sigue estos pasos con las credenciales del usuario:

1. Crea una copia de la plantilla con files.copy en la API de Drive.
2. Reemplaza los valores con documents.batchUpdate en la API de Documentos.