Documentation

CRM_Contact_Import_Form_DataSource extends CRM_Import_Form_DataSource
in package

CRM

This class delegates to the chosen DataSource to grab the data to be imported.

Constants

ATTR_SPACING = '     ': Constants for attributes for various form elements attempt to standardize on the number of variations that we use of the below form elements
CB_PREFIX = 'mark_x_': All checkboxes are defined with a common prefix. This allows us to have the same javascript to check / clear all the checkboxes etc If u have multiple groups of checkboxes, you will need to give them different ids to avoid potential name collision
CB_PREFIX_LEN = 7: All checkboxes are defined with a common prefix. This allows us to have the same javascript to check / clear all the checkboxes etc If u have multiple groups of checkboxes, you will need to give them different ids to avoid potential name collision
CB_PREFIY = 'mark_y_': All checkboxes are defined with a common prefix. This allows us to have the same javascript to check / clear all the checkboxes etc If u have multiple groups of checkboxes, you will need to give them different ids to avoid potential name collision
CB_PREFIZ = 'mark_z_': All checkboxes are defined with a common prefix. This allows us to have the same javascript to check / clear all the checkboxes etc If u have multiple groups of checkboxes, you will need to give them different ids to avoid potential name collision

Properties

$_action : int: (QUASI-PROTECTED) The mode of operation for this form
$_defaults : array<string|int, mixed>: The default values for the form.
$_options : mixed: (QUASI-PROTECTED) The options passed into this form
$_paymentProcessorIDs : array<string|int, mixed>: Available payment processors (IDS).
$ajaxResponse : array<string|int, mixed>: What to return to the client if in ajax mode (snippet=json)
$controller : CRM_Core_Controller
$expectedSmartyVariables : array<string|int, string>: Variables smarty expects to have set.
$html5Types : array<string|int, mixed>: Extra input types we support via the "add" method
$submitOnce : bool
$urlPath : array<string|int, mixed>: Url path used to reach this page
$_actionButtonName : string: Name of action button
$_name : string: The name of this form
$_paymentProcessorID : int: Default or selected processor id.
$_paymentProcessors : array<string|int, mixed>: Available payment processors.
$_renderer : object: The renderer used for this form
$_state : object: The state object that this form belongs to
$_template : CRM_Core_Smarty: Cache the smarty template for efficiency reasons
$_title : string: The title of this form
$context : string: Context of the form being loaded.
$dataSourceDefaults : array<string|int, mixed>: Default values for datasource fields.
$exportedValues : array<string|int, mixed>: Values submitted by the user.
$isDisplayTimeInDateFormats : bool: Should the text describing date formats include the time.
$isQuickFormMode : bool: Is the code being accessed in QuickForm mode.
$mappingName : string: Name of the import mapping (civicrm_mapping).
$optionalQuickFormElements : array<string|int, mixed>: Quick form elements which are conditionally added to the form.
$parser : CRM_Import_Parser
$savedMappingID : int: The id of the saved mapping being updated.
$submittableFields : array<string|int, string>: Fields that may be submitted on any form in the flow.
$submittableMoneyFields : array<string|int, mixed>: Monetary fields that may be submitted.
$templateID : int
$templateValues : array<string|int, mixed>: Values loaded from a saved UserJob template.
$unsavedChangesWarn : bool: Indicate if this form should warn users of unsaved changes
$userJob : array<string|int, mixed>: User job details.
$userJobID : int: User job id.
$authenticatedContactID : int: The contact ID that has been authenticated and can be used for checking permissions.
$isValidated : true

Methods

