Jump to content
adrian

Migrator

Recommended Posts

Great progress! I haven't tried the new features yet (maybe this is covered already) but it might be handy to have it spit out a list of any template files it moves. That would be to remind us to manually move over any include files or other resources those files depend on.

  • Like 1

Share this post


Link to post
Share on other sites

Great idea Steve - I'll do that for sure. 

Done and committed!

Edited by adrian

Share this post


Link to post
Share on other sites

Hi again everyone - I have spent quite a lot of time on this the last few days and it is now much more robust and feature rich.

In an effort to encourage some testing from you guys, I have attached an export of Ryan's blog profile that you can install into an existing PW site.

  1. Download the attached zip file
  2. Grab the latest version of Page Tree Migrator from Github (https://github.com/adrianbj/ProcessPageTreeMigrator) and install.
  3. Make sure your templates directory is writable by the server
  4. Run the module from the your Setup menu
  5. Choose "Import" and continue to Step 2
  6. Choose the Parent Page - choose "Home" which will install the blog as a first level child of your homepage.
  7. Make sure "Everything, including all data pages" is selected for Components to Import.
  8. From Data Source, choose "Zip File Upload", browse to the blog.zip file.
  9. Click "Upload and Create Content" and wait a few seconds.

That's it - you should have a fully functioning blog set up at: Home > Blog

It comes complete with the same test entries, images, gallery, tags, categories etc that Ryan's original one does, although I did add in one extra photo, embedded into an RTE and resized - the photo comes from Joss' Foundation 5 profile.

The one thing you'll notice is that the embedded Youtube link doesn't work, because the Video embedder module isn't installed. Page Tree Migrator will install core modules as needed, but obviously can't install other ones - yet :)

You'll notice that the blog is installed with its CSS and script files in a subdirectory of the templates folder to avoid an overwriting of existing files.

Please test and let me know what you think - Thanks!

blog.zip

  • Like 9

Share this post


Link to post
Share on other sites

I have attached an export of Ryan's blog profile that you can install into an existing PW site.

I had to re-read your last post! This is fantastic.  Thanks.

  • Like 1

Share this post


Link to post
Share on other sites

I've got two notices and a fatal error from your latest version on GitHub:

Notice: Trying to get property of non-object in D:\wamp\www\echofinance\site\modules\ProcessPageTreeMigrator.module on line 879
Notice: Trying to get property of non-object in D:\wamp\www\echofinance\site\modules\ProcessPageTreeMigrator.module on line 1049
Fatal error: Call to a member function getArray() on a non-object in D:\wamp\www\echofinance\site\modules\ProcessPageTreeMigrator.module on line 1052

Share this post


Link to post
Share on other sites

Hey Pete - sorry about that.

Sounds like you are exporting. The issue is that you haven't selected anything in the "Parent Page" or "Components to Export" option. My bad for forgetting to provide a friendly error instead of failing, but if you choose something in that step, you should be fine!

I'll fix it in the next version.

Let me know how you go :)

Share this post


Link to post
Share on other sites

Cutting edge php required? :)

Parse Error: syntax error, unexpected '[' (line 830 of /site/modules/ProcessPageTreeMigrator-master/ProcessPageTreeMigrator.module) 

Share this post


Link to post
Share on other sites

Oops - sorry about that Antti, and for the delayed response - was out enjoying some unseasonable sunshine!

I just pushed a quick fix that should work for older versions of php. I need to set up a 5.3 testing environment.

EDIT: Pete - the export process should now also provide friendly errors if a required option is not selected.

Edited by adrian

Share this post


Link to post
Share on other sites

Spectacular. I just moved a blog tree to another dev site which has saved me a good hour of setup time. Thank you!

  • Like 1

Share this post


Link to post
Share on other sites

Thanks Marty - glad to hear it is working for someone other than me - I was beginning to wonder :)

Also, I just set up php 5.3 testing environment and everything seems to be working there now too, so hopefully I won't be wasting Pete and Antti's time when they try again!

But please keep the bug reports and feature suggestions coming!

Share this post


Link to post
Share on other sites

If it helps my MAMP setup is running PHP 5.4.25

Actually there was a one things I noticed that didn't get packaged up in the zip I exported - and that was an include I used to show my blog categories. It might just be the way I've set it up but I'll put together something for you to look at later.

Share this post


Link to post
Share on other sites

Thanks for the report - I was developing it on 5.5 and have now tested on 5.3, so hopefully we are covered now :)

