made placeholders available in placeholder callback

Author: mtrezza

README.md

@@ -99,8 +99,9 @@ const server = new ParseServer({
                     // A callback that makes the Parse User accessible and allows
                     // to return user-customized placeholders that will override
                     // the default template placeholders. It also makes the user
-                    // locale accessible, if it was returned by the `localeCallback`.
-                    placeholderCallback: async ({ user, locale }) => {
+                    // locale accessible, if it was returned by the `localeCallback`,
+                    // and the current placeholders that will be augmented.
+                    placeholderCallback: async ({ user, locale, placeholders }) => {
                         return {
                             phone: user.get('phone');
                         };
@@ -149,12 +150,13 @@ There are different files for different parts of the email:
 Placeholders allow to dynamically insert text into the template file content. The placeholders are filled in according to the key-value definitions returned by the placeholder callback in the adapter configuration.
 
 This is using the [mustache](http://mustache.github.io/mustache.5.html) template syntax. The most commonly used tags are:
-- `{{double-mustache}}`
+- `{{double-mustache}}`: The most basic form of tag; inserts text as HTML escaped by default.
+- `{{{triple-mustache}}}`: Inserts text with unescaped HTML, which is required to insert a URL for example.
 
-    The most basic form of tag; inserts text as HTML escaped by default.
-- `{{{triple-mustache}}}`
-    
-    Inserts text with unescaped HTML, which is required to insert a URL for example.
+By default, the following placeholders are available in the password reset and email verification templates:
+- `appName`: The app name as defined in the Parse Server configuration.
+- `username`: The username of the user who requested the email.
+- `link`: The URL to the password reset or email verification form.
 
 # Localization
 

spec/ApiMailAdapter.spec.js

@@ -466,6 +466,41 @@ describe('ApiMailAdapter', () => {
             expect(apiCallback.calls.all()[0].args[0].payload.text).not.toContain(templatePlaceholder);
         });
 
+        it('overrides the template placeholder with the email placeholder', async () => {
+            const adapter = new ApiMailAdapter(config);
+            const apiCallback = spyOn(adapter, 'apiCallback').and.callThrough();
+            const email = {
+                templateName: 'customEmailWithPlaceholderCallback',
+                recipient: 'to@example.com',
+                direct: true,
+                placeholders: {
+                    appName: "EmailPlaceholder"
+                }
+            }
+            const template = config.templates[email.templateName];
+            const templatePlaceholder = template.placeholders.appName;
+            const emailPlaceholder = email.placeholders.appName;
+            spyOn(template, 'placeholderCallback').and.callFake(async () => {
+                return {};
+            });
+
+            await adapter._sendMail(email);
+            expect(apiCallback.calls.all()[0].args[0].payload.text).toContain(emailPlaceholder);
+            expect(apiCallback.calls.all()[0].args[0].payload.text).not.toContain(templatePlaceholder);
+        });
+
+        it('makes placeholders accessible in placeholder callback', async () => {
+            const adapter = new ApiMailAdapter(config);
+            const templateName = 'customEmailWithPlaceholderCallback';
+            const template = config.templates[templateName];
+            const email = { templateName, link, appName, user };
+            const placeholderCallback = spyOn(template, 'placeholderCallback').and.callThrough();
+
+            await adapter._sendMail(email);
+            expect(placeholderCallback.calls.all()[0].args[0].placeholders.link).toBe(link);
+            expect(placeholderCallback.calls.all()[0].args[0].placeholders.appName).toBe(appName);
+        });
+
         it('makes user locale accessible in placeholder callback', async () => {
             const adapter = new ApiMailAdapter(config);
             const apiCallback = spyOn(adapter, 'apiCallback').and.callThrough();

src/ApiMailAdapter.js

@@ -228,9 +228,12 @@ class ApiMailAdapter extends MailAdapter {
 
     // If placeholder callback is set
     if (placeholderCallback) {
+      
+      // Copy placeholders to prevent any direct changes
+      const placeholderCopy = Object.assign({}, placeholders);
 
       // Add placeholders from callback
-      let callbackPlaceholders = await placeholderCallback({ user, locale });
+      let callbackPlaceholders = await placeholderCallback({ user, locale, placeholders: placeholderCopy });
       callbackPlaceholders = this._validatePlaceholders(callbackPlaceholders);
       Object.assign(placeholders, callbackPlaceholders);
     }