__construct() : CRM_Core_Form: Constructor for the basic form page.
add() : HTML_QuickForm_Element: Simple easy to use wrapper around addElement.
addAutocomplete() : HTML_QuickForm_Element
addAutoSelector() : mixed: Add autoselector field -if user has permission to view contacts If adding this to a form you also need to add to the tpl e.g
addButtons() : mixed: Add default Next / Back buttons.
addChainSelect() : HTML_QuickForm_Element: Create a chain-select target field. All settings are optional; the defaults usually work.
addCheckBox() : mixed
addCIDZeroOptions() : mixed: Add the options appropriate to cid = zero - ie. autocomplete
addClass() : mixed: Add one or more css classes to the form.
addCurrency() : mixed: Add currency element to the form.
addDate() : mixed: Add date.
addDatePickerRange() : mixed: Add a search for a range using date picker fields.
addDateRange() : mixed
addDateTime() : mixed: Function that will add date and time.
addDefaultButtons() : mixed: Simple shell that derived classes can call to add buttons to the form with a customized title for the main Submit
addEntityRef() : HTML_QuickForm_Element: Create a single or multiple entity ref field.
addExpectedSmartyVariable() : void: Add an expected smarty variable to the array.
addExpectedSmartyVariables() : void: Add an expected smarty variable to the array.
addField() : mixed: Adds a field based on metadata.
addMoney() : HTML_QuickForm_Element: Add a currency and money element to the form.
addOptionalQuickFormElement() : void: Add an optional element to the optional elements array.
addProfileSelector() : mixed: Add a widget for selecting/editing/creating/copying a profile form
addRadio() : HTML_QuickForm_group
addRules() : mixed: This is a virtual function that adds group and global rules to the form.
addSelect() : HTML_QuickForm_Element: Adds a select based on field metadata.
addTaskMenu() : mixed: Add actions menu to results form.
addUploadElement() : mixed
addYesNo() : mixed
allowAjaxSubmit() : mixed: Sets form attribute.
append() : mixed: Appends values to template variables.
assign() : mixed: Assign value to name in template.
assign_by_ref() : mixed: Assign value to name in template by reference.
assignBillingName() : string: Assign billing name to the template.
assignBillingType() : mixed: Assign billing type id to bltID.
assignCiviimportVariables() : void: Assign values for civiimport.
assignVariables() : mixed: Assign an array of variables to the form/tpl
buildForm() : mixed: Core function that builds the form.
buildQuickForm() : void: Build the form object.
cancelAction() : mixed: Function that can be defined in Form to override or.
canUseAjaxContactLookups() : bool
error() : mixed: Error reporting mechanism.
get() : mixed: Get the variable from the form scope.
get_template_vars() : array<string|int, mixed>: Returns an array containing template variables.
getAction() : int|null: Getter for action.
getAuthenticatedContactID() : int: Get the authenticated contact ID.
getCompleteTitle() : string
getContactID() : int|null: Get the contact id that the form is being submitted for.
getContext() : string
getCurrency() : string: Get the currency for the form.
getDefaultContext() : mixed: Classes extending CRM_Core_Form should implement this method.
getDefaultEntity() : mixed: Classes extending CRM_Core_Form should implement this method.
getEntity() : mixed
getHeaderPatterns() : array<string|int, mixed>: Get the data patterns to pattern match the incoming data.
getHookedTemplateFileName() : mixed: A wrapper for getTemplateFileName.
getLoggedInUserContactID() : int|false: Get the contact id of the logged in user.
getName() : string: Getter function for Name.
getOptionalQuickFormElements() : array<string|int, mixed>: Get any quick-form elements that may not be present in the form.
getPaymentProcessorID() : int|null
getProfileDefaults() : array<string|int, mixed>: Set default values on form for given contact (or no contact defaults)
getRenderer() : CRM_Core_Form_Renderer: Getter function for renderer.
getRequestedContactID() : int|null: Get the contact ID that has been requested (via url or form value).
getRootTitle() : null
getSavedMappingID() : int|null: Get the mapping ID that is being loaded.
getState() : object: Getter function for State.
getStateType() : int: Getter function for StateType.
getSubmittedValue() : mixed|null: Get the submitted value, accessing it from whatever form in the flow it is submitted on.
getSubmittedValues() : array<string|int, mixed>: Get values submitted by the user.
getTemplate() : CRM_Core_Smarty
getTemplateFileName() : string: Use the form name to create the tpl file name.
getTemplateID() : int|null: Get the template ID from the url, if available.
getTemplateVars() : mixed: Get the value/s assigned to the Template Engine (Smarty).
getTitle() : string: Return a descriptive name for the page, used in wizard header
getTrackingSummary() : array<string|int, mixed>
getUFGroupIDs() : array<string|int, mixed>: Get the active UFGroups (profiles) on this form Many forms load one or more UFGroups (profiles).
getUserJobID() : int|null
getUserJobType() : string: Get the name of the type to be stored in civicrm_user_job.type_id.
getVar() : mixed
isFormInEditMode() : bool: Is the form in edit mode.
isFormInViewMode() : bool: Is the form in view mode.
mainProcess() : mixed: Main process wrapper.
outputCSV() : void: Outputs and downloads the csv of outcomes from an import job.
overrideExtraTemplateFileName() : string: Default extra tpl file basically just replaces .tpl with .extra.tpl.
postProcess() : mixed: Common postProcessing.
postProcessHook() : mixed: The postProcess hook is typically called by the framework.
preProcess() : void: Set variables up before form is built.
preventAjaxSubmit() : mixed: Sets form attribute.
registerFileField() : void: Register a field with quick form as supporting a file upload.
registerRules() : mixed: Register all the standard rules that most forms potentially use.
removeFileRequiredRules() : mixed
resetValues() : mixed
set() : mixed: Store the variable with the value in the form scope.
setAction() : mixed: Setter for action.
setContext() : mixed: Set context variable.
setDataSourceDefaults() : self: Set dataSource default values.
setDefaultValues() : array<string|int, mixed>: Set the default values of various form elements.
setOptions() : mixed: Setter function for options.
setPageTitle() : void: Sets page title based on entity and action.
setPurifiedDefaults() : mixed
setSavedMappingID() : CRM_Import_Forms
setSelectedChild() : mixed: Set the active tab
setTemplateDefaults() : array<string|int, mixed>: Load default values from the relevant template if one is passed in via the url.
setTitle() : mixed: Setter function for title.
setUserJobID() : void: Set user job ID.
setVar() : mixed
toSmarty() : string: Render form and return contents.
validate() : bool: Performs the server side validation.
validateMandatoryFields() : mixed: Helper function to verify that required fields have been filled.
addContactTypeSelector() : mixed: A long-winded way to add one radio element to the form.
assignPaymentProcessor() : mixed: This if a front end form function for setting the payment processor.
buildAllowedDateFormats() : void: Build the date-format form.
buildDataSourceFields() : void: Allow the datasource class to add fields.
createTemplateJob() : void
createUserJob() : int: Create a user job to track the import.
flushDataSource() : void: Flush datasource on re-submission of the form.
formatParamsForPaymentProcessor() : array<string|int, mixed>: Format the fields in $this->_params for the payment processor.
getApiAction() : mixed: Based on form action, return a string representing the api action.
getAuthenticatedCheckSumContactID() : int: Get the contact ID authenticated as a valid by checksum.
getAvailableFields() : array<string|int, mixed>: Get the fields available for import selection.
getBaseEntity() : string: Get the base entity for the import.
getColumnHeaders() : array<string|int, mixed>: Get column headers for the datasource or empty array if none apply.
getContactIDIfAccessingOwnRecord() : int|false: Get the contact if from the url, using the checksum or the cid if it is the logged in user.
getContactSubType() : string|null: Get the contact sub type selected for the import (on the datasource form).
getContactType() : string: Get the contact type selected for the import (on the datasource form).
getDataRows() : array<string|int, mixed>|int: Get x data rows from the datasource.
getDataSourceClassName() : string|null: Get the name of the datasource class.
getDataSourceFields() : array<string|int, mixed>: Allow the datasource class to add fields.
getDataSourceObject() : DataSourceInterface|null: Get the relevant datasource object.
getDataSources() : array<string|int, mixed>: Get the available datasource.
getDefaultDataSource() : string: Get the default datasource.
getDownloadURL() : string: Get the url to download the relevant csv file.
getErrorMessage() : string: Get an error message to assign to the template.
getFields() : array<string|int, mixed>: Get the fields available for import selection.
getFieldsToExcludeFromPurification() : array<string|int, mixed>: Override this in a subclass to prevent fields intended to contain "raw html" from getting broken. E.g. system message templates
getHighlightedFields() : array<string|int, mixed>: Get the fields to be highlighted in the UI.
getImportEntities() : array<string|int, mixed>: Get the fields available for import selection.
getMappedFieldLabels() : array<string|int, mixed>: Get the mapped fields as an array of labels.
getMappingName() : string
getNumberOfColumns() : int: Get the number of importable columns in the data source.
getOutputColumnsHeaders() : array<string|int, mixed>: Get the column headers for the output csv.
getOutputRows() : array<string|int, mixed>: Get the datasource rows ready for csv output.
getParser() : CRM_Contact_Import_Parser_Contact|CRM_Contribute_Import_Parser_Contribution: Get an instance of the parser class.
getRowCount() : int: Get the number of rows with the specified status.
getSubmittableFields() : array<string|int, string>: Get the fields that can be submitted in the Import form flow.
getTemplateJob() : array<string|int, mixed>|null: Get the UserJob Template, if it exists.
getTranslatedEntities() : string: Get the import entity plural (translated).
getTranslatedEntity() : string: Get the import entity (translated).
getUserJob() : array<string|int, mixed>: Get User Job.
getUserJobInfo() : array<string|int, mixed>: Get information about the user job parser.
getUserJobSubmittedValues() : array<string|int, mixed>: Get submitted values stored in the user job.
handlePreApproval() : mixed: Handle pre approval for processors.
hasImportableRows() : bool: Are there valid rows to import.
isFilterContactFields() : bool: Should contact fields be filtered which determining fields to show.
isFormInViewOrEditMode() : bool: Is the form in view or edit mode.
isImportDataUploaded() : bool: Is the data already uploaded.
isSkipDuplicates() : bool: Did the user specify duplicates should be skipped and not imported.
isSkipExisting() : bool: Has the user chosen to update existing records.
isUpdateExisting() : bool: Has the user chosen to update existing records.
isUpdateTemplateJob() : bool: Is the user wanting to update the template / mapping.
prepareParamsForPaymentProcessor() : array<string|int, mixed>: Format the fields in $params for the payment processor.
preProcessPaymentOptions() : mixed: Handle Payment Processor switching for contribution and event registration forms.
processDatasource() : void: Process the datasource submission - setting up the job and data source.
pushUrlToUserContext() : void: Push path to the userContext (defaults to current url path).
setContactID() : null|int: Get contact iD for a form object.
setTranslatedFields() : mixed: Set translated fields.
storeFormValues() : void: Store form values.
updateTemplateUserJob() : void
updateUserJobMetadata() : void
validateAuthenticatedCheckSumContactID() : int: Verify that a contact ID is authenticated as a valid contact by checksum
formatReferenceFieldAttributes() : mixed
instantiateDataSource() : void: Instantiate the datasource.
preProcessChainSelectFields() : mixed: Set options and attributes for chain select fields based on the controlling field's value
selectOrAnyPlaceholder() : string: Handles a repeated bit supplying a placeholder for entity selection
strToPattern() : mixed
validateChainSelectFields() : mixed: Validate country / state / county match and suppress unwanted "required" errors

ATTR_SPACING

Constants for attributes for various form elements attempt to standardize on the number of variations that we use of the below form elements


    public
        string
    ATTR_SPACING
    = '&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'

CB_PREFIX

All checkboxes are defined with a common prefix. This allows us to have the same javascript to check / clear all the checkboxes etc If u have multiple groups of checkboxes, you will need to give them different ids to avoid potential name collision


    public
        string|int
    CB_PREFIX
    = 'mark_x_'

CB_PREFIX_LEN


    public
        string|int
    CB_PREFIX_LEN
    = 7

CB_PREFIY


    public
        string|int
    CB_PREFIY
    = 'mark_y_'

CB_PREFIZ


    public
        string|int
    CB_PREFIZ
    = 'mark_z_'

$_action

(QUASI-PROTECTED) The mode of operation for this form


    public
        int
    $_action

This field should marked protected and is not generally intended for external callers, but some edge-cases do use it.

$_defaults

The default values for the form.


    public
        array<string|int, mixed>
    $_defaults
     = []

$_options

(QUASI-PROTECTED) The options passed into this form


    public
        mixed
    $_options
     = \NULL

