025 How to use email helper in your components

HOW TO USE EMAIL HELPER IN YOUR COMPONENTS

• Example Of Email Helper Class

The Email Helper Class is a class that gets added to Components Helper area and is therefore available on every page, with which Emails can be send. For example: Take a look at the Helper Class by going to a component that has it included and at 'Helpers'. 00:00:25 The filename is usually the component name: 'Email'. As may be seen, it is in the basic abstract class. That takes Joomla's E-mailer, which is 'Jmail' and gets an instance of it, and adds it to mail and then loads in the variables that's required. 00:00:48

Setting Up Email Helper Class

If this feature is going to be used, the first thing to do when looking at a component (On Component Builder Dashboard) is to open 'Learning Manager'(In Editing the Component area) and go to Libs & Helpers. 00:01:22 It may be noticed that the 'add email helpers' has been set to 'on'. It places the Helper class in the component, but is not implemented anywhere else. That means that if 'yes' is clicked, it is still necessary to create fields, that need to get loaded to the config area.

Settings - Config Area

00:01:55 In 'Settings' is this 'config' area (Adding Custom Config Fields), which gives the ability to add configuration options to the components option area. So if this 'config - add' is being clicked, scroll down till that mail configuration and a whole lot of fields may be seen. These fields correspond to the Joomla's default fields. If you would like to create these fields and some info is needed in order to create these fields, like what should their names and content be, then go and look at the Joomla Global Configuration XML and all the settings in that file may be seen. 00:02:39 There is DKIM implementation available.

In Code Field Names

It will be necessary to look in the code to get these field's names. There is a difference between 'name', 'label' and 'description'. 00:03:13 For instance 'name' is the value that will be used in the code. In the code for example, that word 'mailer' means that the name of the field is called 'Mailer' and the same applies to the name 'field' etc. These are all the fields that needs to be set.

Component Global Options - Mail Configuration

In the component there is a 'Options' area, there is a Mail Configuration and a DKIM area. 00:03:45 It has the 'mailer' status. It is either set to 'Off', then no emails will go out, or to 'On'.

Switch Global Mailer Options

If it is set to 'On' it may be decided whether there is need to override the global variables. The global variables are set in Joomla's components global area. 00:04:10

Joomla Global Configuration - Server

If Global Configurations is opened, and then the Server, and then Mail Settings. These are the main or the Global Settings that will be used in any component that does not add these settings in their config. 00:04:40

If those fields had not been created and added to the component, but the button was used in order to add the Helper class to the component, the result will be that it will fall back to these settings in the Joomla default area. These 'Main Settings' are the values that should be overrided.<<<<<<<<<<<<<<<

Component Builder Email Switch Options

If you want your 00:05:08 component in some way to use other php mail or other send mail or SMTP, values that of the global, you need to set it here. That is basically what this area can do. So you use global, it falls back to the Joomla global. Otherwise you can override it on this level. And send it out in a way that is 00:05:38 what you would like.

DKIM Settings (Encryption)

The DKIM area is the more advanced area which allows you to encrypt and secure email sent out from you. To authenticate that it was really you that send it. This is helpful to show people that receive these emails that it's not spam, and it's really comes from you. It's more advanced. I would encourage you to read up on it. These are the values usually would be required to added a private key, a public key and these type of areas here(see video). If this is set to no, it will not be used, if it set to yes, please ensure to add the values. 00:06:25 Otherwise it still will not be used. So that's basically the values that you need still to create. Component does not do this for you. You need to do it. I could possibly foresee that in the future we might add this, if you tick the helper class it adds these values for you. But even then if you have done it manually, we'll make sure that it doesn't add in twice. 00:06:51 As long as these values have the same names, we will identify that, and do not add them dynamically to avoid clashes. For the meantime it's not automatically being added and so you need to do that manually if you want it to be there. If you don't, like I've said before it will fall back to the Joomla global. 00:07:15

Default Global In Code

To explain to you on the code level, basically it gets from the configuration, the mailer function. Then it checks whether it's global. If it is global, then it implements Joomla's values. If it's not global, it implements your components values. 00:07:38 That is basically what it will do. Now you can read through the code, but the most important area really is this(send) area. To know what is all the various options that you have in the signature to send out mail. So it's able to really send out a lot of mail but nonetheless you're also need to consider 00:08:04 your servers own limitations. Since we don't want you to spam people. We do not override those values. We are simply using the Joomla default Helper jmailer. And it is been extended from another class. There are a lot of features in here. If you want to know more about them you can read up on the jmailer 00:08:35 Class from Joomla. As well as read through this code here and see how we implemented it.

DKIM Values In Code

