EmailTools

carlos Noticias Fecha de creación: 10-05-2019 00:00:00 Última actualización: 04-08-2021 Contador de visitas: 3132

NOTA: Esta clase está obsoleta. Sustituida por la clase NewMail.

Esta clase simplifica el envío de mails. Nos permite enviar comunicaciones electrónicas totalmente personalizables mediante una lista de valores y usando una plantilla de Twig para dar formato visual al contenido del mail. Para el correcto funcionamiento debemos primero establecer la configuración del servidor y la cuenta de correo que usaremos para los envíos, y lo hacemos en en el apartado Por defecto (menú administrador > panel de control), en la pestaña Email.

Sistema de plantillas

Para el diseño visual del mail se utiliza una plantilla Twig. FacturaScripts dispone de una plantilla base BasicTemplate.html.twig pero podemos crear nuestras propias plantillas. Las plantillas personalizadas deben situarse dentro de la carpeta View de nuestro plugin en una nueva carpeta que denominaremos Email. El nombre del archivo debe llevar las extensiones .html.twig.

Las plantillas pueden llevar variables o macros que son substituidas por su valor en el momento de renderizar la plantilla. Estas variables deben estar definidas entre doble corchete [[xxx]]. Ejemplo de plantilla con variables: title, company, body, footer

<!DOCTYPE html>
<html>
        <head>
                <title>[[title]]</title>
                <meta charset="UTF-8">
                <meta name="viewport" content="width=device-width, initial-scale=1.0">
        </head>
        <body>
                <h3 class="text-center">[[company]]</h3>
                <div class="container">[[body]]</div>
                <p class="text-center">[[footer]]</p>
        </body>
</html>

Al usar el componente Twig las plantillas también pueden utilizar la programación propias de este sistema, el sistema de traducción integrado en FacturaScripts y así como una lista de objetos personalizados informados por el desarrollador en la llamada (ver más adelante).

<body>
        <h3 class="text-center">[[company]]</h3>
        <p>{{ i18n.trans('my-company-info-header') }}</p>
        <div class="container">[[body]]</div>
        <p class="text-center">[[footer]]</p>
        <p>{{ i18n.trans('my-company-info-footer') }}</p>
</body>

Cómo mandar un mail

Existen dos métodos para crear y mandar un mail:

el método estático sendMail que realiza todo el proceso de manera automática en base a los parámetros informados
crear una instancia de EmailTools, configurarla y finalmente mandarlo con el método público send.

sendMail

Este método ayuda a envíar un correo de manera totalmente automática simplemente informando el parámetro data, que es un array que contiene la configuración a utilizar en base a las claves y valores:

subject: (string) Asunto o título del correo. (requerido)
body: (string) Texto que conforma el mensaje. Puede ser código html. (requerido si no se informa una plantilla)
email: (string) Lista de cuentas de correo destinatarias, separada por comas. (requerido)
email-cc: (string) Lista de cuentas de correo donde se mandará una copia de cortesía del correo.
email-bcc: (string) Lista de cuentas de correo donde se mandará una copia de manera oculta del correo.
files: (string|array) Ruta y nombre de un archivo o lista de archivos que se adjuntarán al correo.
template: (string) Plantilla Twig con la que diseñar el correo.
template-data: (array) Lista de valores a usar en la plantilla. Ejemplo: [ 'mydate' => '01/01/2019', 'myvalue' => 'custom value' ].
template-object: (array) Lista de objetos que se "pasarán" a la plantilla. Estos objetos estarán disponibles en la plantilla Twig. Ejemplo: [ 'fsc' => $this, 'company' => $company ].

send (manualmente)

Este método nos permite realizar el envío de manera manual, configurando nosotros cada uno de los pasos en la creación y envío del correo. Los pasos a seguir son:

Crear un objeto EmailTools
Obtener un objeto mail (PHPMailer)
Configurar el mail

3.1 Establecer el asunto del mail 3.2 Asignar la lista de correos a donde enviar el mail 3.3 Asignar, si lo hay, los archivos adjuntos 3.4 Generar el mensaje del correo en base a una plantilla. Si no se indica plantilla se usa la estandar de FacturaScripts.

Enviar el mail
Si hay archivos adjuntos, eliminar los archivos temporales

Ejemplo:

 /// Prepare email object
 $emailTools = new EmailTools();
 $mail = $emailTools->newMail();
 $mail->Subject = 'This is a example of manual mail';

 /// Set email list
 $emailTools->addEmails($mail, 'myaccount@my-server.com', 'onecopy@to-you.com', '');

 /// Set attachment files
 $emailTools->addAttachment($mail, 'my-file.doc');

 /// Load template and set data.
 $body = $emailTools->getTemplateHtml(['company' => 'My Company']);
 $mail->msgHTML($body);

 /// Send Email
 $emailTools->send($mail);

 /// Remove upload files
 if (!empty('my-file.doc') && file_exists(FS_FOLDER . '/MyFiles/' . 'my-file.doc'])) {
         unlink(FS_FOLDER . '/MyFiles/' . 'my-file.doc']);
 }

Métodos disponibles

addAttachment

Adjunta un archivo o una lista de archivos al correo informado. Los parámetros son:

mail: (PHPMailer) Puntero al objeto mail encargado del envío.
files: (string|array) Nombre del archivo o lista de nombres de archivos.

addEmails

Añade una dirección de correo o una lista de direcciones (destinatarios) al mail informado. Las listas de direcciones son una relacion de direcciones separadas por una coma entre ellas. Los parámetros son:

mail: (PHPMailer) Puntero al objeto mail encargado del envío.
emails: (string) Dirección de correo o lista de direcciones.
emailsCC: (string) Dirección de correo o lista de direcciones con copia de cortesía.
emailsBCC: (string) Dirección de correo o lista de direcciones con copia oculta.

getTemplateHtml

Genera y devuelve el mensaje a enviar en formato html. Para crear el mensaje utiliza una plantilla Twig.

params: (array) Lista de claves y valores que se aplican a la plantilla. Cada clave se corresponde al nombre de una variable definida en la plantilla. El valor es el valor con el que se reemplazará la variable.
template: (string) Nombre de la plantilla Twig a utilizar.
objects: (array) Lista de claves y valores que se pasan a la plantilla. Cada clave se corresponde al nombre de una variable que se podrá usar en plantilla. El valor es el la dirección al objeto que se corresponderá al usar la variable.

newMail

Crea y nos retorna un objeto PHPMailer configurado con los datos de conexión informados en las preferencia de la aplicación con el que podemos enviar un correo electrónico.

send

Envía el correo electrónico indicado en la llamada y nos retorna si se ha completado correctamente o no el envío.

test

Nos permite realizar una conexión con nuestro servidor de correo para comprobar si los datos de configuración del mail son correctos.

Índice

Amplía tus conocimientos con los cursos oficiales

Curso de usuario

Con este curso aprenderás a gestionar el día a día de tu negocio con FacturaScripts: hacer facturas, albaranes, pedidos, presupuestos, gestionar clientes, proveedores, tarifas, usuarios, además de usar el informe de impuestos. ¿A quién va dirigido? A cualquier usuario que quiera aprender rápidamente el manejo diario del programa.

423

0,00 €

Curso básico de PHP

¡Aprende a programar en PHP de manera fácil y divertida con nuestro curso básico! En este curso, te enseñaremos los conceptos fundamentales de la programación en PHP, incluyendo la sintaxis básica, el manejo de variables, estructuras de control de flujo y mucho más. Al terminar estarás listo para comenzar con el curso de creación de plugins para FacturaScripts.

5,00 €

Curso de Documentos Recurrentes

Aprenderás a crear y configurar documentos recurrentes en FacturaScripts, definir sus líneas y periodicidad, generar documentos manual y automáticamente, enviarlos por correo electrónico y trabajar con plantillas individuales o grupos recurrentes según las necesidades de cada cliente. También conocerás las opciones de importación y exportación mediante CSV para gestionar grandes volúmenes de recurrencias de forma más cómoda. El curso está dirigido a usuarios de FacturaScripts que quieran automatizar tareas administrativas repetitivas relacionadas con presupuestos, pedidos, albaranes o facturas periódicas, y especialmente a quienes ya han adquirido el plugin Documentos Recurrentes y quieren sacarle el máximo partido desde el primer momento, sin necesidad de conocimientos de programación.

9,99 €

Curso de Recursos Humanos para empleados

Este curso está dirigido a trabajadores de empresas que utilizan Recursos Humanos para registrar su jornada y consultar información relacionada con su trabajo. No necesitas conocimientos previos de FacturaScripts. Vamos a centrarnos en las funciones que puedes utilizar como empleado, sin entrar en la configuración ni en las tareas administrativas de la empresa. A lo largo del curso conocerás las distintas formas de fichar y de acceder a tu información personal. Veremos las distintas maneras que la empresa puede tener para registrar las entradas y las salidas, pudiendo en algunos casos registrar ausencias justificadas. También aprenderás cómo solicitar vacaciones, consultar tus documentos y revisar los vales o anticipos que tengas registrados, si tu empresa utiliza esas funciones. Al completar el curso, sabrás utilizar estas herramientas en tu día a día facilitándote la vida laboral.

5,00 €

Curso de ProductoPack

¿Sueles añadir los mismos productos o servicios cada vez que preparas un presupuesto, un pedido o una factura en FacturaScripts? Con ProductoPack puedes preparar esas combinaciones una sola vez y reutilizarlas mediante una referencia. En este curso aprenderás a crear y utilizar Packs, decidir cómo se muestran sus componentes en los documentos y elegir si el precio lo defines para el conjunto o se calcula a partir de los productos incluidos. También descubrirás cómo utilizar un Pack como plantilla de líneas y cuándo conviene trabajar con una Caja, que se vende y controla en stock como un producto propio. Al terminar, sabrás configurar ProductoPack para tus casos habituales, ahorrar la introducción repetitiva de líneas y elegir la modalidad adecuada para cada operación.

5,00 €

Curso de Amortizaciones

Aprende a gestionar los inmovilizados de tu empresa y los préstamos bancarios con el plugin Amortizaciones para FacturaScripts, simplificando los cálculos, el seguimiento de importes pendientes y la generación de asientos contables. En este curso práctico aprenderás a crear y configurar inmovilizados, generar planes de amortización y contabilizar sus periodos. Trabajaremos con ejemplos habituales, como equipos informáticos, instalaciones, licencias de software y vehículos comerciales. También descubrirás cómo modificar planes existentes, continuar amortizaciones procedentes de otros programas y gestionar la venta o baja de un inmovilizado. Además, aprenderás a gestionar préstamos bancarios, calcular sus cuotas mediante el sistema francés y contabilizar por separado el capital y los intereses. Un curso de 8 capítulos, pensado para usuarios de FacturaScripts, con ejemplos paso a paso que te permitirán aprovechar las funcionalidades del plugin y gestionar tus amortizaciones de forma más sencilla y organizada.

8,99 €