This field should marked protected and is not generally intended for external callers, but some edge-cases do use it.

$_paymentProcessorIDs

Available payment processors (IDS).


    public
        array<string|int, mixed>
    $_paymentProcessorIDs

As part of trying to consolidate various payment pages we store processors here & have functions at this level to manage them. An alternative would be to have a separate Form that is inherited by all forms that allow payment processing.

An array of the IDS available on this form.

$ajaxResponse

What to return to the client if in ajax mode (snippet=json)


    public
        array<string|int, mixed>
    $ajaxResponse
     = []

$controller


    public
        CRM_Core_Controller
    $controller

$expectedSmartyVariables

Variables smarty expects to have set.


    public
        array<string|int, string>
    $expectedSmartyVariables
     = [
    // in CMSPrint.tpl
    'breadcrumb',
    'pageTitle',
    'urlIsPublic',
    'isDeleted',
    // in 'body.tpl
    'suppressForm',
    'beginHookFormElements',
    // required for footer.tpl
    'contactId',
    // required for info.tpl
    'infoMessage',
    'infoTitle',
    'infoType',
    'infoOptions',
    // required for attachmentjs.tpl
    'context',
    // FormButtons.tpl (adds buttons to forms).
    'linkButtons',
    // Required for contactFooter.tpl.
    // See CRM_Activity_Form_ActivityTest:testInboundEmailDisplaysWithLineBreaks.
    'external_identifier',
    'lastModified',
    'created_date',
    'changeLog',
    // Required for footer.tpl,
    // See CRM_Activity_Form_ActivityTest:testInboundEmailDisplaysWithLineBreaks.
    'footer_status_severity',
    // Required for some profiles (e.g on the Main page of the contribution form flow).
    // A bit tricky to add closer to the usage due to conditionality of inclusion
    'showCMS',
]

We ensure these are assigned (value = NULL) when Smarty is instantiated in order to avoid e-notices / having to use empty or isset in the template layer.

$html5Types

Extra input types we support via the "add" method


    public
    static    array<string|int, mixed>
    $html5Types
     = ['number', 'url', 'email', 'color']

$submitOnce


    public
        bool
    $submitOnce
     = \FALSE

$urlPath

Url path used to reach this page


    public
        array<string|int, mixed>
    $urlPath
     = []

$_actionButtonName

Name of action button


    protected
        string
    $_actionButtonName

$_name

The name of this form


    protected
        string
    $_name

$_paymentProcessorID

Default or selected processor id.


    protected
        int
    $_paymentProcessorID

$_paymentProcessors

Available payment processors.


    protected
        array<string|int, mixed>
    $_paymentProcessors

As part of trying to consolidate various payment pages we store processors here & have functions at this level to manage them.

An array of payment processor details with objects loaded in the 'object' field.

$_renderer

The renderer used for this form


    protected
        object
    $_renderer

$_state

The state object that this form belongs to


    protected
        object
    $_state

$_template

Cache the smarty template for efficiency reasons


    protected
    static    CRM_Core_Smarty
    $_template

$_title

The title of this form


    protected
        string
    $_title
     = \NULL

$context

Context of the form being loaded.


    protected
        string
    $context

'event' or null

$dataSourceDefaults

Default values for datasource fields.


    protected
        array<string|int, mixed>
    $dataSourceDefaults
     = []

$exportedValues

Values submitted by the user.


    protected
        array<string|int, mixed>
    $exportedValues
     = []

These values have been checked for injection per https://pear.php.net/manual/en/package.html.html-quickform.html-quickform.exportvalues.php and are as submitted.

Once set this array should be treated as read only.

$isDisplayTimeInDateFormats

Should the text describing date formats include the time.


    protected
        bool
    $isDisplayTimeInDateFormats
     = \FALSE

This is used to alter the displayed text to that perceived to be more useful. e.g. for contacts it might be birthdate so including time is confusing but activities would more likely use them.

$isQuickFormMode

Is the code being accessed in QuickForm mode.


    protected
        bool
    $isQuickFormMode
     = \TRUE

If false, ie functions being called to support the angular form, then we 'quick-form-ify' the fields with dots over to double underscores.

$mappingName

Name of the import mapping (civicrm_mapping).


    protected
        string
    $mappingName

$optionalQuickFormElements

Quick form elements which are conditionally added to the form.


    protected
        array<string|int, mixed>
    $optionalQuickFormElements
     = []

Elements in this array will be added to the form at the end if not present so that smarty does not e-notice on things like '{if $form.group}' when 'group' is not added to the form (e.g when no groups exist).

$parser


    protected
        CRM_Import_Parser
    $parser

$savedMappingID

The id of the saved mapping being updated.


    protected
        int
    $savedMappingID

Note this may not be the same as the saved mapping being used to load data. Use the getSavedMappingID function to access & any extra logic can be added in there.

$submittableFields

Fields that may be submitted on any form in the flow.


    protected
        array<string|int, string>
    $submittableFields
     = [
    'contactType' => 'DataSource',
    'contactSubType' => 'DataSource',
    'dateFormats' => 'DataSource',
    'savedMapping' => 'DataSource',
    'dataSource' => 'DataSource',
    'use_existing_upload' => 'DataSource',
    'dedupe_rule_id' => 'DataSource',
    'onDuplicate' => 'DataSource',
    'disableUSPS' => 'DataSource',
    'doGeocodeAddress' => 'DataSource',
    'multipleCustomData' => 'DataSource',
    // Note we don't add the save mapping instructions for MapField here
    // (eg 'updateMapping') - as they really are an action for that form
    // rather than part of the mapping config.
    'mapper' => 'MapField',
]

$submittableMoneyFields

Monetary fields that may be submitted.


    protected
        array<string|int, mixed>
    $submittableMoneyFields
     = []

Any fields in this list will be converted to non-localised format if retrieved by getSubmittedValue

$templateID


    protected
        int
    $templateID

$templateValues

Values loaded from a saved UserJob template.


    protected
        array<string|int, mixed>
    $templateValues
     = []

Within Civi-Import it is possible to save a UserJob with is_template = 1.

$unsavedChangesWarn

Indicate if this form should warn users of unsaved changes


    protected
        bool
    $unsavedChangesWarn

$userJob

User job details.


    protected
        array<string|int, mixed>
    $userJob

This is the relevant row from civicrm_user_job.

$userJobID

User job id.


    protected
        int
    $userJobID

This is the primary key of the civicrm_user_job table which is used to track the import.

$authenticatedContactID

The contact ID that has been authenticated and can be used for checking permissions.


    private
        int
    $authenticatedContactID

It could be a combination of cid in the url plus a checksum or the logged in user. Importantly it can be used to run permission checks on.

$isValidated


    private
        true
    $isValidated
     = \FALSE

__construct()

Constructor for the basic form page.


    public
                    __construct([object $state = NULL ][, int $action = CRM_Core_Action::NONE ][, string $method = 'post' ][, string $name = NULL ]) : CRM_Core_Form

We should not use QuickForm directly. This class provides a lot of default convenient functions, rules and buttons

Parameters

$state : object = NULL: State associated with this form.
$action : int = CRM_Core_Action::NONE: The mode the form is operating in (None/Create/View/Update/Delete)
$method : string = 'post': The type of http method used (GET/POST).
$name : string = NULL: The name of the form if different from class name.

Return values

CRM_Core_Form

add()

Simple easy to use wrapper around addElement.


    public
                &    add(string $type, string $name[, string $label = '' ][, array<string|int, mixed> $attributes = NULL ][, bool $required = FALSE ][, array<string|int, mixed> $extra = NULL ]) : HTML_QuickForm_Element

Deal with simple validation rules.

Parameters

$type : string
$name : string
$label : string = ''
$attributes : array<string|int, mixed> = NULL: (options for select elements)
$required : bool = FALSE
$extra : array<string|int, mixed> = NULL: (attributes for select elements). For datepicker elements this is consistent with the data from CRM_Utils_Date::getDatePickerExtra

Return values

HTML_QuickForm_Element —

Could be an error object

addAutocomplete()


    public
                    addAutocomplete(string $name[, string $label = '' ][, array<string|int, mixed> $props = [] ][, bool $required = FALSE ]) : HTML_QuickForm_Element