These(see video) are the dkim values that you would need in your component to be able to use the dkim encryption. But you could also read up on this and check out this function here, up till there, in its way that it's implementing these features. It obviously is adding it to the mailer and most of the work is done in the mailer. 00:09:05 It's basically adding the data to the mailer and the mailer takes care of the rest. Here it sends it off.

Error Checking For Emails In Code

And if there is an error, let's say for some reason it didn't work out well. Then it checks whether your component helper class, your component has a helper class, it's this file here(learningmanagerhelper). 00:09:31 If it have a storemessage variable or method. So if we were to go check this. You see that there is the storemessage method in the helper class. This is a custom method that I wrote. You can write it anywhere you like, but this signature should be the same. 00:10:00 So basically this area that(learningmanager) and that(learningmanager) is dynamically updated to your component. It uses your component name here(learningmanager) and your component name there(learningmanager). But this storemessage cannot be changed, but it takes the send email, the recipient, the subject, the body, the text only, the mode and it's says that it's emailed. So you can have different types, so if you look at the method, the type can be anything. 00:10:30 We want to do different things on different types. If it send an SMS and it didn't fail, you want to store the message. This kind of feature isn't only used when something didn't work, but also if it worked. If it was sent, it's going to store it. So it's a way to store the message,myou can 00:10:57 let your user go, if they login, they can see messages sent to them and this kind of stuff. This is what the store message does. You will see that it's whole huge custom method that I wrote. You can update it and change it, pause the video, copy it down. If you realize this is actually something you write up yourself you just need to make sure that that part is the same. The rest is up to you how you deal with it. That is implementing the learning manager emailer 00:11:35 in your component.

Implemented Example

Maybe I should show you where I implemented at least in one area. I have this component called job tracking system. I open it up, you'll see that it actually has that function: Add email helper. Set it to on. The view in which we are using the email method is the job order view. Basically we want to email the client, it did a job order 00:12:21 when it's created. So let me show you how I implemented it there. So here is the job order. I would basically then click on email. I can update it to whatever email I like, 00:12:45 [email protected] or something. Just send it in to nothing. Then once the email has been sent, it let's me know. In the top right it says email was sent successfully. That's basically what the emailer does. It just this button that sends the document 00:13:11 to my client. If I want to send it to my store, the people that does the job, I could also do that here. I'm not going to explain to you the reality of taking this content, adding it to the email and sending it. That I would suspect you need to know and you need to learn or study to do that yourself. I'm simply explaining to you how to use the email helper class.

Above Example In Code

So we will go to the code and I'll show you how I do it and 00:13:45 I'll give you some pointers. I won't go into detail about how that is done. Let's go to the code. We are in the job order, first thing here is some JavaScript. There's the send email function and gets a set of values. And then it gives it over to the send email server function, which sends it as a 00:14:20 json request to the server. The send email is the task and when it gets a response that's when you get the notification. That's simply the JavaScript of it. If we go to php, in previous tutorials we explain how to use the Ajax class.

I'm going to touched on it briefly. 00:14:47 You have your input here(ajax input). This is where you set up your controller. So you'll see in your controller there is send email class what was defined in this field here(see video). And you see that there is three variables, and they 00:15:12 should be filtered in this way and they are pass over to these methods and you should be login user. So if you look at the code, again this is the task(sendEmail), down here it triggers the task. It checks for those values and then passes it over to this method(sendmail) which is in the model. We go to models, Ajax. Here is the the model(see video). Let's just scroll down to the sendemail. Here is the sendemail and this again 00:15:47 is a custom script. So if I was to go back here, I close this, you'd see there's the ajax method, there is a lot, I mean look at that, you can see that scroll down way down is a lot of other custom methods. This is another custom method I've wrote, it's called sendemail, it gets the mail, the HTML, the type. It it does the necessary cleansing and whatever. 00:16:14

Over here(see video) we're calling the email helper. We using the send method, we passing the valuables, and set the result in here. If the results is true, 00:16:38 we will let the user know, otherwise we give him the error. I'm also using this email body to help me build the email because I want to make sure that it got all the necessary HTML and stuff. You can pause the video and type that out if you like. This is the email body that I usually use. It simply adds the subject to the email, 00:17:15 the necessary places as well as the body in the necessary place that it gets send in a way that's more appropriate. That all is happening right here. That is what I'm passing in here. A custom method which gets the data from the ajax and then sends it off. 00:17:43 That's a quick tutorial on how to implement sending emails through your component, using the email helper class. The email helper class is available on GitHub in the component builder. If you feel that our implementation lacks some professional help then please do make a commit to quest or send me an email. We'll gladly update an improved this class, although I think we followed all the necessary standard and requirements to make it useful to everyone.