It makes sense that your include file was not added to the zip. Hopefully you noticed the message after the import to that effect - it mentions that you need to copy any .inc and other supporting files yourself. At the moment the migrator will only add template php files to the zip that are tied to the templates used in the pages that are exported. I have actually contemplated scanning through the template files looking for include, include_once, require, require_once and grabbing those files as well. I'll have a think about it and see if I think it makes sense to do that.

The blog profile zip I attached a few posts back was manually modified to contain all the associated inc, js, and css files, but everything else was direct from the automatic export process.

Share this post


Link to post
Share on other sites

I figured that might be the case as I hadn't logged that inc as a template at all - there was no real need to. I didn't see a message though - or maybe I missed it. I'll take a look next time I try it, which will be soon.

Share this post


Link to post
Share on other sites

Another pretty major update today. Here's the list of changes:

  1. Friendly error handling when modules/fieldtypes aren't installable on the destination site which also prevents any actions until you install the required modules.
  2. Support for migrating page data for all (hopefully) custom fieldtypes. I have tested with cropImage, MapMarker, Dimensions, and Phone. Let me know if you find one that doesn't work. Also, if you are playing around with MapMarker, be sure to make the changes shown in this PR: https://github.com/ryancramerdesign/FieldtypeMapMarker/pull/4/files - seems like it might only affect very recent devs of PW and hopefully Ryan will commit that change soon anyway.
  3. New Import Types: Append, Overwrite, Replace. Explained fully in the module, but the key new functionality is replace, which effectively allows you to edit the content in a section (Page Tree) of a site (say on your dev server), including changes to field settings, which fields are in the template (including repeater fields and their subfields), and the page data in the fields, and all these changes will be replicated on the destination site. This is very new, so let me know if you find something I have missed.

Remember, there is one happy customer already ....

Spectacular. I just moved a blog tree to another dev site which has saved me a good hour of setup time. Thank you!

But I am looking for more :)

If you want a quick demo, don't forget you can try installing Ryan's blog profile as a child of your Home using the zip attached to this post.

  • Like 1

Share this post


Link to post
Share on other sites

@adrian, I've been testing this a bit and getting this after export:

Notice: Trying to get property of non-object in /site/modules/ProcessPageTreeMigrator/ProcessPageTreeMigrator.module on line 1038

Warning: Invalid argument supplied for foreach() in /site/modules/ProcessPageTreeMigrator/ProcessPageTreeMigrator.module on line 1038

Not sure if this affects the import process, though. At least pages get imported properly, but there is something a bit strange there too; see attached screenshot. "Following template files" seems to suggest that something was (supposed to be) migrated there too, but now it looks like somethings missing below that headline?

Earlier this template had repeater field on it and I was seeing quite a bit more errors, so I removed the repeater field in case that was causing it somehow. Errors did actually go away, but only partly -- as you can see, some still remain.

I'm running 2.4 master branch on a local MAMP installation with PHP 5.5.10. You can see exported data here.

post-175-0-30741700-1394870451_thumb.png

  • Like 1

Share this post


Link to post
Share on other sites

Happy yet demanding :) I can't wait to test this update.

This Replace feature has me thinking (which I'll test soon). I know it's probably outside of the scope of what you're doing but how difficult would it be to periodically replace a page tree from one site to another? I'm thinking in terms of a site sharing a blog or news section. I know I could use Pages Web Service to show post lists but I'm thinking of shifting entire posts between sites regularly.

Share this post


Link to post
Share on other sites

Hey teppo,

Thank you for the testing. I can replicate that same export error. I hadn't come across it before, but looking at your export JSON, I noticed that the page field you included has a parent_id of "home". I never anticipated that. The module will actually find all page field parent/child trees and add them to the export, so if for example you had a pagefield that linked to a categories/category tree, then it would grab that info, export it and import it on the new site, even though it is not directly under the parent you chose when exporting.

I think the module actually handles this scenario quite well (despite the error which is an easy fix) - so if you do choose home, it won't try to export the entire home tree, but it will use the children of home on the new site, once you do the import, which is what happened for me when I imported your JSON. Does that make sense?

EDIT: Actually that 1038 error is because your page field doesn't have a "Template of Selectable Pages" set. I have always been testing with page fields with both "Parent of ..." and "Template of..." defined in the Input tab. I'll have to make sure there aren't any further complications here.

The message about importing template files should be hidden in this case, since it is clear you used the copy/paste approach. Obviously template files (*.php) can only be migrated with the "Save" output format. I'll take care of hiding that when it's not appropriate.

Now for the confusing one, the errors with repeater fields. I haven't had any issues with those in quite some time now so I am curious on the exact setup. Would you mind testing one again and send me the errors you're getting and also the JSON, and if they're not being included in the export, perhaps you could sketch out their structure.

One thing I am curious about on the repeater front - what option are you choosing for "Components to Export"? I have been doing almost all my recent testing with "Everything", so I am wondering if that might have something to do with it. I notice that none of your page fields have any content.

Thanks again, really appreciate this!

BTW, I have attached an export of a page tree that shows repeater and page fields working, along with images and RTE embedded images. Be sure to import "Everything" and choose "Replace". It should go into any parent, but I have been testing mostly with Home as the import's root is "About". It will replace your About (if you have one) and also install a US states page tree for the state selector field. There are a couple of repeaters at the bottom of the gallery child page.

files.zip

  • Like 1

Share this post


Link to post
Share on other sites

I've also been exporting "everything", though (like you said) the copy method obviously can't literally export everything.. :)