Parameters

$name : string
$label : string = ''
$props : array<string|int, mixed> = []
$required : bool = FALSE

Return values

HTML_QuickForm_Element

addAutoSelector()

Add autoselector field -if user has permission to view contacts If adding this to a form you also need to add to the tpl e.g


    public
                    addAutoSelector([array<string|int, mixed> $profiles = [] ][, array<string|int, mixed> $autoCompleteField = [] ]) : mixed

{if !empty($selectable)}

{$form.select_contact.label}

{$form.select_contact.html}

{/if}

Parameters

$profiles : array<string|int, mixed> = []

Ids of profiles that are on the form (to be autofilled).

$autoCompleteField : array<string|int, mixed> = []

name_field
id_field
url (for ajax lookup)

addButtons()

Add default Next / Back buttons.


    public
                    addButtons(array<string|int, mixed> $params) : mixed

Parameters

$params : array<string|int, mixed>: Array of associative arrays in the order in which the buttons should be displayed. The associate array has 3 fields: 'type', 'name' and 'isDefault' The base form class will define a bunch of static arrays for commonly used formats.

addChainSelect()

Create a chain-select target field. All settings are optional; the defaults usually work.


    public
                    addChainSelect(string $elementName[, array<string|int, mixed> $settings = [] ]) : HTML_QuickForm_Element

Parameters

$elementName : string
$settings : array<string|int, mixed> = []

Return values

HTML_QuickForm_Element

addCheckBox()


    public
                    addCheckBox(int $id, string $title, array<string|int, mixed> $values[, null $other = NULL ][, null $attributes = NULL ][, null $required = NULL ][, null $javascriptMethod = NULL ][, string $separator = '<br />' ][, bool $flipValues = FALSE ]) : mixed

Parameters

$id : int
$title : string
$values : array<string|int, mixed>
$other : null = NULL
$attributes : null = NULL
$required : null = NULL
$javascriptMethod : null = NULL
$separator : string = '<br />'
$flipValues : bool = FALSE

addCIDZeroOptions()

Add the options appropriate to cid = zero - ie. autocomplete


    public
                    addCIDZeroOptions() : mixed

addClass()

Add one or more css classes to the form.


    public
                    addClass(string $className) : mixed

Parameters

$className : string

addCurrency()

Add currency element to the form.


    public
                    addCurrency([string $name = 'currency' ][, string $label = NULL ][, bool $required = TRUE ][, string $defaultCurrency = NULL ][, bool $freezeCurrency = FALSE ][, bool $setDefaultCurrency = TRUE ]) : mixed

Parameters

$name : string = 'currency'
$label : string = NULL
$required : bool = TRUE
$defaultCurrency : string = NULL
$freezeCurrency : bool = FALSE
$setDefaultCurrency : bool = TRUE

addDate()

Add date.


    public
                    addDate(string $name, string $label[, bool $required = FALSE ][, array<string|int, mixed> $attributes = NULL ]) : mixed

Use $this->add('datepicker', ...) instead.

Parameters

$name : string: Name of the element.
$label : string: Label of the element.
$required : bool = FALSE: True if required.
$attributes : array<string|int, mixed> = NULL: Key / value pair.

addDatePickerRange()

Add a search for a range using date picker fields.


    public
                    addDatePickerRange(string $fieldName, string $label[, bool $isDateTime = FALSE ][, bool $required = FALSE ][, string $fromLabel = 'From' ][, string $toLabel = 'To' ][, array<string|int, mixed> $additionalOptions = [] ][, string $to = '_high' ][, string $from = '_low' ]) : mixed

Parameters

$fieldName : string
$label : string
$isDateTime : bool = FALSE: Is this a date-time field (not just date).
$required : bool = FALSE
$fromLabel : string = 'From'
$toLabel : string = 'To'
$additionalOptions : array<string|int, mixed> = []
$to : string = '_high': string to append to the to field.
$from : string = '_low': string to append to the from field.

addDateRange()


    public
                    addDateRange(string $name[, string $from = '_from' ][, string $to = '_to' ][, string $label = 'From:' ][, string $dateFormat = 'searchDate' ][, bool $required = FALSE ][, bool $displayTime = FALSE ]) : mixed

Use $this->addDatePickerRange() instead.

Parameters

$name : string
$from : string = '_from'
$to : string = '_to'
$label : string = 'From:'
$dateFormat : string = 'searchDate'
$required : bool = FALSE
$displayTime : bool = FALSE

addDateTime()

Function that will add date and time.


    public
                    addDateTime(string $name, string $label[, bool $required = FALSE ][, array<string|int, mixed> $attributes = NULL ]) : mixed

Use $this->add('datepicker', ...) instead.

Parameters

$name : string
$label : string
$required : bool = FALSE
$attributes : array<string|int, mixed> = NULL

addDefaultButtons()

Simple shell that derived classes can call to add buttons to the form with a customized title for the main Submit


    public
                    addDefaultButtons(string $title[, string $nextType = 'next' ][, string $backType = 'back' ][, bool|string $submitOnce = FALSE ]) : mixed

Parameters

$title : string: Title of the main button.
$nextType : string = 'next': Button type for the form after processing.
$backType : string = 'back'
$submitOnce : bool|string = FALSE

addEntityRef()

Create a single or multiple entity ref field.


    public
                    addEntityRef(string $name[, string $label = '' ][, array<string|int, mixed> $props = [] ][, bool $required = FALSE ]) : HTML_QuickForm_Element

Parameters

$name : string

$label : string = ''

$props : array<string|int, mixed> = []

Mix of html and widget properties, including:.

select - params to give to select2 widget
entity - defaults to Contact
create - can the user create a new entity on-the-fly? Set to TRUE if entity is contact and you want the default profiles, or pass in your own set of links. @see CRM_Campaign_BAO_Campaign::getEntityRefCreateLinks for format note that permissions are checked automatically
api - array of settings for the getlist api wrapper note that it accepts a 'params' setting which will be passed to the underlying api
placeholder - string
multiple - bool
class, etc. - other html properties

$required : bool = FALSE

Return values

HTML_QuickForm_Element

addExpectedSmartyVariable()

Add an expected smarty variable to the array.


    public
                    addExpectedSmartyVariable(string $elementName) : void

Parameters

$elementName : string

addExpectedSmartyVariables()

Add an expected smarty variable to the array.


    public
                    addExpectedSmartyVariables(array<string|int, mixed> $elementNames) : void

Parameters

$elementNames : array<string|int, mixed>

addField()

Adds a field based on metadata.


    public
                    addField(mixed $name[, array<string|int, mixed> $props = [] ][, bool $required = FALSE ][, bool $legacyDate = TRUE ]) : mixed

Parameters

$name : mixed

Field name to go on the form.

$props : array<string|int, mixed> = []

Mix of html attributes and special properties, namely.

entity (api entity name, can usually be inferred automatically from the form class)
name (field name - only needed if different from name used on the form)
option_url - path to edit this option list - usually retrieved automatically - set to NULL to disable link
placeholder - set to NULL to disable
multiple - bool
context - @see CRM_Core_DAO::buildOptionsContext

$required : bool = FALSE

$legacyDate : bool = TRUE

Temporary param to facilitate the conversion of fields to use the datepicker in a controlled way. To convert the field the jcalendar code needs to be removed from the tpl as well. That file is intended to be EOL.

Return values

mixed —

HTML_QuickForm_element void

addMoney()

Add a currency and money element to the form.


    public
                    addMoney(string $name, string $label[, bool $required = FALSE ][, array<string|int, mixed> $attributes = NULL ][, bool $addCurrency = TRUE ][, string $currencyName = 'currency' ][, string $defaultCurrency = NULL ][, bool $freezeCurrency = FALSE ]) : HTML_QuickForm_Element

Parameters

$name : string
$label : string
$required : bool = FALSE
$attributes : array<string|int, mixed> = NULL
$addCurrency : bool = TRUE
$currencyName : string = 'currency'
$defaultCurrency : string = NULL
$freezeCurrency : bool = FALSE

Return values

HTML_QuickForm_Element

addOptionalQuickFormElement()

Add an optional element to the optional elements array.


    public
                    addOptionalQuickFormElement(string $elementName) : void

