blastula v0.3
Want to share your content on R-bloggers? click here if you have a blog, or here if you don't.
The newest release of the blastula package lets you to do amazing things with HTML email in R and RStudio Connect. You can install blastula 0.3 from CRAN with:
install.packages("blastula")
This is a huge release! There are so many new and improved features we won’t be able to get through all of them here. Let’s focus on just two: R Markdown report emailing and improved HTML emailing using SMTP.
R Markdown Report Emailing via RStudio Connect
The capability to email a rendered R Markdown document in RStudio Connect has been available for well over a year. What would happen is that the report would be in the form of an attachment and message portion of the email would be prepared largely by RStudio Connect. With blastula v0.3, we can now create an email message body directly with R Markdown. Moreover, we can have a ‘main’ report for RStudio Connect viewers (with all of the details) and an ‘email’ version of the report that contains only the necessary elements for the purposes of email.
Static elements like ggplots and images can be part of the R Markdown email. The contents are faithfully converted to an HTML email message body that is fully responsive, so it’ll look great on both larger displays and on mobile devices. We went to great lengths to test and ensure that received emails display without problems on dozens of email clients.
If you thought that emailing R Markdown reports from RStudio Connect was a bit more difficult than should be, you’ll like this next part. There is now an easier-to-use methodology for associating an email to a published R Markdown report. The function prepare_rsc_example_files() is included to generate a set of example files relevant to R Markdown emailing in RStudio Connect. It provides a working example of a main .Rmd document, an email .Rmd document, and a CSV file that can be included as an attachment (any files generated from the main .Rmd document can also be attached). Documentation that explains how these documents interact, which blastula functions are used, and how to publish to RSC, is available in the internal documentation for the attach_connect_email() function. An updated support document in the official RStudio Connect documentation is forthcoming.
I’m pretty sure that RStudio Connect users and the recipients of these emails will love the changes implemented here. Expect further improvements to R Markdown emailing via RStudio Connect in future releases of blastula.
Improved HTML Emailing Using SMTP
RStudio Connect isn’t the only way to send emails with blastula. We can opt to send our own custom emails through an SMTP server we have access to (e.g., Gmail, Outlook, etc.). These are HTML emails that are, again, responsive to display size and have been well tested on dozens of email clients. Let’s quickly look at three things that have changed for the better with regard to email composition and SMTP sending.
Revised message composition with improved security
Previously, text interpolation features from the glue package were built into the compose_email() function. This means we could have used the string "The date and time of sending is {Sys.time()}." directly as input to, say, the message footer. Having the potential for R evaluation in strings invites security risks, so, this is no longer possible. Instead, we can simply opt to use glue::glue() ourselves or paste(). When there is any Markdown or HTML element, the md() function is required. Here is an example of a simple message that uses Markdown:
email <-
compose_email(
body = md(
"
## Hello!
This is an email message that was generated by the blastula package.
Yep, we can use **Markdown** formatting but be sure to use the `md()` function.
Here is a link to a great song ([E-MAIL ME!](https://youtu.be/-FcJbEg3vX8)).
Cheers,
The blastula team
"),
footer = md(
"
sent via the [blastula](https://rich-iannone.github.io/blastula) R package
")
)
We can always preview the email object in the RStudio Viewer while getting the composition just right. For more details on email message composition with compose_email(), have a look at the Simple Email Composition article on the project website.
No external software to install for SMTP sending
In the few years that blastula has been available, it relied on various pieces of external software for sending email. Not anymore. This release favors the creation of an RFC-2822 email body, sending through the excellent curl package. This all means that emails can now be sent dependably with the smtp_send() function on all the major platforms with no up-front installation of a third-party binary.
Improved credentials handling
The package now ships with functions for setting up and retrieving SMTP configuration and credentials information. We can set this in the system-wide key-value store with create_smtp_creds_key(). With such a key added, the credentials helper creds_key() can be used when sending email through smtp_send(). Alternatively, a credentials file can be created using the create_smtp_creds_file() function (retrieved with the creds_file() credentials helper). Lastly, credentials can be fully specified at the time of sending with the creds() function. Whenever a password is needed for setup, a prompt will appear for password entry and the password text will be obscured.
More!
Other quality-of-life improvements include automatic image embedding (via Base64 encoding) from the use of the add_image() and add_ggplot() functions when used in conjunction with compose_email(). There’s the option for automatic image deployment and retrieval of the external image tag through the add_imgur_image() function. Finally, there is a new set of block_*() functions that help us compose emails with more complex layouts.
Wrapping Up
I hope that you try out the new release of the blastula package. So many useful things can be created with R and having the means to deliver our findings through email is super satisfying both for the sender and the recipient.
La nouvelle version du package blastula vous permet de faire des choses sympas avec les e-mails HTML dans R et RStudio Connect. Installez blastula 0.3 de CRAN avec:
install.packages("blastula")
C’est une énorme sortie et donc il y a beaucoup de nouvelles choses… Je ne pense pas qu’il y ait assez de temps pour parler de tout ici. Mais ça va, regardons deux choses: envoyer des rapports par e-mail avec R Markdown et des e-mails HTML améliorés (via un serveur SMTP).
Emailing R Markdown Rapports avec RStudio Connect
La possibilité d’envoyer un document R Markdown rendu par e-mail est disponible depuis longtemps (dans RStudio Connect). Mais c’était en pièce jointe (un peu décevant). Avec le nouveau package blastula, nous pouvons désormais créer un e-mail entièrement avec R Markdown (le contenu va directement dans l’e-mail). De plus, nous pouvons avoir un rapport «principal» pour les téléspectateurs RStudio Connect (avec tous les détails) et une version «e-mail» du rapport qui contient uniquement les éléments nécessaires aux fins de l’e-mail. Ah… beaucoup mieux!
Les éléments statiques tels que ggplots et les images peuvent faire partie de l’e-mail R Markdown. Le contenu est converti en un corps de message électronique HTML qui a fière allure sur les grands écrans et sur les téléphones cellulaires. Nous avons fait de grands efforts pour tester tout cela. Cela impliquait de consulter les e-mails de nombreux clients de messagerie.
L’envoi de rapports R Markdown par RStudio Connect a été un peu difficile. Il est désormais plus facile d’associer un e-mail à un rapport R Markdown publié. La fonction prepare_rsc_example_files() peut être utilisée pour générer un ensemble d’exemples de fichiers. Ces fichiers montrent comment effectuer des e-mails R Markdown dans RStudio Connect. Les fichiers incluent un document .Rmd principal, un document .Rmd de courrier électronique et un fichier CSV qui peut être inclus en tant que pièce jointe. Pourquoi le CSV? Parce que tous les fichiers générés à partir du document principal .Rmd peuvent également être joints! La documentation qui explique comment ces documents interagissent, quelles fonctions blastula sont utilisées et comment publier sur RSC, est disponible dans la documentation interne de la fonction attach_connect_email().
Ouais. Je suis certain que les utilisateurs de RStudio Connect et les destinataires de ces e-mails adoreront les changements mis en œuvre ici. Nous apporterons plus de modifications aux e-mails R Markdown via RStudio Connect dans les prochaines versions de blastula.
Emailing HTML amélioré à l’aide de SMTP
RStudio Connect n’est pas le seul moyen d’envoyer des e-mails avec blastula. Nous pouvons envoyer des e-mails via un serveur SMTP auquel nous avons accès (par exemple, Gmail, Outlook, etc.). Voyons rapidement trois choses qui se sont améliorées en ce qui concerne la composition des e-mails et l’envoi SMTP.
Composition des messages révisée avec plus de sécurité
Auparavant, les fonctions d’interpolation de texte du package glue étaient intégrées à la fonction compose_email(). Cela signifie que nous aurions pu utiliser la déclaration "The date and time of sending is {Sys.time()}." Directement comme entrée dans, disons, le pied de page du message. Le fait d’avoir le potentiel d’évaluation R dans les chaînes entraîne des risques de sécurité, ce n’est donc plus possible. Au lieu de cela, nous pouvons simplement choisir d’utiliser glue::glue() nous-mêmes ou paste(). Lorsqu’il y a un élément Markdown ou HTML, la fonction md() est requise. Voici un exemple de message simple qui utilise Markdown (c’est en anglais):
email <-
compose_email(
body = md(
"
## Hello!
This is an email message that was generated by the blastula package.
Yep, we can use **Markdown** formatting but be sure to use the `md()` function.
Here is a link to a great song ([E-MAIL ME!](https://youtu.be/-FcJbEg3vX8)).
Cheers,
The blastula team
"),
footer = md(
"
sent via the [blastula](https://rich-iannone.github.io/blastula) R package
")
)
Nous pouvons toujours prévisualiser l’objet email dans la RStudio Viewer tout en obtenant la composition parfaite. Pour plus de détails sur la composition des e-mails avec compose_email(), consultez l’article Simple Email Composition sur le site web du projet.
Aucun logiciel externe n’est nécessaire pour envoyer des e-mails avec SMTP
Au cours des quelques années où blastula a été disponible, il s’est appuyé sur divers logiciels externes pour envoyer des e-mails. Ce n’est plus vrai. Nous créons maintenant un corps d’e-mail RFC-2822 et envoyons des e-mails avec une fonction du package curl. Désormais, les e-mails peuvent désormais être envoyés de manière fiable avec la fonction smtp_send() sur toutes les principales plates-formes informatiques sans aucune dépendance difficile à installer.
Amélioration de la gestion des informations d’identification
Le package possède désormais des fonctions de configuration et de récupération des informations de configuration et d’informations d’identification SMTP. Nous pouvons configurer cela avec create_smtp_creds_key(). Avec une telle clé ajoutée, l’aide aux informations d’identification creds_key() peut être utilisée lors de l’envoi d’e-mails via smtp_send(). Alternativement, un fichier d’informations d’identification peut être créé en utilisant la fonction create_smtp_creds_file() (récupérée avec creds_file()). Enfin, les informations d’identification peuvent être entièrement spécifiées au moment de l’envoi avec la fonction creds(). Chaque fois qu’un mot de passe est nécessaire, une invite apparaîtra pour la saisie du mot de passe (le texte du mot de passe sera masqué).
Il y a encore plus!
D’autres changements incluent l’intégration automatique d’images (via l’encodage Base64) à partir de l’utilisation des fonctions add_image() et add_ggplot() lorsqu’elles sont utilisées avec compose_email(). La fonction add_imgur_image() facilite l’utilisation d’images externes dans les e-mails. Enfin, il existe un nouvel ensemble de fonctions block_*() qui nous aident à composer des e-mails avec des mises en page plus complexes.
Conclusion
J’espère que vous essayez la nouvelle version du package blastula. Nous pouvons créer des choses utiles avec R et avoir les moyens de livrer nos résultats par e-mail est super cool pour l’expéditeur et le destinataire.
Mit der neuen Version des blastula-Pakets können Sie in R und RStudio Connect coole Dinge mit HTML-E-Mails tun. Installieren Sie CRAN blastula 0.3 mit:
install.packages("blastula")
Dies ist ein ziemlich umfangreiches Software-Upgrade! Es gibt so viele neue und verbesserte Funktionen, dass wir sie hier nicht alle durcharbeiten können. Schauen wir uns zwei neue Themen an: R Markdown Bericht-E-Mail und verbessertes HTML-E-Mail mit SMTP.
R Markdown E-Mail-Berichte mit RStudio Connect
Die Möglichkeit, ein per E-Mail gesendetes R Markdown-Dokument zu senden, ist seit langem verfügbar (in RStudio Connect). Aber es war anhaftend (etwas enttäuschend). Mit dem neuen Blastula-Paket können wir jetzt eine E-Mail komplett mit R Markdown erstellen (der Inhalt geht direkt in die E-Mail). Außerdem können wir einen “Haupt”-Report für die Zuschauer RStudio Connect (mit allen Details) und eine “E-Mail”-Version des Berichts haben, die nur die für die Zwecke der E-Mail erforderlichen Elemente enthält. Viel besser!
Statische Elemente wie ggplots und Bilder können Teil der R Markdown-E-Mail sein. Der Inhalt wird in einen HTML-Nachrichtentext konvertiert, der auf große Desktop-Displays und Handys großartig aussieht. Wir haben große Anstrengungen unternommen, um all dies zu testen. Dies beinhaltete das Betrachten der E-Mails vieler E-Mail-Clients.
Es war ein bisschen schwierig, R Markdown von RStudio Connect zu melden. Es ist jetzt einfacher, eine E-Mail mit einem veröffentlichten R Markdown-Report zu verknüpfen. Die Funktion prepare_rsc_example_files() kann verwendet werden, um einen Satz von Beispieldateien zu generieren. Diese Dateien zeigen, wie R Markdown-E-Mails in RStudio Connect erstellt werden. Die Dateien enthalten ein Haupt-RMD-Dokument, ein RMD-E-Mail-Dokument und eine CSV-Datei, die als Anhang beigefügt werden kann. Warum die CSV? Denn alle Dateien, die aus dem Hauptdokument .Rmd generiert wurden, können auch angehängt werden! Die Dokumentation, die erklärt, wie diese Dokumente interagieren, welche blastula-Funktionen verwendet werden und wie sie in RSC veröffentlicht werden, finden Sie in der internen Dokumentation der Funktion attach_connect_email().
Ja. Ich bin sicher, dass RStudio Connect-Nutzer und -Empfänger dieser E-Mails die hier vorgenommenen Änderungen lieben werden. In zukünftigen Versionen von blastula werden wir weitere Änderungen an R Markdown-E-Mails über RStudio Connect vornehmen.
Erweitertes HTML-E-Mailing über SMTP
RStudio Connect ist nicht die einzige Möglichkeit, E-Mails mit blastula zu versenden. Wir können E-Mails über einen SMTP-Server senden, auf den wir Zugriff haben (z. B. Google Mail, Outlook usw.). Schauen wir uns kurz drei Dinge an, die sich in Bezug auf die E-Mail-Zusammensetzung und den SMTP-Versand verbessert haben.
Überarbeitete Nachrichtenkomposition mit mehr Sicherheit
Zuvor waren die Textinterpolationsfunktionen des glue-Pakets in die Funktion compose_email() integriert. Dies bedeutet, dass wir die Anweisung "The date and time of sending is {Sys.time()}." Direkt als Eintrag beispielsweise in der Fußzeile der Nachricht verwendet haben könnten. Das Potential zur Bewertung R in den Ketten zu haben, führt zu Sicherheitsrisiken, so dass dies nicht mehr möglich ist. Stattdessen können wir uns einfach dafür entscheiden, glue::glue() oder paste() zu verwenden. Wenn ein Markdown- oder HTML-Element vorhanden ist, ist die Funktion md() erforderlich. Hier ist ein Beispiel für eine einfache Nachricht, die Markdown verwendet:
email <-
compose_email(
body = md(
"
## Hello!
This is an email message that was generated by the blastula package.
Yep, we can use **Markdown** formatting but be sure to use the `md()` function.
Here is a link to a great song ([E-MAIL ME!](https://youtu.be/-FcJbEg3vX8)).
Cheers,
The blastula team
"),
footer = md(
"
sent via the [blastula](https://rich-iannone.github.io/blastula) R package
")
)
Wir können weiterhin eine Vorschau des E-Mail-Objekts im RStudio Viewer anzeigen, um die perfekte Komposition zu erhalten. Weitere Informationen zum Verfassen von E-Mails mit compose_email() finden Sie im Artikel Simple Email Composition auf der Projektwebsite.
Zum Versenden von E-Mails mit SMTP ist keine externe Software erforderlich
In den wenigen Jahren, in denen blastula verfügbar war, stützte er sich zum Versenden von E-Mails auf verschiedene externe Software. Das stimmt nicht mehr. Wir erstellen jetzt einen RFC-2822-E-Mail-Body und senden E-Mails mit einer curl-Paketfunktion. Jetzt können E-Mails mit der Funktion smtp_send() zuverlässig auf allen wichtigen Computerplattformen ohne schwer zu installierende Abhängigkeiten gesendet werden.
Verbesserte Berechtigungsnachweisverwaltung
Das Paket verfügt jetzt über Funktionen zum Konfigurieren und Abrufen von Konfigurationsinformationen und SMTP-Anmeldeinformationen. Wir können dies mit create_smtp_creds_key() konfigurieren. Mit einem solchen hinzugefügten Schlüssel kann die creds_key()-Hilfe zum Versenden von E-Mails über smtp_send() verwendet werden. Alternativ kann eine Berechtigungsnachweisdatei mit der Funktion create_smtp_creds_file() erstellt werden (abgerufen mit creds_file()). Schließlich können die Anmeldeinformationen zum Zeitpunkt des Sendens mit der Funktion creds() vollständig angegeben werden. Immer wenn ein Passwort erforderlich ist, erscheint eine Aufforderung zur Eingabe des Passworts (der Passworttext wird ausgeblendet).
Es gibt noch mehr!
Andere Änderungen umfassen die automatische Bildintegration (über Base64-Codierung) durch die Verwendung der Funktionen add_image() und add_ggplot(), wenn sie mit compose_email() verwendet werden. Die Funktion add_imgur_image() erleichtert die Verwendung externer Bilder in E-Mails. Schließlich gibt es eine neue Reihe von block_*()-Funktionen, mit denen wir E-Mails mit komplexeren Layouts erstellen können.
Die Zukunft ist da
Ich hoffe aufrichtig, dass Sie die neue Version des blastula-Pakets testen. Mit R können wir so viele nützliche Dinge erschaffen. Die Möglichkeit, unsere Ergebnisse per E-Mail zu übermitteln, ist für den Absender und den Empfänger eine absolute Freude.
R-bloggers.com offers daily e-mail updates about R news and tutorials about learning R and many other topics. Click here if you're looking to post or find an R/data-science job.
Want to share your content on R-bloggers? click here if you have a blog, or here if you don't.