These are the errors I get in the same situation, with repeater field added. Ready items for this repeater is set to 3 and you can view the final JSON output here.

Notice: Trying to get property of non-object in /site/modules/ProcessPageTreeMigrator/ProcessPageTreeMigrator.module on line 1403

Warning: Invalid argument supplied for foreach() in /site/modules/ProcessPageTreeMigrator/ProcessPageTreeMigrator.module on line 1403

Notice: Trying to get property of non-object in /site/modules/ProcessPageTreeMigrator/ProcessPageTreeMigrator.module on line 1038

Warning: Invalid argument supplied for foreach() in /site/modules/ProcessPageTreeMigrator/ProcessPageTreeMigrator.module on line 1038

Warning: Invalid argument supplied for foreach() in /site/modules/ProcessPageTreeMigrator/ProcessPageTreeMigrator.module on line 1026

Notice: Trying to get property of non-object in /site/modules/ProcessPageTreeMigrator/ProcessPageTreeMigrator.module on line 1403

Warning: Invalid argument supplied for foreach() in /site/modules/ProcessPageTreeMigrator/ProcessPageTreeMigrator.module on line 1403

Notice: Trying to get property of non-object in /site/modules/ProcessPageTreeMigrator/ProcessPageTreeMigrator.module on line 1403

Warning: Invalid argument supplied for foreach() in /site/modules/ProcessPageTreeMigrator/ProcessPageTreeMigrator.module on line 1403

Notice: Trying to get property of non-object in /site/modules/ProcessPageTreeMigrator/ProcessPageTreeMigrator.module on line 1403

Warning: Invalid argument supplied for foreach() in /site/modules/ProcessPageTreeMigrator/ProcessPageTreeMigrator.module on line 1403

Testing your zip file didn't go exactly as planned, though that was probably user error; didn't select "replace", tried to "append" with parent set to "home" and as a result I got "Integrity constraint violation: 1062 Duplicate entry 'about-1' for key 'name_parent_id'".

Slightly weird thing here is that when trying this again with "replace", I got the same error, though this might be because something was broken earlier. Might have to setup another test site to see what's actually going on here -- if this works for you, there's most likely something wrong with my test site.

One specific thing I'm not really comfortable with, though I'm not entirely sure if that's possible to avoid either, is that even though the import fails things like fields and templates are still added and/or kept. This could potentially leave the site in a kind of a strange state, with some old content and some new. It'd be cool if failed import "cleaned up the mess", so to speak :)

Another thing that probably should be handled somehow are possible permission errors:

Warning: copy(/site/templates///basic-page.php): failed to open stream: Permission denied in /site/modules/ProcessPageTreeMigrator/ProcessPageTreeMigrator.module on line 449

Warning: copy(/site/templates///gallery.php): failed to open stream: Permission denied in /site/modules/ProcessPageTreeMigrator/ProcessPageTreeMigrator.module on line 449

The reason for these is obvious and (again) I should've known better, but then again, the module could also check for necessary permissions beforehand -- or perhaps just interrupt the import the moment this happens and notify user to make sure that permissions need to be tweaked?

.. and by the way, those template paths with three forward slashes look a bit strange, but that's far from fatal :)

PS. I actually enjoy testing this module and see a lot of potential in it. As a matter of fact it's already proven it's worth in some of our projects, saving me quite literally hours of work, on more than one occasion. If it sounds like I'm only seeing bad things here, that couldn't be further from the truth :)

  • Like 1

Share this post


Link to post
Share on other sites

Thanks again teppo - awesomely helpful!

So I think I have taken care of everything from your reports:

  1. If there are no template php files in the import, then the message is not displayed to avoid confusion.
  2. Write permissions are now checked on the destination templates directory (if there are template files to be imported), before anything happens and the user is alerted so they can fix and start again.
  3. Also fixed the extra forward slashes :)
  4. I have fixed the line 1403 errors for repeaters - that error only occurred when there were no entries for a repeater on a page which is why I hadn't seen it before. I am not getting the line 1026 error at all, so please let me know if that one still shows up for you.
  5. Fixed the line 1038 error - now the module will work without the page field's Template of Selectable Pages set. Along with this I have also put a limitation on automatically migrating content for page fields - it won't automatically export the entire page tree if a page field's Parent of Selectable Pages is Home (id#1, just in case the name was changed), and also only if the Parent of Selectable Pages is set - so, it won't potentially try to migrate pages from all over the page tree, which might happen if some is using Template, or even worse a Custom Selector or Custom PHP option.