These elements are assigned as empty (null) variables if there is no real field - allowing smarty to use them without notices.

Parameters

$elementName : string

addProfileSelector()

Add a widget for selecting/editing/creating/copying a profile form


    public
                    addProfileSelector(string $name, string $label, string $allowCoreTypes, string $allowSubTypes, array<string|int, mixed> $entities[, bool $default = FALSE ][, string $usedFor = NULL ]) : mixed

Parameters

$name : string: HTML form-element name.
$label : string: Printable label.
$allowCoreTypes : string: Only present a UFGroup if its group_type includes a subset of $allowCoreTypes; e.g. 'Individual', 'Activity'.
$allowSubTypes : string: Only present a UFGroup if its group_type is compatible with $allowSubypes.
$entities : array<string|int, mixed>
$default : bool = FALSE: //CRM-15427.
$usedFor : string = NULL

addRadio()


    public
                &    addRadio(string $name, string $title, array<string|int, mixed> $values[, array<string|int, mixed> $attributes = [] ][, string $separator = NULL ][, bool $required = FALSE ][, array<string|int, mixed> $optionAttributes = [] ]) : HTML_QuickForm_group

Parameters

$name : string

$title : string

$values : array<string|int, mixed>

$attributes : array<string|int, mixed> = []

$separator : string = NULL

$required : bool = FALSE

$optionAttributes : array<string|int, mixed> = []

Option specific attributes

Return values

HTML_QuickForm_group

addRules()

This is a virtual function that adds group and global rules to the form.


    public
                    addRules() : mixed

Keeping it distinct from the form to keep code small and localized in the form building code

addSelect()

Adds a select based on field metadata.


    public
                    addSelect(string $name[, array<string|int, mixed> $props = [] ][, bool $required = FALSE ]) : HTML_QuickForm_Element

TODO: This could be even more generic and widget type (select in this case) could also be read from metadata Perhaps a method like $form->bind($name) which would look up all metadata for named field

Parameters

$name : string

Field name to go on the form.

$props : array<string|int, mixed> = []

Mix of html attributes and special properties, namely.

entity (api entity name, can usually be inferred automatically from the form class)
field (field name - only needed if different from name used on the form)
option_url - path to edit this option list - usually retrieved automatically - set to NULL to disable link
placeholder - set to NULL to disable
multiple - bool
context - @see CRM_Core_DAO::buildOptionsContext

$required : bool = FALSE

Return values

HTML_QuickForm_Element

addTaskMenu()

Add actions menu to results form.


    public
                    addTaskMenu(array<string|int, mixed> $tasks) : mixed

Parameters

$tasks : array<string|int, mixed>

addUploadElement()


    public
                    addUploadElement(array<string|int, string>|string $elementName) : mixed

Parameters

$elementName : array<string|int, string>|string

addYesNo()


    public
                    addYesNo(string $id, string $title[, bool $allowClear = FALSE ][, bool $required = NULL ][, array<string|int, mixed> $attributes = [] ]) : mixed

Parameters

$id : string
$title : string
$allowClear : bool = FALSE
$required : bool = NULL
$attributes : array<string|int, mixed> = []

allowAjaxSubmit()

Sets form attribute.


    public
                    allowAjaxSubmit() : mixed

append()

Appends values to template variables.


    public
                    append(array<string|int, mixed>|string $tpl_var[, mixed $value = NULL ][, bool $merge = FALSE ]) : mixed

Parameters

$tpl_var : array<string|int, mixed>|string: the template variable name(s)
$value : mixed = NULL: The value to append.
$merge : bool = FALSE

assign()

Assign value to name in template.


    public
                    assign(string $var[, mixed $value = NULL ]) : mixed

Parameters

$var : string: Name of variable.
$value : mixed = NULL: Value of variable.

assign_by_ref()

Assign value to name in template by reference.


    public
                    assign_by_ref(string $var, mixed &$value) : mixed

since 5.72 will be removed around 5.84

Parameters

$var : string: Name of variable.
$value : mixed: Value of variable.

assignBillingName()

Assign billing name to the template.


    public
                    assignBillingName([array<string|int, mixed> $params = [] ]) : string

Parameters

$params : array<string|int, mixed> = []: Form input params, default to $this->_params.

Return values

string

assignBillingType()

Assign billing type id to bltID.


    public
                    assignBillingType() : mixed

assignCiviimportVariables()

Assign values for civiimport.


    public
                    assignCiviimportVariables() : void

I wanted to put this in the extension - but there are a lot of protected functions we would need to revisit and make public - do we want to?

assignVariables()

Assign an array of variables to the form/tpl


    public
                    assignVariables(array<string|int, mixed> $values, array<string|int, mixed> $keys) : mixed

Parameters

$values : array<string|int, mixed>: Array of [key => value] to assign to the form
$keys : array<string|int, mixed>: Array of keys to assign from the values array

buildForm()

Core function that builds the form.


    public
                    buildForm() : mixed

We redefine this function here and expect all CRM forms to build their form in the function buildQuickForm.

buildQuickForm()

Build the form object.


    public
                    buildQuickForm() : void

cancelAction()

Function that can be defined in Form to override or.


    public
                    cancelAction() : mixed

perform specific action on cancel action

canUseAjaxContactLookups()


    public
                    canUseAjaxContactLookups() : bool

Return values

bool

error()

Error reporting mechanism.


    public
                    error(string $message[, int $code = NULL ][, CRM_Core_DAO $dao = NULL ]) : mixed

Parameters

$message : string: Error Message.
$code : int = NULL: Error Code.
$dao : CRM_Core_DAO = NULL: A data access object on which we perform a rollback if non - empty.

get()

Get the variable from the form scope.


    public
                    get(string $name) : mixed

Parameters

$name : string: Name of the variable

get_template_vars()

Returns an array containing template variables.


    public
                    get_template_vars([string $name = NULL ]) : array<string|int, mixed>

since 5.69 will be removed around 5.93. use getTemplateVars.

Parameters

$name : string = NULL

Return values

array<string|int, mixed>

getAction()

Getter for action.


    public
                    getAction() : int|null

Return values

int|null

getAuthenticatedContactID()

Get the authenticated contact ID.


    public
                    getAuthenticatedContactID() : int

APIYes

This is either

a contact ID authenticated by checksum
the logged in user
0 for none.

Return values

int

getCompleteTitle()


    public
                    getCompleteTitle() : string

Return values

string

getContactID()

Get the contact id that the form is being submitted for.


    public
                    getContactID() : int|null

Return values

int|null

getContext()


    public
                    getContext() : string

Return values

string

getCurrency()

Get the currency for the form.


    public
                    getCurrency() : string

Return values

string

getDefaultContext()

Classes extending CRM_Core_Form should implement this method.


    public
                    getDefaultContext() : mixed

TODO: Merge with CRM_Core_DAO::buildOptionsContext($context) and add validation.

getDefaultEntity()

Classes extending CRM_Core_Form should implement this method.


    public
                    getDefaultEntity() : mixed

getEntity()


    public
                    getEntity() : mixed

getHeaderPatterns()

Get the data patterns to pattern match the incoming data.


    public
                    getHeaderPatterns() : array<string|int, mixed>

Return values

array<string|int, mixed>

getHookedTemplateFileName()

A wrapper for getTemplateFileName.


    public
                    getHookedTemplateFileName() : mixed

This includes calling the hook to prevent us from having to copy & paste the logic of calling the hook.

getLoggedInUserContactID()

Get the contact id of the logged in user.


    public
                    getLoggedInUserContactID() : int|false

Return values

int|false

getName()

Getter function for Name.


    public
                    getName() : string

getProfileDefaults()

Set default values on form for given contact (or no contact defaults)


    public
                    getProfileDefaults([mixed $profile_id = 'Billing' ][, int $contactID = NULL ]) : array<string|int, mixed>

Parameters

$profile_id : mixed = 'Billing': (can be id, or profile name).
$contactID : int = NULL

Return values

array<string|int, mixed>

getRenderer()

Getter function for renderer.


    public
                &    getRenderer() : CRM_Core_Form_Renderer

If renderer is not set create one and initialize it.

Return values

