apex4x/Help/$A API/Import and Fetch APIs/Import.txt

The Comprehensive ARIA Development Suite

��

Function: import(ExternalResources, ConfigObject, ContextNode)



Shorthand1: import(ExternalResources, CallbackFunction)



Shorthand2: import(ExternalResources, ConfigObject, CallbackFunction)



Description: Loads one or more external scripts, stylesheets, or images into the current document within the specified domElement. Differs from $A.getScript by utilizing the native Fetch API for faster processing and more granular control.



Returns: domElement, or $A object if chained.



Note: The ConfigObject parameter can be used to set manual overrides for custom functionality. The ContextNode parameter can be used to set a custom DOM element where imported tag elements are appended. When the "name" property is set within ConfigObject, the referenced module code will be imported and then executed dynamically if it has not been imported previously, then all subsequent import statements with the same name will cause the module callback statement to be executed without having to import the external module code again.



ExternalResources (argument)



The external resources parameter may contain an absolute or relative file path string, or it may contain an array of multiple file paths.



Alternatively, the $A.moduleFolder path can be set to reference the folder path where 4X module files are located. When this is done, module files can be loaded simply by referencing the file name for each module, whether as a string to pull in one module, or as an array of module names to import all at once. When doing this, it is not necessary to include ".js" at the end of each module name reference. Examples: "Accordion", or ["Accordion", "Beep", "Datepicker", ...]



For help configuring the default "moduleFolder" path, view the help file at: "Help/Module Intro and Usage"



ConfigObject (argument)



Syntax:



{



  // Defer call function execution until after the page completes loading.

  // When true, all external modules will load instantly to maximize speed, but the associated call function will be deferred.

  defer: false, // Default



  // Set a unique name for the import statement.

  // When specified, external modules for this import statement will be loaded only once, after which the call function will always be executed immediately. 

  // Note: This functionality is separate from caching, which will still execute the previously loaded module code when called again even when stored internally.

  name: "", // Empty by default.



  // Specify that the imported module code will be executed only once, after which it will not be executed again even if the same import statement is run repeatedly.

  once: false,



  // May be set as a localized override of the $A.noCache property, where import caching can be temporarily enabled or disabled as needed.

    noCache: false,



  // Set custom props that will be passed into the scope of every dynamically loaded module.

  // When set, "props" is automatically declared within the scope of all externally loaded module code, which may in turn be passed into other import statements to pass data down the chain of each module.

  // To better understand how the props object works, view the help file "Props.txt".

  props: {

    // Set custom properties and methods to pass into each external module through 'props'.

  },



  // Execute a callback after all external resources complete loading.

  call: function(props, returnedValue) {

    // Do something after the external resources load.

    // returnedValue is populated when an imported module includes a return statement within it.

  },



  // When importing an array of multiple resources, specify that the call function will run after each import completes loading.

  // Otherwise, only do so after all resources finish loading.

  callOnAll: false,



  // Optionally override all functionality within the internal Fetch get method for every url being imported.

  override: {

    data: {

      // Options: "html", "text", "xml", "json"

      returnType: "text",

      // Sets a CSS query selector to return the first matching node within the newly loaded html or xml.

      selector: "",

      // Fetch API 

      method: "GET",

      headers: {}, // request headers. format is the identical to that accepted by the Headers constructor

      body: null, // request body. can be null, a string, a Buffer, a Blob, or a Node.js Readable stream

      cache: "default", // The cache mode you want to use for the request: default, no-store, reload, no-cache, force-cache, or only-if-cached.

      redirect: "follow", // The redirect mode to use: follow (automatically follow redirects), error (abort with an error if a redirect occurs), or manual (handle redirects manually). In Chrome the default is follow (before Chrome 47 it defaulted to manual).

      keepalive: false, // The keepalive option can be used to allow the request to outlive the page. Fetch with the keepalive flag is a replacement for the Navigator.sendBeacon() API.

      mode: 'cors', // The mode you want to use for the request, e.g., cors, no-cors, or same-origin.

      credentials: 'omit', // The request credentials you want to use for the request: omit, same-origin, or include. To automatically send cookies for the current domain, this option must be provided. Starting with Chrome 50, this property also takes a FederatedCredential instance or a PasswordCredential instance.

      referrer: 'client', // A USVString specifying no-referrer, client, or a URL. The default is client.

      referrerPolicy: 'no-referrer', // Specifies the value of the referer HTTP header. May be one of no-referrer, no-referrer-when-downgrade, origin, origin-when-cross-origin, unsafe-url.

      signal: null, // An AbortSignal object instance; allows you to communicate with a fetch request and abort it if desired via an AbortController.

      integrity: null // Contains the subresource integrity value of the request (e.g., sha256-BpfBw7ivV8q2jLiT13fxDYAe2tJllusRSZ273h2nFSE=).

    },

    success: function(content, promise){    },

    error: function(error, promise){    }

  }



}



ContextNode (argument)



The ContextNode parameter can be optionally set to load imported content into specific DOM node container elements when needed. This is often used when importing CSS stylesheets.



CallbackFunction (argument)



The specified callback function will execute after the referenced module or module array has completed loading.



Example:



// Load an external module and execute a callback function using shorthand syntax.

$A.import( stringPathToImport, function() {

  // Do something after the imported modules complete loading.

});



// Load an external module and execute a callback function using alternative shorthand syntax.

$A.import( [stringPathsToImport], {defer: true}, function() {

  // Do something after the imported modules complete loading.

});



// Import a collection of modules into 4X

$A.import(["Accordion", "Datepicker", "Tab"]);



// Import a collection of modules into 4X that will load only once.

$A.import(["Accordion", "Datepicker", "Tab"], { once: true });



// Import a specific module into 4X once and run the associated callback, then immediately execute the same callback every time the same statement is run without reloading the external resource again.

$A.import("Accordion", // Specifies the referenced module file name within the folder "/4X/Modules/" to be dynamically loaded.

  {

    name: "AccordionModule", // Specify a unique identifier for the import statement.

    props: {

      // Optionally set properties and methods to pass into the newly loaded module.

    },

    // Prevent the call function from executing until after the page finishes loading.

    defer: true,

    call: function(props) {

      // Execute $A.setAccordion() statement after the module code is loaded.

    }

  }

);