Not sure why you are getting that integrity constraint violation. I know I have broken many a PW install while testing this module, so maybe if you could start with a fresh one and let me know, that would be great. By the way - I tested that files.zip with "Append" and it works as expected without errors, so I do think something is likely amiss at your end, but please let me know what you find.

Actually, I have managed to replicate something similar to this - it's amazing what you can sometimes miss due to the way you are doing something. Anyway, I am on it - it is related to the addition of the new REPLACE option, but I am having trouble tracking it down fully tonight, so it might have to wait another day or until I can find some more time, but I'll post again when that is fixed. In the meantime, so long as you delete the About tree from your install before importing, that zip should work!

Great thought on the issue of a failed import and the cleanup idea. Ideally I'd love for there to be no reason for a failed import, so maybe better checking for potential conflicts before anything happens is the easiest way. Undoing changes / cleanup might be tricky!

Really appreciate hearing that this has saved you lots of time - I would love this to be a "must have" PW module once some more kinks are ironed out.

Thanks again.

Edited by adrian

Share this post


Link to post
Share on other sites

Happy yet demanding :) I can't wait to test this update.

This Replace feature has me thinking (which I'll test soon). I know it's probably outside of the scope of what you're doing but how difficult would it be to periodically replace a page tree from one site to another? I'm thinking in terms of a site sharing a blog or news section. I know I could use Pages Web Service to show post lists but I'm thinking of shifting entire posts between sites regularly.

Hey Marty, anything for you :)

Do you mean automatically or manually on a regular basis? Manually will be no problem at all - that is what this is designed to do (once I get a for more of the REPLACE kinks sorted out). If you want automatic replacement, I am sure we could use a cron job to handle both the export and import - the key thing would be to save the zip on the server, instead of downloading it to local machine. Then get the zip from the destination server and trigger the import. All sounds do-able. That said, if it is just content we are talking about and no fields or templates would change, then I wonder if an import from a web service feed might not be a better approach - this could even bring across new images.

I'll sleep on it!

Share this post


Link to post
Share on other sites

Turns out I really broke some keys things when I added the import actions functionality (for append, overwrite, replace). I need sleep now and won't be able to get to this again for at least a day, maybe two. So, the most stable version right now is probably:

https://github.com/adrianbj/ProcessPageTreeMigrator/blob/019e006833ad970263533516aa7615b8c87af573/ProcessPageTreeMigrator.module

Of course this doesn't include the fixes for the PHP warnings that teppo found, nor the directory writing checks etc.

Anyway, I'll post again when the import actions additions are working properly.

Share this post


Link to post
Share on other sites

Ok, I have fixed another round of bugs, including one weird one getting an "Unknown column 'field_images.modified'" error when importing a page tree into a brand new install before ever having viewed a page on the site. Getting off track, but the issue was due to the need to trigger getDatabaseSchema on the images field which adds the modified and created DB fields. 

The things I've done is add optional support for migrating createdUser/modifiedUser and created/modified datetime for pages. I am using quiet save which is supposed to support createdUser, modifiedUser, and created, but it isn't supporting modifiedUser for me at the moment. I might resort to SQL, or I might decide it's actually best to just change the created versions and leave the modified to change to the user running the import and the current time.

On the user migration - if a user doesn't exist it will be created and assigned its roles from the source installation as defined in the JSON. Also, if the needed roles aren't available, they will be created too.

Let me know how it goes for you!

  • Like 1

Share this post


Link to post
Share on other sites