CRM_Core_Form_Renderer

getRequestedContactID()

Get the contact ID that has been requested (via url or form value).


    public
                    getRequestedContactID() : int|null

Ideally the forms would override this so only the cid in the url would be checked in the shared form function.

Return values

int|null

getRootTitle()


    public
                    getRootTitle() : null

Return values

null

getSavedMappingID()

Get the mapping ID that is being loaded.


    public
                    getSavedMappingID() : int|null

Return values

int|null

getState()

Getter function for State.


    public
                &    getState() : object

Return values

object

getStateType()

Getter function for StateType.


    public
                    getStateType() : int

Return values

int

getSubmittedValue()

Get the submitted value, accessing it from whatever form in the flow it is submitted on.


    public
                    getSubmittedValue(string $fieldName) : mixed|null

Parameters

$fieldName : string

Return values

mixed|null

getSubmittedValues()

Get values submitted by the user.


    public
                    getSubmittedValues() : array<string|int, mixed>

APIYes

Compared with $this->controller->exportValues this has a couple of changes

any fields declared in $this->submittableMoneyFields will be de-formatted first.
it is possible to store access fields from related forms if they are declared in getSubmittableFields(). This is notably used in imports to combine fields from the various screens & save the resulting 'submitted_values' to the UserJob.

Return values

array<string|int, mixed>

getTemplate()


    public
            static    &    getTemplate() : CRM_Core_Smarty

Return values

CRM_Core_Smarty

getTemplateFileName()

Use the form name to create the tpl file name.


    public
                    getTemplateFileName() : string

Return values

string

getTemplateID()

Get the template ID from the url, if available.


    public
                    getTemplateID() : int|null

Otherwise there are other possibilities...

it could already be saved to our UserJob.
on the DataSource form we could determine if from the savedMapping field (which will hold an ID that can be used to load it). We want to check this is coming from the POST (ie fresh)
on the MapField form it could be derived from the new mapping created from saveMapping + saveMappingName.

Return values

int|null

getTemplateVars()

Get the value/s assigned to the Template Engine (Smarty).


    public
                    getTemplateVars([string|null $name = NULL ]) : mixed

Parameters

$name : string|null = NULL

getTitle()

Return a descriptive name for the page, used in wizard header


    public
                    getTitle() : string

Return values

string

getTrackingSummary()


    public
                    getTrackingSummary() : array<string|int, mixed>

Return values

array<string|int, mixed>

getUFGroupIDs()

Get the active UFGroups (profiles) on this form Many forms load one or more UFGroups (profiles).


    public
                    getUFGroupIDs() : array<string|int, mixed>

This provides a standard function to retrieve the IDs of those profiles from the form so that you can implement things such as "is is_captcha field set on any of the active profiles on this form?"

NOT SUPPORTED FOR USE OUTSIDE CORE EXTENSIONS - Added for reCAPTCHA core extension.

Return values

array<string|int, mixed>

getUserJobID()


    public
                    getUserJobID() : int|null

Return values

int|null

getUserJobType()

Get the name of the type to be stored in civicrm_user_job.type_id.


    public
                    getUserJobType() : string

Return values

string

getVar()


    public
                    getVar(string $name) : mixed

use of this function assumes that an otherwise unavailable variable can be used form outside the class in question. However, the very fact it is otherwise unavailable means there is no contract that it will not be changed or become unused. This function is OK for temporary usage but should be accompanied with an effort to establish a more correct method or property tested hook / api interface if this is being done from outside of core.

Parameters

$name : string

isFormInEditMode()

Is the form in edit mode.


    public
                    isFormInEditMode() : bool

Helper function, notably for extensions implementing the buildForm hook, so that they can return early.

Return values

bool

isFormInViewMode()

Is the form in view mode.


    public
                    isFormInViewMode() : bool

Helper function, notably for extensions implementing the buildForm hook, so that they can return early.

Return values

bool

mainProcess()

Main process wrapper.


    public
                    mainProcess([bool $allowAjax = TRUE ]) : mixed

Implemented so that we can call all the hook functions.

Parameters

$allowAjax : bool = TRUE: FIXME: This feels kind of hackish, ideally we would take the json-related code from this function. and bury it deeper down in the controller

outputCSV()

Outputs and downloads the csv of outcomes from an import job.


    public
            static        outputCSV() : void

Function is accessed from civicrm/import/outcome path.

This gets the rows from the temp table that match the relevant status and output them as a csv.

overrideExtraTemplateFileName()

Default extra tpl file basically just replaces .tpl with .extra.tpl.


    public
                    overrideExtraTemplateFileName() : string

i.e. we do not override.

Return values

string

postProcess()

Common postProcessing.


    public
                    postProcess() : mixed

postProcessHook()

The postProcess hook is typically called by the framework.


    public
                    postProcessHook() : mixed

However in a few cases, the form exits or redirects early in which case it needs to call this function so other modules can do the needful Calling this function directly should be avoided if possible. In general a better way is to do setUserContext so the framework does the redirect

preProcess()

Set variables up before form is built.


    public
                    preProcess() : void

preventAjaxSubmit()

Sets form attribute.


    public
                    preventAjaxSubmit() : mixed

registerFileField()


    public
                    registerFileField(array<string|int, mixed> $fieldNames) : void

Parameters

$fieldNames : array<string|int, mixed>

registerRules()


    public
                    registerRules() : mixed

removeFileRequiredRules()


    public
                    removeFileRequiredRules(mixed $elementName) : mixed

Parameters

$elementName : mixed

resetValues()


    public
                    resetValues() : mixed

set()

Store the variable with the value in the form scope.


    public
                    set(string $name, mixed $value) : mixed

Parameters

$name : string: Name of the variable.
$value : mixed: Value of the variable.

setAction()

Setter for action.


    public
                    setAction(int $action) : mixed

Parameters

$action : int: The mode we want to set the form.

setContext()

Set context variable.


    public
                    setContext() : mixed

setDataSourceDefaults()

Set dataSource default values.


    public
                    setDataSourceDefaults(array<string|int, mixed> $dataSourceDefaults) : self

Parameters

$dataSourceDefaults : array<string|int, mixed>

Return values

self

setDefaultValues()

Set the default values of various form elements.


    public
                    setDefaultValues() : array<string|int, mixed>

Return values

array<string|int, mixed> —

reference to the array of default values

setOptions()

Setter function for options.


    public
                    setOptions(mixed $options) : mixed

Parameters

$options : mixed

setPageTitle()

Sets page title based on entity and action.


    public
                    setPageTitle([string|null $entityLabel = NULL ]) : void

Parameters

$entityLabel : string|null = NULL

setPurifiedDefaults()


    public
                    setPurifiedDefaults(mixed $defaults) : mixed

Parameters

$defaults : mixed

setSavedMappingID()


    public
                    setSavedMappingID(int $savedMappingID) : CRM_Import_Forms

Parameters

$savedMappingID : int

Return values

CRM_Import_Forms

setSelectedChild()

Set the active tab


    public
                    setSelectedChild([string $default = NULL ]) : mixed

Parameters

$default : string = NULL

setTemplateDefaults()

Load default values from the relevant template if one is passed in via the url.


    public
                    setTemplateDefaults() : array<string|int, mixed>

We need to create and UserJob at this point as the relevant values go beyond the first DataSource screen.

Return values

array<string|int, mixed>

setTitle()

Setter function for title.


    public
                    setTitle(string $title) : mixed

Parameters

$title : string: The title of the form.

setUserJobID()

Set user job ID.


    public
                    setUserJobID(int $userJobID) : void

Parameters

$userJobID : int

setVar()


    public
                    setVar(string $name, mixed $value) : mixed

use of this function assumes that an otherwise unavailable variable can be used form outside the class in question. However, the very fact it is otherwise unavailable means there is no contract that it will not be changed or become unused. This function is OK for temporary usage but should be accompanied with an effort to establish a more correct method or property tested hook / api interface if this is being done from outside of core.

Parameters

$name : string
$value : mixed

toSmarty()

Render form and return contents.


    public
                    toSmarty() : string

Return values

string

validate()

Performs the server side validation.


    public
                    validate() : bool

Return values

bool —

true if no error found

validateMandatoryFields()

