Merge pull request #7 from douglascayers/develop

Release 2.1

Author: douglascayers

.gitignore

@@ -1,7 +1,6 @@
-.idea
-.sfdx
-.vscode
+.idea/
+.sfdx/
+.vscode/
 *.iml
-assets
-IlluminatedCloud
-deploy.sh
+IlluminatedCloud/
+node_modules/

LICENSE

@@ -1,6 +1,6 @@
 BSD 3-Clause License
 
-Copyright (c) 2018, Doug Ayers, douglascayers.com
+Copyright (c) 2018-2019, Doug Ayers, douglascayers.com
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

README.md

@@ -1,12 +1,22 @@
-# Call REST API from Lightning Components without Named Credentials
+# Call REST API from Lightning Aura Components without Named Credentials
 
 A simple [promise-based](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/js_promises.htm)
 [service component](https://developer.salesforce.com/blogs/2018/08/implement-and-use-lightning-service-components.html)
 for working with Salesforce REST API and JavaScript Fetch API
-directly from your component's JavaScript without you needing to
+directly from your aura component's JavaScript without you needing to
 write Apex or configure Named Credentials. Just install and use.
 
-# Pre-Requisites
+## 📝 Table of Contents
+
+* [Prerequisites](#-prerequisites)
+* [Getting Started](#-getting-started)
+* [Example Usage](#-example-usage)
+* [Troubleshooting](#-troubleshooting)
+* [Authors](#️-authors)
+* [Acknowledgements](#-acknowledgements)
+* [License](#-license)
+
+## 🚨 Prerequisites
 
 1. Enable Lightning Experience
 2. Enable My Domain
@@ -15,15 +25,32 @@ write Apex or configure Named Credentials. Just install and use.
 You can find step-by-step instructions with screen shots in the [Mass Action Scheduler Pre-Requisites](https://github.com/douglascayers-org/sfdx-mass-action-scheduler/wiki/Pre-Requisites-Instructions) wiki page,
 which is my primary app that uses this component. 
 
-
-# Getting Started
+## 👋 Getting Started
 
 1. Deploy this project to your org (you only need what's in `force-app` folder).
 
+    ```
+    git clone https://github.com/douglascayers/sfdx-lightning-api-component.git
+    
+    cd sfdx-lightning-api-component
+    
+    sfdx force:org:create -a lapi -s -f config/project-scratch-def.json
+    
+    sfdx force:source:deploy -u lapi -p force-app
+    ```
+
 2. Explore the `LC_RequestDemo` and `LC_FetchDemo` components in the `force-demo` folder on usage.
 
 3. Try out a demo
 
+    ```
+    sfdx force:source:deploy -u lapi -p force-demo
+    
+    sfdx force:user:permset:assign -n LC_Demo
+    
+    sfdx force:org:open -u lapi -p //lightning/n/LC_Demo
+    ```
+
     a. Assign yourself the **LC Demo** permission set.
 
     b. Navigate to the **LC Demo** tab.
@@ -32,10 +59,9 @@ which is my primary app that uses this component.
 
     d. Marvel that you didn't have to write any Apex code or configure a Named Credential :)
 
+## 📘 Example Usage
 
-## Example Usage
-
-Add the `<c:lc_api>` to your component and give it an `aura:id` for reference.
+Add the `<c:lc_api>` to your aura component and give it an `aura:id` for reference.
 
 ```xml
 <!-- YourComponent.cmp -->
@@ -55,7 +81,7 @@ Find the `<c:lc_api>` by its `aura:id` then call one of the request methods:
     createAccount: function( component, event, helper ) {
 
         component.find( 'lc_api' ).restRequest({
-            'url' : '/services/data/v45.0/sobjects/Account',
+            'url' : '/services/data/v46.0/sobjects/Account',
             'method' : 'post',
             'body' : JSON.stringify({
                 "Name" : "LC Demo Account"
@@ -85,9 +111,9 @@ Find the `<c:lc_api>` by its `aura:id` then call one of the request methods:
 })
 ```
 
-# Troubleshooting
+## 🧐 Troubleshooting
 
-## "Access Denied" or "No 'Access-Control-Allow-Origin' header is present on the requested resource. Origin 'https://yourinstance.visualforce.com' is therefore not allowed access."
+### "Access Denied" or "No 'Access-Control-Allow-Origin' header is present on the requested resource. Origin 'https://yourinstance.visualforce.com' is therefore not allowed access."
 
 Your request was blocked due to [Cross-Origin Resource Sharing (CORS) policy](https://help.salesforce.com/articleView?id=extend_code_cors.htm&type=5).
 
@@ -99,24 +125,25 @@ Because the two domains do not match, then CORS policy prevents the request.
 
 2. Add the origin URL mentioned in your error message (e.g. `https://yourinstance.visualforce.com`) to the list of whitelisted domains.
 
-
-# Credits
+## ✍️ Authors
 
 [Doug Ayers](https://douglascayers.com) develops and maintains the project.
 
+See also the list of [contributors](https://github.com/douglascayers/sfdx-lightning-api-component/graphs/contributors) who participated in this project.
+
+## 🎉 Acknowledgements
+
 [Penpal](https://github.com/Aaronius/penpal)
 for a secure, promise-based library for communicating between windows and iframes.
 
 [jsforce](https://jsforce.github.io/)
 for an elegant, promise-based library for working with Salesforce REST API.
 
-
-# Other Utilities
+## 🎈 Other Utilities
 
 You should check out [sfdc-lax](https://github.com/ruslan-kurchenko/sfdc-lax) by Ruslan Kurchenko,
 a promise-based service component that makes calling Apex actions or using Lightning Data Service a breeze.
 
-
-# License
+## 👀 License
 
 The source code is licensed under the [BSD 3-Clause License](LICENSE)

config/project-scratch-def.json

@@ -1,10 +1,10 @@
 {
-  "orgName" : "Lightning API",
-  "edition" : "Developer",
-  "features" : [],
-  "settings" : {
-    "orgPreferenceSettings" : {
-      "s1EncryptedStoragePref2" : false
+    "orgName" : "Lightning API",
+    "edition" : "Developer",
+    "features" : [],
+    "settings" : {
+        "orgPreferenceSettings" : {
+            "s1EncryptedStoragePref2" : false
+        }
     }
-  }
 }

force-app/main/aura/LC_API/LC_API.cmp

@@ -14,11 +14,17 @@ License: BSD 3-Clause License
                     access="private"
                     description="Which visualforce page to load for bridging API calls."/>
 
-    <aura:attribute name="penpalInitialized"
+    <aura:attribute name="penpalFrameCreated"
                     type="Boolean"
                     access="private"
                     default="false"
-                    description="Has the Penpal connection been initialized?"/>
+                    description="Has the Penpal iframe been created?"/>
+
+    <aura:attribute name="penpalFrameConnected"
+                    type="Boolean"
+                    access="private"
+                    default="false"
+                    description="Has the Penpal iframe been connected?"/>
 
     <aura:handler name="init" value="{!this}" action="{!c.onInit}"/>
 
@@ -39,7 +45,7 @@ License: BSD 3-Clause License
 
         Example usage:
             component.find( 'lcAPI' ).restRequest({
-                'url' : '/services/data/v45.0/sobjects/Account',
+                'url' : '/services/data/v46.0/sobjects/Account',
                 'method' : 'post',
                 'body' : JSON.stringify({
                     'Name' : 'Salesforce',
@@ -94,15 +100,15 @@ License: BSD 3-Clause License
                         description="Supports these keys: url (string), options (map)."/>
     </aura:method>
 
-    <div class="slds-hide">
-        <iframe aura:id="penpalFrame" src="{!v.iframeSrc}"></iframe>
+    <div aura:id="penpalFrameContainer" class="slds-hide">
+        {!v.body}
     </div>
 
 </aura:component>
 <!--
 BSD 3-Clause License
 
-Copyright (c) 2018, Doug Ayers, douglascayers.com
+Copyright (c) 2018-2019, Doug Ayers, douglascayers.com
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

force-app/main/aura/LC_API/LC_API.cmp-meta.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <AuraDefinitionBundle xmlns="http://soap.sforce.com/2006/04/metadata">
-    <apiVersion>45.0</apiVersion>
+    <apiVersion>46.0</apiVersion>
     <description>LC_API</description>
 </AuraDefinitionBundle>

force-app/main/aura/LC_API/LC_APIController.js

@@ -29,58 +29,126 @@ License: BSD 3-Clause License
      */
     onRender: function( component, event, helper ) {
 
-        let initialized = component.get( 'v.penpalInitialized' );
+        const isPenpalFrameCreated = component.get( 'v.penpalFrameCreated' );
 
+        // For Penpal to operate correctly, you must ensure that `connectToChild`
+        // is called before the iframe has called `connectToParent`.
         // Since the iframe source is calculated asynchronously,
         // we listen to the component's render events and each time
-        // check if the iframe is ready, and if so, then we initialize
+        // check if the iframe source is ready, and if so, then we initialize
         // penpal to connect this component to the iframe.
         // Since we only want to do this once, we also set the initialized flag.
-        if ( !initialized ) {
+        if ( !isPenpalFrameCreated ) {
 
-            let iframeElmt = component.find( 'penpalFrame' ).getElement();
+            const container = component.find( 'penpalFrameContainer' );
+            const iframeSrc = component.get( 'v.iframeSrc' );
 
-            if ( !$A.util.isEmpty( iframeElmt.src ) ) {
+            // Ensure the container element has rendered otherwise we can't
+            // append child elements to it. And wait for the iframe source to
+            // be available otherwise no reason to create the iframe element.
+            if ( !$A.util.isEmpty( container ) && !$A.util.isEmpty( iframeSrc ) ) {
 
-                component.set( 'v.penpalInitialized', true );
+                $A.createComponent(
+                    "aura:html",
+                    {
+                        "aura:id": "penpalFrame",
+                        "tag": "iframe",
+                        "HTMLAttributes": {
+                            "src": iframeSrc
+                        }
+                    },
+                    function ( iframeCmp, status, errorMessage ) {
+
+                        // This callback happened asynchronously, so make one
+                        // more check on whether the penpal frame has been initialized or not
+                        // in the off chance a separate render cycle got here before this one.
+                        const isPenpalFrameCreated = component.get( 'v.penpalFrameCreated' );
+
+                        if ( isPenpalFrameCreated ) {
+
+                            console.log( 'LC_API: iframe is already initialized' );
+
+                        } else if ( status === 'SUCCESS' ) {
+
+                            // At this point, the iframe component has been constructed
+                            // but not yet been rendered, so we don't have access to the
+                            // HTML iframe element yet. We need to wait for another render cycle,
+                            // that is, we need to wait for the render() method to be called again
+                            // after we append the new iframe component to the body of its container.
+                            // Once we're able to find the 'penpalFrame' on the page then
+                            // we can proceed with the rest of the penpal initialization.
+
+                            component.set( 'v.penpalFrameCreated', true );
+
+                            container.set( 'v.body', [ iframeCmp ] );
+
+                            console.info( 'LC_API: iframe initialized' );
+
+                        } else if ( status === 'INCOMPLETE' ) {
+
+                            console.warn( 'LC_API: No response from server or client is offline' );
+
+                        } else if ( status === 'ERROR' ) {
+
+                            console.error( 'LC_API: Error creating iframe: ' + errorMessage );
+
+                        }
+
+                    }
+                );
+
+            } // else, iframe source is empty, keep waiting
+
+        } else {
+
+            const isPenpalFrameConnected = component.get( 'v.penpalFrameConnected' );
+            const iframeCmp = component.find( 'penpalFrame' );
+
+            if ( !$A.util.isEmpty( iframeCmp ) && !isPenpalFrameConnected ) {
 
                 const connection = Penpal.connectToChild({
                     // The iframe to which a connection should be made
-                    iframe: iframeElmt
+                    iframe: iframeCmp.getElement()
                 });
 
                 helper._penpal.connection = connection;
 
                 connection.promise.then( $A.getCallback( function( child ) {
+
                     // Cache a reference to the child so that we can
                     // use it in the restRequest/fetchRequest methods,
                     // as well as be able to destroy it when this component unrenders.
                     helper._penpal.child = child;
+                    console.info( 'LC_API: connected to iframe ' + iframeCmp.getGlobalId() );
+                    component.set( 'v.penpalFrameConnected', true );
+
                 })).catch( $A.getCallback( function( err ) {
-                    console.error( 'LC_API: Error establishing connection to iframe', err );
-                    component.set( 'v.penpalInitialized', false );
+
+                    console.error( 'LC_API: Error establishing connection to iframe ' + iframeCmp.getGlobalId(), err );
+                    component.set( 'v.penpalFrameConnected', false );
+
                 }));
 
-            } // else, iframe source is empty, keep waiting
+            }
 
         }
 
     },
 
     onRestRequest: function( component, event, helper ) {
-        var params = event.getParam( 'arguments' );
+        const params = event.getParam( 'arguments' );
         return helper.handleRestRequest( component, params.request );
     },
 
     onFetchRequest: function( component, event, helper ) {
-        var params = event.getParam( 'arguments' );
+        const params = event.getParam( 'arguments' );
         return helper.handleFetchRequest( component, params.request );
     }
 })
 /*
 BSD 3-Clause License
 
-Copyright (c) 2018, Doug Ayers, douglascayers.com
+Copyright (c) 2018-2019, Doug Ayers, douglascayers.com
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without