On a roll - after a chat with Joss, I have added a new option on export that allows you to select any additional required helper files such as .inc, .css, .js, etc. These selected files will be packaged in the zip for the migration.

This option is only displayed if you choose "save" because obviously not relevant to "copy" where it's only the JSON that can be exported.

Note that there is no need to select normal template files as these are still included in the export automatically.

  • Like 1

Share this post


Link to post
Share on other sites

Another pretty major update!

There is now an "Edit Imported Content" option during the import process that lets you determine exactly which fields and pages (from the JSON) get imported.

This should come in especially handy when importing the one of the Shared JSON packages. I have added a new one that is a good test for this, called "person" (maybe needs a more detailed name), that creates a person template with a complete range of contact/address fields. So, on import you can easily choose only the fields you want from the package.

I think this should be really handy for distributing standard templates, but with easy customization for each use case.

Share this post


Link to post
Share on other sites

Adrian, this module sounds more and more useful everytime. Next thing, you will be creating a "recording" mode that collects all changes that happen in PW during a certain period and makes it possible to export them as json to make late changes on published sites really easy! (did that sound like a suggestion?)

  • Like 2

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 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
       
       
    • By Cybermano
      Food Allergens Module
      A simple List of Food Allergens
      My needs were to provide a simple list of food allergens for our clients with restaurant related activity.
      The idea was to simply output the list (to speed up the data entry) without leaving the food menu editing, eg. opening another page in new tab or window.
      This isn't a perfect solution, but it works fine for my needs and I decided to share the base idea.
      This could also be easily used to show little notes or short "vademecum", not only for the list of food allergens.
      ---
      Main features
      The basis
      All moves from a short editing of the module in this tutorial: How to create custom admin pages by @bernhard
      First of all it creates an empty admin page, with a dedicated permission to let safe-user to see it (this permission has to be created as a new ones, manually or by the module).
      Once the page is created, I have hooked its behaviour into the ready.php, to show the content (basically a list).
      A step further
      With the tips of  @bernhard, @Soma (and many others), see here , the magic happens. 
      The new page will be shown as a panel, so editors will not abandon their data entry to have a quick view to the list.
      A little further
      Why scroll to the top of the page to click a link?
      The next step was to create a sticky button only in the food menu pages.
      Again with a @bernhard tip I moved into the customization of this simple module and the related hook.
      ---
      How to use this module
      After installed, it creates the page /admin/page/allergens/ and the module is to be setted up. The first field is a CKEditor with multi-language. This is the place where to write the informations that will be shown into the page. The next field is a simply text-area where to place a bit of JS that will be appended to the markup of the text (omit the 'script' tags). I also putted a checkbox with a silly statement: this to think at least twice on the safety of the written JS. Now comes the first way to display the link to the page
      Field Note with Link. Enable and save it. The module will display a new row with 4 selects (1 standard and 3 ASM):
      View mode (to show the page as Panel or as Modal PopUp); Templates to select: select one or more and save before proceed, so the  asm-select of the pages will be populated showing all the pages of the selected templates. Pages to select: also here select at least one and save before proceed to populate the asm-select for fields only with the ones that belong to the selected pages. Select the fields where to place the note and save again. That's all: now you will find into the notes of the selected fields the link "See the List of Allergens".
      At the same way, the option for the sticky button, but with a plus
      The field select is obviously unnecessary, but you could play with the last row: the inline styles to fix your sticky button where you like. Here you could set the sticky position of the <div> and the absolute ones of the <a>.

      Video Explanation
      In these screencasts you could see a custom JS that show a "copy" button near a "hanna-code" call.
      This because I've set a specific one for each allergen to show up a tooltip in the front end.

      Registrazione #33.mp4  

      Registrazione #34.mp4 ---
      Last but not the least
      Actually it works fine for my needs, even if it's much improvable: I'm working on the permissions creation, the uninstall section, a separate configs and defaults and how to include the hook into the module leaving free the ready.php. According to a simpler uninstall. Also I would make the link text as a dynamic text field, so it will be more flexible.
      I always learn a lot here, so I would share my code for whom it could be interested.
      I removed the hanna code references, but I provide you the html list of the allergens, English and Italian too, so you can paste them into the "source" of the CKEditor field to have a ready to use module.
      Obviously you are free to modify the code as per your needs.
      Please, keep in mind that I'm not a pro coder and I beg your pardon for my verbosity (speaking and coding). 😉
      I hope be helpful or for inspiration.
      Bye
      ready.phpList-ITA.htmlList-ENG.htmlAllergens.module
      README.md
×
×
  • Create New...