Helper function to verify that required fields have been filled.


    public
            static        validateMandatoryFields(array<string|int, mixed> $fields, array<string|int, mixed> $values, array<string|int, mixed> &$errors) : mixed

Typically called within the scope of a FormRule function

Parameters

$fields : array<string|int, mixed>
$values : array<string|int, mixed>
$errors : array<string|int, mixed>

addContactTypeSelector()

A long-winded way to add one radio element to the form.


    protected
                    addContactTypeSelector() : mixed

assignPaymentProcessor()

This if a front end form function for setting the payment processor.


    protected
                    assignPaymentProcessor(bool $isPayLaterEnabled) : mixed

It would be good to sync it with the back-end function on abstractEditPayment & use one everywhere.

Parameters

$isPayLaterEnabled : bool

buildAllowedDateFormats()

Build the date-format form.


    protected
                    buildAllowedDateFormats() : void

buildDataSourceFields()

Allow the datasource class to add fields.


    protected
                    buildDataSourceFields() : void

This is called as a snippet in DataSourceConfig and also from DataSource::buildForm to add the fields such that quick form picks them up.

createTemplateJob()


    protected
                    createTemplateJob() : void

createUserJob()

Create a user job to track the import.


    protected
                    createUserJob() : int

Return values

int

flushDataSource()

Flush datasource on re-submission of the form.


    protected
                    flushDataSource() : void

If the form has been re-submitted the datasource might have changed. We tell the dataSource class to remove any tables (and potentially files) created last form submission.

If the DataSource in use is unchanged (ie still CSV or still SQL) we also pass in the new variables. In theory it could decide that they have not actually changed and it doesn't need to do any cleanup.

In practice the datasource classes blast away as they always have for now

however, the sql class, for example, might realise the fields it cares about are unchanged and not flush the table.

formatParamsForPaymentProcessor()

Format the fields in $this->_params for the payment processor.


    protected
                    formatParamsForPaymentProcessor(array<string|int, mixed> $fields) : array<string|int, mixed>

In order to pass fields to the payment processor in a consistent way we add some renamed parameters.

Parameters

$fields : array<string|int, mixed>

Return values

array<string|int, mixed>

getApiAction()

Based on form action, return a string representing the api action.


    protected
                    getApiAction() : mixed

Used by addField method.

Return string

getAuthenticatedCheckSumContactID()

Get the contact ID authenticated as a valid by checksum.


    protected
                    getAuthenticatedCheckSumContactID() : int

Return values

int

getAvailableFields()

Get the fields available for import selection.


    protected
                    getAvailableFields() : array<string|int, mixed>

Return values

array<string|int, mixed> —

