About Shared

The Shared folder contains functionality that is shared among all Ninja Forms plugins. It is intended to be a resource that simplifies the code of any single integrating plugin such that the plugin focuses solely on what makes it unique from other plugins. Classes in the Shared folder are aware of Ninja Forms and Wordpress, but nothing else. Integrating plugins can use Shared classes without needing to make requests of Ninja Forms or Wordpress directly, and are thus isolated for unit testing.

Class Organization

Classes within Shared are organized by the type of functionality each provides; understanding this organization helps one find the specific code needed for a given task.

Handlers

Handlers perform a specific task or very limited collection of tasks. These classes almost always have a single public method ->handle() into which well-defined properties are passed and the remaining functionality is handled within. Handler classes that do have other public methods are usually for actions and hooks requiring public access, but these methods aren't used directly by integrating plugins.

NOTE: FormAction class does not follow this structure, and it probably belongs in a different group, but I don't know where.

Entities

Entities define and structure data to be passed among other classes. Usually, the underlying data is an array and can be initiated from a configuration file. Type declarations on public methods such as getters and setters ensure the integrity of the data.

Contracts

Contracts specify what public methods must be defined along with the property type requirements in and out of those methods. Most of the integrating plugins' classes that use the Shared directory directly will be held to these contracts.

Abstracts

Abstracts provide code that is shared among multiple child classes. Often, it simplifies the implementation of a contract by handling the underlying functionality that is not unique to any single implementation, isolating into abstract methods the unique functionality required by the children

Templates

Templates output scripts from which content is constructed in Marionnette. See the TemplateAutobuild section for automatic, dynamic template building.

Functional Groups

Introductory comments...

Creating and Registering Actions

To create and register an action, first create an action configuration array and a new child class of Abstracts\FormActionProcessor, e.g. FormActionProcessorChild. You will be required to add a single method to your child class = processSubmissionData(). The submission data is prepared into a protected property submissionData and this data is structured into an array that matches the structure in your action configuration.
Thus with only your configuration array and a single method, you can create an entire plugin. Of course, to reduce complexity, you can call other classes and methods as desired. To register your action, create an instance of Handlers\FormAction using your child FormActionProcessor. Create an instance of ActionRegistrar and call the handle method, passing in the instantiated FormAction

$myConfigurationArray = array(...);

class FormActionProcessorChild extends Abstracts\FormActionProcessor{
    protected function processSubmissionData(){
        // Do something with $this->submissionData, it's already structured for you
    }
}


$myFormActionProcessor = new FormActionProcessorChild($myConfigurationArray);

$myFormAction = new Handlers\FormAction($myFormActionProcessor);

(new Handlers\ActionRegistrar)->handle($myFormAction);

The above code can be run at Wordpress' plugins_loaded hook and it will automatically register your action and run your processSubmissionData method. Should your action require access to external functionality not avaiable at plugins_loaded, you can create a factory class and inject it into your FormActionProcessor, which will call the functionality required at run time.

Registering Plugin Settings with Linked AJAX

Ninja Forms' plugin settings registration very straightforward to begin with; two basic arrays are all that is required to set up a function settings section with automatic storage of values. The shared library builds upon that with enhanced functionality that simplifies the setup of a user interface including AJAX calls and dynamic setting of values (as opposed to the statically configured values from the original array),

1. Instantiate an instance of Handlers\PluginSettingsRegistrar with your configured array. This automatically adds the array details to the required filters. For statically configured settings, this is all that is required.
2. If you wish to dynamically modify the settings at run time, create child class that extends Abstracts\FilterSettingsOutput. To instantiate your class, you will pass in a FilterTag string property, which is conveniently provided by the PluginSettingsRegistrar. The PluginSettingsRegistrar will apply a filter at run time using that filter tag; meanwhile, Abstracts\FilterSettingsOutput adds itself to that filter. In your child class, you have one method required, and in that method you can modify the settings array however needed for output.
3. To add AJAX functionality, create a child of Abstracts\AjaxHandler and set up the four properties required. Also set up a JS file to handle the JS functionality. Instantiating your class will automatically register and enqueue your script along with passing your data to and from the JS file.

Data Model Provider

Ninja Forms has some standard data structures for output; this class provides that standard data from other sources. For example, if one has a collection of data, an indexed array of associative arrays, this class can construct a common structure such as label value pairs that can readily be used to construct a dropdown select list.

The file CreateChainedContact.php demonstrates how to use this. In the method finalizeActionSettings, a variable $groups is set using the civiObjectsFactory to provide a groups object that provides a collection of records. Immdediately following the request for the collection, the dataModelProvider constructs label-value pairs, which are set at the action settings select list dropdown. Note how little data manipulation is required within this class; the provided objects standardize the data structure such that this class need only make the appropriate requests to construct the drop down list for the action.

Template Autobuilder

Output of action settings require a template. NF Core has some pre-built templates and plugins can provide their own templates for customized output. Because the CiviCRM plugin has multiple settings, each requiring its own custom template, the plugin contains a TemplateAutobuild class that builds and registers the template directly from the action configuration array.. To use the autobuilder for a given action setting, ass a setting key-value pair of 'autobuild'=>true and for each column in the setting, add a new setting of 'autobuild_label'=>enter_your_label_here. The TemplateAutobuild class will generate a single column template of the columns in the configuration.
See tag-contact-action-settings.php for a working example.