Jump to content
FireWire

Fluency - Integrated DeepL Powered Content Translation

Recommended Posts

Hello community!

I want to share a new module I've been working on that I think could be a big boost for multi-language ProcessWire sites.

Some background, I was looking for a way for our company website to be efficiently translated as working with human translators was pretty laborious and a lack of updating content created a divergence between languages. I, and several other devs here, have talked about translation integrations and have recognized the power that DeepL has. DeepL is an AI deep learning powered service that delivers translation quality beyond any automated service available. After access to the API was opened up to the US, I built Fluency, a DeepL translation integration for ProcessWire.

Fluency brings automated translation to every multi-language field in the admin, and also provides a translation tool allowing the user to translate their text to any language without it being inside a template's field. With Fluency you can:

  • Translate any plain textarea or text input
  • Translate any CKEditor content (yes, with markup)
  • Translate page names for fully localized URLs on every page
  • Translate your in-template translation function wrapped strings
  • Translate modules

DeepL offers translations to the following languages: English (US), English (UK), German, French, Spanish, Portuguese (EU), Portuguese (Brazil, Italian, Dutch, Polish, Russian, Japanese, Chinese (Simplified)

Installation and usage is completely plug and play. Whether you're building a new multi-language site, need to update a site to multi-language, or simply want to stop manually translating a site and make any language a one-click deal, it could not be easier to do it. Fluency works by having you match the languages configured in ProcessWIre to DeepL's. You can have your site translating to any or all of the languages DeepL translates to in minutes (quite literally).

Let's break out the screenshots...
When the default language tab is shown, a message is displayed to let users know that translation is available. Clicking on each tab shows a link that says "Translate from English". Clicking it shows an animated overlay with the word "Translating..." cycling through each language and a light gradient shift. Have a CKEditor field? All good. Fluency will translated it and use DeepL's ability to translate text within HTML tags. CKEditor fields can be translated as easily and accurately as text/textarea fields.

input_fields.thumb.jpg.9337edf798b103053e744fffed460b90.jpg

Repeaters and AJAX created fields also have translation enabled thanks to a JavaScript MutationObserver that searches for multi-language fields and adds translation as they're inserted into the DOM. If there's a multi-language field on the page, it will have translation added.

fluency_repeater.thumb.jpg.879cbf180c7e9714798b736e1db612f4.jpg

Same goes for image description fields. Multi-language SEO friendly images are good to go.

fluently_image_description.thumb.jpg.03269127f3d10f64a9b67d567cbdb765.jpg

Creating a new page from one of your templates? Translate your title, and also translate your page name for native language URLs. (Not available for Russian, Chinese, or Japanese languages due to URL limitations). These can be changed in the "Settings" tab for any page as well so whether you're translating new pages or existing pages, you control the URLs everywhere.

fluency_new_page.thumb.jpg.b3b649fd3087bf2c0cc565c60fed733c.jpg

Language configuration pages are no different. Translate the names of your languages and search for both Site Translation Files (including all of your modules)

fluency_language_page.thumb.jpg.63e41f268eecf2f3f3742325a3fbc5b1.jpg

Translate all of the static text in your templates as well. Notice that the placeholders are retained. DeepL is pretty good at recognizing and keeping non-translatable strings like that. If it is changed, it's easy to fix manually.

fluency_template_translation.thumb.jpg.38093371850fcb9011e9b7d668a79680.jpg

Fluency adds a "Translate" item to the CMS header. When clicked this opens up a modal with a full translation tool that lets the user translate any language to any language. No need to leave the admin if you need to translate content from a secondary language back to the default ProcessWire language. There is also a button to get the current API usage statistics. DeepL account owners can set billing limitations via character count to control costs. This may help larger sites or sites being retrofitted keep an eye on their usage. Fluency can be used by users having roles given the fluency-translate permission.

fluency_translation_tool.thumb.jpg.e69dcca7351659306731f8fffa084a20.jpg

It couldn't be easier to add Fluency to your new or existing website. Simply add your API key and you're shown what languages are currently available for translation from/to as provided by DeepL. This list and all configuration options are taken live from the API so when DeepL releases new languages you can add them to your site without any work. No module updates, just an easy configuration. Just match the language you configured in ProcessWire to the DeepL language you want it to be associated with and you're done. Fluency also allows you to create a list of words/phrases that will not be translated which can prevent items such as brands and company names from being translated when they shouldn't

fluency_config.thumb.jpg.0a0fbd7fcaefd5adda3f59ad850d708f.jpg

 

Limitations:

  • No "translate page" - Translating multiple fields can be done by clicking multiple translation links on multiple fields at once but engineering a "one click page translate" is not feasible from a user experience standpoint. The time it takes to translate one field can be a second or two, but cumulatively that may take much longer (CKEditor fields are slower than plain text fields). There may be a workaround in the future but it isn't currently on the roadmap.
  • No "translate site" - Same thing goes for translating an entire website at once. It would be great, but it would be a very intense process and take a very (very) long time. There may be a workaround in the future but it isn't on the roadmap.
  • No current support for Inline CKEditor fields - Handling for CKEditor on-demand hasn't been implemented yet, this is planned for a future release though and can be done. I just forgot about it because I've never really used that feature personally..
  • Alpha release - This module is in alpha. Releases should be stable and usable, but there may be edge case issues. Test the module thoroughly and please report any bugs via a Gitlab issue on the repository or respond here.

Please note that the browser plugin for Grammarly conflicts with Fluency (as it does with many web applications). To address this issue it is recommended that you disable Grammarly when using Fluency, or open the admin to edit pages in a private window where Grammarly may not be loaded. This is an issue that may not have a resolution as creating a workaround may not be possible. If you have insight as to how this may be solved please visit the Gitlab page and file a bugfix ticket.

Requirements:

  • ProcessWire  3.0+
  • UIKit Admin Theme

That's Fluency in a nutshell. A core effort in this module is to create it so that there is nothing DeepL related hard-coded in that would require updating it when DeepL offers new languages. I would like this to be a future-friendly module that doesn't require developer work to keep it up-to-date.

It's Free
This is my first real module and I want to give it back to the community as thanks. This is the best CMS I've worked with (thank you Ryan & contributors) and a great community (thank you dear reader). The only cost to use this is a subscription fee for the DeepL Pro API. Find out more and sign up here.

Download & Feedback
Download the latest version here
https://github.com/SkyLundy/Fluency-Translation/archive/main.zip

Github repository:
https://github.com/SkyLundy/Fluency-Translation

File issues and feature requests here (your feedback and testing is greatly appreciated):
https://github.com/SkyLundy/Fluency-Translation/issues

 

Thank you! ¡Gracias! Ich danke Ihnen! Merci! Obrigado! Grazie! Dank u wel! Dziękuję! Спасибо! ありがとうございます! 谢谢你!

fluency_results.jpg

  • Like 24
  • Thanks 11

Share this post


Link to post
Share on other sites

This looks amazing. Thanks for your hard work and generosity. 

  • Like 1

Share this post


Link to post
Share on other sites

This looks amazing!! Thank you for your hard work and generosity! Super contribution to ProcessWire!

  • Like 1

Share this post


Link to post
Share on other sites
9 hours ago, bartelsmedia said:

Dreams come true! You should put up a donation link.

There's a link for that in the module config page. Was hidden in the screenshot for simplicity.

  • Like 1

Share this post


Link to post
Share on other sites

For one of the latest website I did, the client asked if there could be an integration of some sort with DeepL since they were using it for translation. And now your amazing contribution is out ! It looks great and I might use it for the next project with this client next year.

Thank you !

  • Like 1

Share this post


Link to post
Share on other sites
2 hours ago, monollonom said:

For one of the latest website I did, the client asked if there could be an integration of some sort with DeepL since they were using it for translation. And now your amazing contribution is out ! It looks great and I might use it for the next project with this client next year.

Thank you !

That's excellent to hear! Glad it came in time. I'm going to be launching a site that uses it in the next few weeks as it is stable and useful right now. It should have more features and time in production by the time you use it! If you get any time to play around with it or use it in the meantime I would love to hear feedback and any bugs you find. Cheers!

  • Like 1

Share this post


Link to post
Share on other sites

I'm continuing work on this module as it gets more time in use and any edge case issues pop up. I'm going to be working on fast iterations while in alpha to address problems quickly so the module can get to a formal release. If you download and test/use the module please submit any issues via the Gitlab repo so it's on my radar. Be sure to check for newer versions on the master branch to get the latest stable version. The next push to master will contain a changelog so early users can track changes and decide if a module upgrade is needed. Thanks again to those who are able to help!

Here's the link to the repo: https://gitlab.com/SkyLundy/fluency-processwire

 

  • Like 1

Share this post


Link to post
Share on other sites

0.2.0 is now working fine. Thank you so much. One cosmetic/minor suggestion: Could you move the "translate" link from underneath the content box to above the box? It would dramatically help to minimize scrolling back and forth:

move.thumb.png.7e2a67eed151365794a9f3a693cf8721.png

Share this post


Link to post
Share on other sites

It is easy to translate from the default language to other languages but it doesn't seem to be possible to start with a secondary language and translate that into the primary language. Or am I wrong?

 

Share this post


Link to post
Share on other sites
2 minutes ago, bartelsmedia said:

It is easy to translate from the default language to other languages but it doesn't seem to be possible to start with a secondary language and translate that into the primary language. Or am I wrong?

 

Yes, that is a limitation in the on-page UI. Initial goal is to keep it simple for the user to translate from the primary language with a one click operation rather than needing a select input to choose the source language.

I prioritized the translation tool in the menu at the top is to translate content from any language to any language just in case that becomes something that is needed. That was the goal of making the link a modal so that tool can be used anywhere there has to be content translated from any language to any language without leaving the page or tab-hopping.

 

17 minutes ago, bartelsmedia said:

0.2.0 is now working fine. Thank you so much. One cosmetic/minor suggestion: Could you move the "translate" link from underneath the content box to above the box? It would dramatically help to minimize scrolling back and forth:

move.thumb.png.7e2a67eed151365794a9f3a693cf8721.png

I had the same thought but was concerned about having it stack up against the language tabs if there were too many of them or if the screen was smaller (like in the screenshots in the original post). I could try experimenting with the translation trigger placement in the future but it would be sometime after localizing the UI so more people can use the module.

Share this post


Link to post
Share on other sites

Can you hack into the Processwire language tabs and add a drop-down "Translate from language..."?! This would probably be the most flexible UI option.

Share this post


Link to post
Share on other sites
7 minutes ago, bartelsmedia said:

Can you hack into the Processwire language tabs and add a drop-down "Translate from language..."?! This would probably be the most flexible UI option.

Everything is hackable...

That would interfere with ProcessWire's existing UI where clicking on a tab that is already selected changes all of the tabs on the page to that language. I don't want the module to alter the native PW interface and take away a feature.

I may revisit the idea of translating a field to all languages at once and test it out to see if it is feasible in practice. If I can do that while being able to provide a progress bar or something then I think that would be the way to go. That would take care of the amount of work of clicking for each language, save space, reduce scrolling, etc.

Share this post


Link to post
Share on other sites

giphy.gif 

Thanks you guy for this module!

If you are willing to accept pull-requests, I will send one which give ability to translate a file (eg: docx) into a CKEditor field and another one which will support my incoming field/module EditorJS.

 

And some suggestions.

About the issue #2 (formality param), as you can know which language is or not supported, you could hardcode the six unsupported languages only.

Quote

If I can do that while being able to provide a progress bar or something then I think that would be the way to go. 

Exactly what I was going to suggest (#15). We are lazy here 😂

  • Like 1

Share this post


Link to post
Share on other sites
17 hours ago, flydev 👊🏻 said:

giphy.gif 

Thanks you guy for this module!

If you are willing to accept pull-requests, I will send one which give ability to translate a file (eg: docx) into a CKEditor field and another one which will support my incoming field/module EditorJS.

 

And some suggestions.

About the issue #2 (formality param), as you can know which language is or not supported, you could hardcode the six unsupported languages only.

Exactly what I was going to suggest (#15). We are lazy here 😂

Just doing it for the love of the code.

Really striving not to "lock in" hard definitions into the code like formality. A workaround I am thinking about is adding an ability for a developer to configure language/formality association with directions for them to review the API as a step to make it work. Believe it or not, I sent a request to DeepL to see if they have a way to query formality that isn't documented 

The module is essentially a DeepL API wrapper with a lot of the work being handled by the front-end JS. The module itself is going to go through some evolution before I can push it out for collaboration. I'll add a module method to work with files. I still need to firm up the structure of the data returned from the module's methods and then document it. It would be awesome to see this integrated in with your EditorJS module which looks super awesome!

I've got a separate repository for a CKEditor integration that I could use a help with. I set that up over the weekend but haven't really touched it. Just did some skeleton code to add the ability to highlight text and exclude it from translation but it's not even close to useful. PM me and let me know what you think.

Share this post


Link to post
Share on other sites

We were on the verge of developing such a module ourselves, but you have beaten us to it ... Thank you very much for this great work!

Unfortunately we have a problem with the integration of the translation service into text fields, because our default language is set to german, as also set in Fluency module settings. But in text fields, we can only translate englisch texts from english, instead from german. Have we done something wrong?

 

Thank you in advance,

Thomas.

settings.png

text_field.png

  • Like 1

Share this post


Link to post
Share on other sites
10 hours ago, xportde said:

We were on the verge of developing such a module ourselves, but you have beaten us to it ... Thank you very much for this great work!

Unfortunately we have a problem with the integration of the translation service into text fields, because our default language is set to german, as also set in Fluency module settings. But in text fields, we can only translate englisch texts from english, instead from german. Have we done something wrong?

 

Thank you in advance,

Thomas.

settings.png

text_field.png

Unfortunately I haven't localized the UI yet but that is the next priority item on my list. If you have your primary language set as German and the other language as English, the translation link will still say "Translate from English" but it will still translate from German to English. Right now this issue is purely aesthetic. Here's the language translating from German to English but the translate link saying the wrong text.

868413029_Screenshotfrom2020-11-1109-35-00.png.311e4b7a9ca2e4558d012ab18b451e60.png

If you would like to change these now so you don't have to wait for a module upgrade, you can update the text strings located on the following lines in these JS files:

Fluency/src/js/fluency.js
153
160
216
473
476
490

Fluency/src/js/fluency_language_translator.js
108
168

By changing the text there the module will then fit your setup. Like I mentioned above, I'm working on having this behave correctly out of the box!

Share this post


Link to post
Share on other sites

Just found out from a user that the browser plugin for Grammarly conflicts with Fluency and causes errors which prevent translations from working. Grammarly is known to cause issues with some web apps and the company seems to not be interested in working on compatibility (as an example, Grammarly has ignored requests to fix conflicts with WordPress' Gutenberg interface for years). Considering how prevalent these issues are with many sites, this isn't a priority for the module's development. Just a heads up in case this becomes an issue for you or your clients. If you have any insight on this that could help solve the issue please open a ticket on the Fluency Gitlab repo.

Share this post


Link to post
Share on other sites

Thank you for the clarification! 

 

In fact, the translations service works as expected, and the hint text is only a cosmetic issue. 

We have unfortunately discovered another problem with CKEditor fields in inline mode, where the translation is not transfered into the target field. Knowing this, we may use the regular mode for CKEditor. Maybe, it's very tricky to implement the translation service here, because the inline editor is loaded dynamically on demand.

 

Best regards,

Thomas.

Share this post


Link to post
Share on other sites

Currently, it seems that only superuser can use the translation service.  Is it possible to enable translations by permission and role? 

Share this post


Link to post
Share on other sites
9 hours ago, xportde said:

Thank you for the clarification! 

 

In fact, the translations service works as expected, and the hint text is only a cosmetic issue. 

We have unfortunately discovered another problem with CKEditor fields in inline mode, where the translation is not transfered into the target field. Knowing this, we may use the regular mode for CKEditor. Maybe, it's very tricky to implement the translation service here, because the inline editor is loaded dynamically on demand.

 

Best regards,

Thomas.

Oh I have never really used CKEditor fields in anything other than regular mode. I will update the description of the module with that information and add that to the roadmap.

9 hours ago, xportde said:

Currently, it seems that only superuser can use the translation service.  Is it possible to enable translations by permission and role? 

I added a permission to the implementation at the company I work for. I will add that to this module as well. Update should be pushed soon and I'll let you know when that is available

 

 

Share this post


Link to post
Share on other sites
11 hours ago, xportde said:

Currently, it seems that only superuser can use the translation service.  Is it possible to enable translations by permission and role? 

This has been fixed, the translation tool can be accessed by anyone with page-edit permissions, which was the original intent of the module.

Out of curiosity- do you see a need to break down access to the translator tool to a specific permission? I'm curious about that idea but didn't think there was a use case.

New version is 0.2.2 - quick link to download the latest: https://gitlab.com/SkyLundy/fluency-processwire/-/archive/master/fluency-processwire-master.zip

Share this post


Link to post
Share on other sites

@FireWire - just installed and on going to the Translation page, I get these errors:

PHP Warning: file_get_contents(/site/modules/Fluency/fluency_templates/el_h1.tpl.html): failed to open stream: No such file or directory in .../Fluency/classes/FluencyTools.class.php:31
PHP Warning: file_get_contents(/site/modules/Fluency/fluency_templates/el_p.tpl.html): failed to open stream: No such file or directory in .../Fluency/classes/FluencyTools.class.php:31

I installed via the URL to the zip file and the problem is that it resulted in two "Fluency" directories such that the path is actually:

/var/www/dev.grief.coach/site/modules/Fluency/Fluency/fluency_templates/el_p.tpl.html

Once I moved those files and did a modules > refresh it started working as expected.

  • Thanks 1

Share this post


Link to post
Share on other sites

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!

Register a new account

Sign in

Already have an account? Sign in here.

Sign In Now

  • Recently Browsing   0 members

    No registered users viewing this page.

  • Similar Content

    • By tcnet
      PageViewStatistic for ProcessWire is a module to log page visits of the CMS. The records including some basic information like IP-address, browser, operating system, requested page and originate page. Please note that this module doesn't claim to be the best or most accurate.
      Advantages
      One of the biggest advantage is that this module doesn't require any external service like Google Analytics or similar. You don't have to modify your templates either. There is also no Javascript or image required.
      Disadvantages
      There is only one disadvantage. This module doesn't record visits if the browser loads the page from its browser cache. To prevent the browser from loading the page from its cache, add the following meta tags to the header of your page:
      <meta http-equiv="Cache-Control" content="no-cache, no-store, must-revalidate" /> <meta http-equiv="Pragma" content="no-cache" /> <meta http-equiv="Expires" content="0" /> How to use
      The records can be accessed via the Setup-menu of the CMS backend. The first dropdown control changes the view mode.

      Detailed records
      View mode "Detailed records" shows all visits of the selected day individually with IP-address, browser, operating system, requested page and originate page. Click the update button to see new added records.

      Cached visitor records
      View modes other than "Detailed records" are cached visitor counts which will be collected on a daily basis from the detailed records. This procedure ensures a faster display even with a large number of data records. Another advantage is that the detailed records can be deleted while the cache remains. The cache can be updated manually or automatically in a specified time period. Multiple visits from the same IP address on the same day are counted as a single visitor.

      Upgrade from older versions
      Cached visitor counts is new in version 1.0.8. If you just upgraded from an older version you might expire a delay or even an error 500 if you display cached visitor counts. The reason for this is that the cache has to be created from the records. This can take longer if your database contains many records. Sometimes it might hit the maximally execution time. Don't worry about that and keep reloading the page until the cache is completely created.
      Special Feature
      PageViewStatistic for ProcessWire can record the time a visitor viewed the page. This feature is deactivated by default. To activate open the module configuration page and activate "Record view time". If activated you will find a new column "S." in the records which means the time of view in seconds. With every page request, a Javascript code is inserted directly after the <body> tag. Every time the visitor switches to another tab or closes the tab, this script reports the number of seconds the tab was visible. The initial page request is recorded only as a hyphen (-).

      Settings
      You can access the module settings by clicking the Configuration button at the bottom of the records page. The settings page is also available in the menu: Modules->Configure->ProcessPageViewStat.
      IP2Location
      This module uses the IP2Location database from: http://www.ip2location.com. This database is required to obtain the country from the IP address. IP2Location updates this database at the begin of every month. The settings of ProcessPageViewStat offers the ability to automatically download the database monthly. Please note, that automatically download will not work if your webspace doesn't allow allow_url_fopen.
      Dragscroll
      This module uses DragScroll. A JavaScript available from: http://github.com/asvd/dragscroll. Dragscroll adds the ability in view mode "Day" to drag the records horizontally with the mouse pointer.
      parseUserAgentStringClass
      This module uses the PHP class parseUserAgentStringClass available from: http://www.toms-world.org/blog/parseuseragentstring/. This class is required to filter out the browser type and operating system from the server request.
    • By Mike Rockett
      TextformatterTypographer
      A ProcessWire wrapper for the awesome PHP Typography class, originally authored by KINGdesk LLC and enhanced by Peter Putzer in wp-Typography. Like Smartypants, it supercharges text fields with enhanced typography and typesetting, such as smart quotations, hyphenation in 59 languages, ellipses, copyright-, trade-, and service-marks, math symbols, and more.
      It's based on the PHP-Typography library found over at wp-Typography, which is more frequently updated and feature rich that its original by KINGdesk LLC.
      The module itself is fully configurable. I haven't done extensive testing, but there is nothing complex about this, and so I only envisage a typographical bug here and there, if any.
    • By daniel_puehringer
      Hi community,

      I am using the "PageTable" Module (also called "ProFields: Page Table") and the built in "Language" Module (also called "Languages Support").

      With the help of PageTable I was able to create several content elements which should usually be displayed in German(default language) and English.

      However some Content Elements should only be shown in German and NOT in English.

      Well sounds easy, right? Not so fast. I really love this CMS, but I have not found a solution for this problem yet.
      As you can see in the screenshots attached I tried to uncheck the "active" Checkbox for the english language to completely hide the content element for english users.

      However no matter what I do the german text shows on the english page.
      If I leave the "content-should-not-be-shown-in-english"(see Screenshot Number 2) blank and save the page, the page will inherit the german page url "content-element-with-simple-text-which-should-only-be-shown-in-german".

      My question therefore is:
      How can I hide a specific content-element for only one language?

      I´m using the latest processwire & module versions.

      The code which I use to render the content elements looks like this:
      //Info: contentelements is a field of type "ProFields: Page Table" <?php foreach ($page->contentelements as $element): echo($element->render()); endforeach; ?> filename: basic-page.php


      I would really appreciate your help since I haven´t found a solution after reading through quite a lot of forum posts.

      All the best,
      Dani


    • By robert
      I often had the need for an overview of all used fields and their contents for a specific page/template while developing new websites without switching to the backend, so I made a small module which lists all the needed information in a readable manner (at least for me):
      Debug Page Fields
      https://github.com/robertweiss/ProcessDebugPageFields
      It adds two new properties to all pages:
      $page->debugFieldValues – returns an object with all (sub-)fields, their labels, fieldtypes and values $page->debugFieldTypes – returns an object with all fieldtypes and their corresponding fields // List all values of a pages $page->debugFieldValues // List a specific field $page->debugFieldValues->fieldname // List all used fieldtypes of a page $page->debugFieldTypes I recommend using it in combination with Tracy Debugger, Ray, Xdebug etc. as it returns an object and is only meant for developing/debugging uses. 
      For now, the fieldtype support includes mostly fieldtypes I use in my projects, but can easily be extended by adding a new FieldtypeFIELDNAME method to the module. I use it with five different client installations (all PW 3.0.*), but of course there might be some (or more) field configurations which are not covered correctly yet.
      Supported fieldtypes
      Button Checkbox Color Combo Datetime Email FieldsetPage * File FontIconPicker Functional Image ImageReference MapMarker Multiplier Mystique Options Page PageIDs PageTitle Radio Repeater * RepeaterMatrix * RockAwesome SeoMaestro Table Text Textarea Textareas Toggle URL * The fields with complete subfield-support also list their corresponding subfields.
      Installation
      Download the zip file at Github or clone the repo into your site/modules directory. If you downloaded the zip file, extract it in your sites/modules directory. In your admin, go to Modules > Refresh, then Modules > New, then click on the Install button for this module. As this is my first ›public‹ module, I hope I did not miss any important things to mention here.
    • By horst
      Wire Mail SMTP

      An extension to the (new) WireMail base class that uses SMTP-transport

      This module integrates EmailMessage, SMTP and SASL php-libraries from Manuel Lemos into ProcessWire. I use this continously evolved libraries for about 10 years now and there was never a reason or occasion not to do so. I use it nearly every day in my office for automated composing and sending personalized messages with attachments, requests for Disposition Notifications, etc. Also I have used it for sending personalized Bulkmails many times.

      The WireMailSmtp module extends the new email-related WireMail base class introduced in ProcessWire 2.4.1 (while this writing, the dev-branch only).
       
      Here are Ryans announcement.



      Current Version 0.6.0
      Changelog: https://github.com/horst-n/WireMailSmtp/blob/master/CHANGELOG.md
      get it from the Modules Directory Install and Configure

      Download the module into your site/modules/ directory and install it.

      In the config page you fill in settings for the SMTP server and optionaly the (default) sender, like email address, name and signature.
      You can test the smtp settings directly there. If it says "SUCCESS! SMTP settings appear to work correctly." you are ready to start using it in templates, modules or bootstrap scripts.


      Usage Examples
      The simplest way to use it:
      $numSent = wireMail($to, $from, $subject, $textBody); $numSent = wireMail($to, '', $subject, $textBody); // or with a default sender emailaddress on config page This will send a plain text message to each recipient.
       
      You may also use the object oriented style:
      $mail = wireMail(); // calling an empty wireMail() returns a wireMail object $mail->to($toEmail, $toName); $mail->from = $yourEmailaddress; // if you don't have set a default sender in config // or if you want to override that $mail->subject($subject); $mail->body($textBody); $numSent = $mail->send(); Or chained, like everywhere in ProcessWire:
      $mail = wireMail(); $numSent = $mail->to($toEmail)->subject($subject)->body($textBody)->send(); Additionaly to the basics there are more options available with WireMailSmtp. The main difference compared to the WireMail BaseClass is the sendSingle option. With it you can set only one To-Recipient but additional CC-Recipients.
      $mail = wireMail(); $mail->sendSingle(true)->to($toEmail, $toName)->cc(array('person1@example.com', 'person2@example.com', 'person3@example.com')); $numSent = $mail->subject($subject)->body($textBody)->send(); The same as function call with options array:
      $options = array( 'sendSingle' => true, 'cc' => array('person1@example.com', 'person2@example.com', 'person3@example.com') ); $numSent = wireMail($to, '', $subject, $textBody, $options); There are methods to your disposal to check if you have the right WireMail-Class and if the SMTP-settings are working:
      $mail = wireMail(); if($mail->className != 'WireMailSmtp') { // Uups, wrong WireMail-Class: do something to inform the user and quit echo "<p>Couldn't get the right WireMail-Module (WireMailSmtp). found: {$mail->className}</p>"; return; } if(!$mail->testConnection()) { // Connection not working: echo "<p>Couldn't connect to the SMTP server. Please check the {$mail->className} modules config settings!</p>"; return; }  
      A MORE ADVANCED DEBUG METHOD!
      You can add some debug code into a template file and call a page with it:
      $to = array('me@example.com'); $subject = 'Wiremail-SMTP Test ' . date('H:i:s') . ' äöü ÄÖÜ ß'; $mail = wireMail(); if($mail->className != 'WireMailSmtp') { echo "<p>Couldn't get the right WireMail-Module (WireMailSmtp). found: {$mail->className}</p>"; } else { $mail->from = '--INSERT YOUR SENDER ADDRESS HERE --'; // <--- !!!! $mail->to($to); $mail->subject($subject); $mail->sendSingle(true); $mail->body("Titel\n\ntext text TEXT text text\n"); $mail->bodyHTML("<h1>Titel</h1><p>text text <strong>TEXT</strong> text text</p>"); $dump = $mail->debugSend(1); } So, in short, instead of using $mail->send(), use $mail->debugSend(1) to get output on a frontend testpage.
      The output is PRE formatted and contains the areas: SETTINGS, RESULT, ERRORS and a complete debuglog of the server connection, like this one:
       
      Following are a ...


      List of all options and features


      testConnection () - returns true on success, false on failures


      sendSingle ( true | false ) - default is false

      sendBulk ( true | false ) - default is false, Set this to true if you have lots of recipients (50+)


      to ($recipients) - one emailaddress or array with multiple emailaddresses

      cc ($recipients) - only available with mode sendSingle, one emailaddress or array with multiple emailaddresses

      bcc ($recipients) - one emailaddress or array with multiple emailaddresses

       
      from = 'person@example.com' - emailaddress, can be set in module config (called Sender Emailaddress) but it can be overwritten here

      fromName = 'Name Surname' - optional, can be set in module config (called Sender Name) but it can be overwritten here


      priority (3) - 1 = Highest | 2 = High | 3 = Normal | 4 = Low | 5 = Lowest

      dispositionNotification () or notification () - request a Disposition Notification


      subject ($subject) - subject of the message

      body ($textBody) - use this one alone to create and send plainText emailmessages

      bodyHTML ($htmlBody) - use this to create a Multipart Alternative Emailmessage (containing a HTML-Part and a Plaintext-Part as fallback)

      addSignature ( true | false ) - the default-behave is selectable in config screen, this can be overridden here
      (only available if a signature is defined in the config screen)

      attachment ($filename, $alternativeBasename = "") - add attachment file, optionally alternative basename


      send () - send the message(s) and return number of successful sent messages


      debugSend(1) - returns and / or outputs a (pre formatted) dump that contains the areas: SETTINGS, RESULT, ERRORS and a complete debuglog of the server connection. (See above the example code under ADVANCED DEBUG METHOD for further instructions!)


      getResult () - returns a dump (array) with all recipients (to, cc, bcc) and settings you have selected with the message, the message subject and body, and lists of successfull addresses and failed addresses,


      logActivity ($logmessage) - you may log success if you want

      logError ($logmessage) - you may log warnings, too. - Errors are logged automaticaly
       
       
      useSentLog (true | false) - intended for usage with e.g. third party newsletter modules - tells the send() method to make usage of the sentLog-methods - the following three sentLog methods are hookable, e.g. if you don't want log into files you may provide your own storage, or add additional functionality here

      sentLogReset ()  - starts a new LogSession - Best usage would be interactively once when setting up a new Newsletter

      sentLogGet ()  - is called automaticly within the send() method - returns an array containing all previously used emailaddresses

      sentLogAdd ($emailaddress)  - is called automaticly within the send() method
      Changelog: https://github.com/horst-n/WireMailSmtp/blob/master/CHANGELOG.md
       
       
×
×
  • Create New...