e.g ['first_name' => 'First Name', 'last_name' => 'Last Name'....

getBaseEntity()

Get the base entity for the import.


    protected
                    getBaseEntity() : string

Return values

string

getColumnHeaders()

Get column headers for the datasource or empty array if none apply.


    protected
                    getColumnHeaders() : array<string|int, mixed>

This would be the first row of a csv or the fields in an sql query.

If the csv does not have a header row it will be empty.

Return values

array<string|int, mixed>

getContactIDIfAccessingOwnRecord()

Get the contact if from the url, using the checksum or the cid if it is the logged in user.


    protected
                    getContactIDIfAccessingOwnRecord() : int|false

use getAuthenticatedContactID()

This function returns the user being validated. It is not intended to get another user they have permission to (setContactID does do that) and can be used to check if the user is accessing their own record.

Return values

int|false

getContactSubType()

Get the contact sub type selected for the import (on the datasource form).


    protected
                    getContactSubType() : string|null

Return values

string|null —

e.g Staff.

getContactType()

Get the contact type selected for the import (on the datasource form).


    protected
                    getContactType() : string

Return values

string —

e.g Individual, Organization, Household.

getDataRows()

Get x data rows from the datasource.


    protected
                    getDataRows([mixed $statuses = [] ][, int $limit = 0 ]) : array<string|int, mixed>|int

At this stage we are fetching from what has been stored in the form during postProcess on the DataSource form.

In the future we will use the dataSource object, likely supporting offset as well.

Parameters

$statuses : mixed = []
$limit : int = 0

Return values

array<string|int, mixed>|int —

One or more of the statues available - e.g CRM_Import_Parser::VALID or [CRM_Import_Parser::ERROR, CRM_Import_Parser::VALID]

getDataSourceClassName()

Get the name of the datasource class.


    protected
                    getDataSourceClassName() : string|null

This function prioritises retrieving from GET and POST over 'submitted'. The reason for this is the submitted array will hold the previous submissions data until after buildForm is called.

This is problematic in the forward->back flow & option changing flow. As in....

Load DataSource form - initial default datasource is set to CSV and the form is via ajax (this calls DataSourceConfig to get the data).
User changes the source to SQL - the ajax updates the html but the form was built with the expectation that the csv-specific fields would be required.
When the user submits QuickForm calls preProcess and buildForm and THEN retrieves the submitted values based on what has been added in buildForm. Only the submitted values for fields added in buildForm are available - but these have to be added BEFORE the submitted values are determined. Hence we look in the POST or GET to get the updated value.

Note that an imminent refactor will involve storing the values in the civicrm_user_job table - this will hopefully help with a known (not new) issue whereby the previously submitted values (eg. skipColumnHeader has been checked or sql has been filled in) are not loaded via the ajax request.

Return values

string|null

getDataSourceFields()

Allow the datasource class to add fields.


    protected
                    getDataSourceFields() : array<string|int, mixed>

This is called as a snippet in DataSourceConfig and also from DataSource::buildForm to add the fields such that quick form picks them up.

Return values

array<string|int, mixed>

getDataSourceObject()

Get the relevant datasource object.


    protected
                    getDataSourceObject() : DataSourceInterface|null

Return values

DataSourceInterface|null

getDataSources()

Get the available datasource.


    protected
                    getDataSources() : array<string|int, mixed>

Permission dependent, this will look like [ 'CRM_Import_DataSource_CSV' => 'Comma-Separated Values (CSV)', 'CRM_Import_DataSource_SQL' => 'SQL Query', ]

The label is translated.

Return values

array<string|int, mixed>

getDefaultDataSource()

Get the default datasource.


    protected
                    getDefaultDataSource() : string

Return values

string

getDownloadURL()

Get the url to download the relevant csv file.


    protected
                    getDownloadURL(string $status) : string

Parameters

$status : string

Return values

string

getErrorMessage()

Get an error message to assign to the template.


    protected
                    getErrorMessage() : string

Return values

string

getFields()

Get the fields available for import selection.


    protected
                    getFields() : array<string|int, mixed>

Return values

array<string|int, mixed> —

e.g ['first_name' => 'First Name', 'last_name' => 'Last Name'....

getFieldsToExcludeFromPurification()

Override this in a subclass to prevent fields intended to contain "raw html" from getting broken. E.g. system message templates


    protected
                    getFieldsToExcludeFromPurification() : array<string|int, mixed>

Return values

array<string|int, mixed>

getHighlightedFields()

Get the fields to be highlighted in the UI.


    protected
                    getHighlightedFields() : array<string|int, mixed>

The highlighted fields are those used to match to an existing entity.

Return values

array<string|int, mixed>

getImportEntities()

Get the fields available for import selection.


    protected
                    getImportEntities() : array<string|int, mixed>

Return values

array<string|int, mixed> —

e.g ['first_name' => 'First Name', 'last_name' => 'Last Name'....

getMappedFieldLabels()

Get the mapped fields as an array of labels.


    protected
                    getMappedFieldLabels() : array<string|int, mixed>

e.g ['First Name', 'Employee Of - First Name', 'Home - Street Address']

Return values

array<string|int, mixed>

getMappingName()


    protected
                    getMappingName() : string

Return values

string

getNumberOfColumns()

Get the number of importable columns in the data source.


    protected
                    getNumberOfColumns() : int

Return values

int

getOutputColumnsHeaders()

Get the column headers for the output csv.


    protected
                    getOutputColumnsHeaders() : array<string|int, mixed>

Return values

array<string|int, mixed>

getOutputRows()

Get the datasource rows ready for csv output.


    protected
                    getOutputRows([array<string|int, mixed> $statuses = [] ][, int $limit = 0 ]) : array<string|int, mixed>

Parameters

$statuses : array<string|int, mixed> = []
$limit : int = 0

Return values

array<string|int, mixed>

getParser()

Get an instance of the parser class.


    protected
                    getParser() : CRM_Contact_Import_Parser_Contact|CRM_Contribute_Import_Parser_Contribution

Return values

CRM_Contact_Import_Parser_Contact|CRM_Contribute_Import_Parser_Contribution

getRowCount()

Get the number of rows with the specified status.


    protected
                    getRowCount([array<string|int, mixed>|int $statuses = [] ]) : int

Parameters

$statuses : array<string|int, mixed>|int = []

Return values

int

getSubmittableFields()

Get the fields that can be submitted in the Import form flow.


    protected
                    getSubmittableFields() : array<string|int, string>

These could be on any form in the flow & are accessed the same way from all forms.

Return values

array<string|int, string>

getTemplateJob()

Get the UserJob Template, if it exists.


    protected
                    getTemplateJob() : array<string|int, mixed>|null

Return values

array<string|int, mixed>|null

getTranslatedEntities()

Get the import entity plural (translated).


    protected
                    getTranslatedEntities() : string

Used for template layer text.

Return values

string

getTranslatedEntity()

Get the import entity (translated).


    protected
                    getTranslatedEntity() : string

Used for template layer text.

Return values

string

getUserJob()

Get User Job.


    protected
                    getUserJob() : array<string|int, mixed>

API call to retrieve the userJob row.

Return values

array<string|int, mixed>

getUserJobInfo()

Get information about the user job parser.


    protected
                    getUserJobInfo() : array<string|int, mixed>

This is as per CRM_Core_BAO_UserJob::getTypes()

Return values

array<string|int, mixed>

getUserJobSubmittedValues()

Get submitted values stored in the user job.


    protected
                    getUserJobSubmittedValues() : array<string|int, mixed>

Return values

array<string|int, mixed>

handlePreApproval()

Handle pre approval for processors.


    protected
                    handlePreApproval(array<string|int, mixed> &$params) : mixed

This fits with the flow where a pre-approval is done and then confirmed in the next stage when confirm is hit.

This function is shared between contribution & event forms & this is their common class.

However, this should be seen as an in-progress refactor, the end goal being to also align the backoffice forms that action payments.

Parameters

$params : array<string|int, mixed>

hasImportableRows()

Are there valid rows to import.


    protected
                    hasImportableRows() : bool

Return values

bool

isFilterContactFields()

Should contact fields be filtered which determining fields to show.


    protected
                    isFilterContactFields() : bool

This applies to Contribution import as we put all contact fields in the metadata but only present those used for a match - but will permit create via LeXIM.

Return values

bool

isFormInViewOrEditMode()

Is the form in view or edit mode.


    protected
                    isFormInViewOrEditMode() : bool

The 'addField' function relies on the form action being one of a set list of actions. Checking for these allows for an early return.

Return values

bool

isImportDataUploaded()

Is the data already uploaded.


    protected
                    isImportDataUploaded() : bool


    protected
                    prepareParamsForPaymentProcessor(array<string|int, mixed> $params) : array<string|int, mixed>

In order to pass fields to the payment processor in a consistent way we add some renamed parameters.

Parameters

$params : array<string|int, mixed>: Payment processor params

Return values

array<string|int, mixed> —

$params

preProcessPaymentOptions()

Handle Payment Processor switching for contribution and event registration forms.


    protected
                    preProcessPaymentOptions() : mixed

This function is shared between contribution & event forms & this is their common class.

However, this should be seen as an in-progress refactor, the end goal being to also align the backoffice forms that action payments.

This function overlaps assignPaymentProcessor, in a bad way.

processDatasource()

Process the datasource submission - setting up the job and data source.


    protected
                    processDatasource() : void

pushUrlToUserContext()

Push path to the userContext (defaults to current url path).


    protected
                    pushUrlToUserContext([string|null $path = NULL ]) : void

This is like a save point :-). The next status bounce will return the browser to this url unless another is added.

Parameters

$path : string|null = NULL: Path string e.g. civicrm/foo/bar?reset=1, defaults to current path.

setContactID()

Get contact iD for a form object.


    protected
                    setContactID() : null|int

This checks the requestedContactID and returns it if

it is the number 0 (relevant for online contribution & event forms).
it is the logged in user
it is validated by a checksum in the url.
it is a contact that the logged in user has permission to view

Failing that it returns the logged in user, if any. This is may be useful for users taking actions from their contact dashboard (although usually one of the variants above would be hit).

Return values

null|int

setTranslatedFields()

Set translated fields.


    protected
                    setTranslatedFields() : mixed

This function is called from the class constructor, allowing us to set fields on the class that can't be set as properties due to need for translation or other non-input specific handling.

storeFormValues()

Store form values.


    protected
                    storeFormValues(array<string|int, mixed> $names) : void

Parameters

$names : array<string|int, mixed>

updateTemplateUserJob()


    protected
                    updateTemplateUserJob(array<string|int, mixed> $metaData) : void

Parameters

$metaData : array<string|int, mixed>

updateUserJobMetadata()


    protected
                    updateUserJobMetadata(string $key, array<string|int, mixed> $data) : void

Parameters

$key : string
$data : array<string|int, mixed>

validateAuthenticatedCheckSumContactID()

Verify that a contact ID is authenticated as a valid contact by checksum


    protected
                    validateAuthenticatedCheckSumContactID(int|null $contactID) : int

Parameters

$contactID : int|null

Return values

int

formatReferenceFieldAttributes()


    private
                    formatReferenceFieldAttributes(array<string|int, mixed> &$props, string $formName) : mixed

Parameters

$props : array<string|int, mixed>
$formName : string

instantiateDataSource()

Instantiate the datasource.


    private
                    instantiateDataSource() : void

This gives the datasource a chance to do any table creation etc.

preProcessChainSelectFields()

Set options and attributes for chain select fields based on the controlling field's value


    private
                    preProcessChainSelectFields() : mixed

selectOrAnyPlaceholder()

Handles a repeated bit supplying a placeholder for entity selection


    private
            static        selectOrAnyPlaceholder(string $props, bool $required[, string $title = NULL ]) : string

Parameters

$props : string: The field properties, including the entity and context.
$required : bool: If the field is required.
$title : string = NULL: A field title, if applicable.

Return values

string —

The placeholder text.

strToPattern()


    private
                    strToPattern(string $str) : mixed

Parameters

$str : string

validateChainSelectFields()

Validate country / state / county match and suppress unwanted "required" errors


    private
                    validateChainSelectFields() : mixed

CRM_Contact_Import_Form_DataSource extends CRM_Import_Form_DataSource in package CRM

Table of Contents

Constants

Properties

Methods

Constants

ATTR_SPACING

CB_PREFIX

CB_PREFIX_LEN

CB_PREFIY

CB_PREFIZ

Properties

$_action

$_defaults

$_options

$_paymentProcessorIDs

$ajaxResponse

$controller

$expectedSmartyVariables

$html5Types

$submitOnce

$urlPath

$_actionButtonName

$_name

$_paymentProcessorID

$_paymentProcessors

$_renderer

$_state

$_template

$_title

$context

$dataSourceDefaults

$exportedValues

$isDisplayTimeInDateFormats

$isQuickFormMode

$mappingName

$optionalQuickFormElements

$parser

$savedMappingID

$submittableFields

$submittableMoneyFields

$templateID

$templateValues

$unsavedChangesWarn

$userJob

$userJobID

$authenticatedContactID

$isValidated

Methods

__construct()

Parameters

Return values

add()

Parameters

Tags

Return values

addAutocomplete()

Parameters

Return values

addAutoSelector()

Parameters

Tags

addButtons()

Parameters

addChainSelect()

Parameters

Return values

addCheckBox()

Parameters

addCIDZeroOptions()

Tags

addClass()

Parameters

addCurrency()

Parameters

addDate()

Parameters

addDatePickerRange()

Parameters

addDateRange()

CRM_Contact_Import_Form_DataSource extends CRM_Import_Form_DataSource
in package

CRM