Customisation Guide

This page is to detail how customistions can be implemented in the Accelerator Pro/Plus and MobileX products.

No customisations are possible in AC Lite.

---

Primary Entity Search

These use the screen

  ENTITYOfficeIntSearch

to determine what fields to search on.

If the ENTITYOfficeIntSearch field does not exists then the xxxx_name field is used

It is recommended that you create SQL indexes on these fields to improve performance.

---

Primary Entity Search List Results

These use the screen

  ENTITYOfficeIntSmall

to determine what fields to display

---

SSA fields

These use the CRM screen

  ENTITYOfficeIntSmall

to determine what to display when a search result is returned.

If the screen ENTITYOfficeIntSmall does not exist then the xxxx_name field is only shown

---

Custom Primary Entity Tabs

To add in a tabgroup you create it using the name

  ENTITYInt

eg

 ProjectInt

Next you add in the Summary tab item

 Caption=Summary
 Action=customfile
 Custom File=SageCRMWS/intENTITY.aspx

To add the Communications tab (we assume that these primary entities have communications)

 Caption=Communications
 Action=customfile
 Custom File=SageCRMWS/listCommunications.aspx

---

Create Scripts

Here we document how to write code in Sage CRM "create scripts" to update an element when you use a new form screen (New company/person/case etc)

1. Form element methods

Form fields that register themselves globally can be accessed in browser scripts by their field `name`. For example, a field named `oppo_stage` is available as `window.oppo_stage` after it has mounted:

```js window.oppo_stage.setOptions([

 { text: "Design Requested", value: "DesignRequested" },
 { text: "Out For Bid", value: "OutForBid" },

]); ```

The methods below are the form-field helpers intended for scripts. Method names are case-sensitive. The component assigns its instance to `window` when it mounts. Behavior after a field is removed from the page is not guaranteed (`MyFormSignature` removes its global reference when unmounted).

This documents the helper methods intended for integrations, not internal event handlers or component lifecycle methods.

1. 1. Common field methods

These methods are available on `MyFormInput`, `MyFormNumber`, `MyFormCheckbox`, `MyFormSelect`, `MyFormSelectMultiple`, `MyFormRemoteLookup`, `MyFormTime`, `MyFormTextArea`, and `MyFormSignature`.

| Method | Argument | Result / effect | |---|---|---| | `setCaption(caption)` | `string` | Changes the field caption. | | `getCaption()` | — | Returns the current caption. | | `getValue()` | — | Returns the field's current value. The shape depends on the field type; see below. | | `setRequired(required)` | `boolean` | Enables or disables required validation. | | `setReadOnly(readOnly)` | `boolean` | Enables or disables read-only behavior. |

Example:

```js window.oppo_customerref.setValue("ABC 123"); window.oppo_customerref.setRequired(true); window.oppo_customerref.getValue(); ```

`MyFormCurrency` has caption and value helpers of its own, but does not implement `setRequired` or `setReadOnly`.

1. 1. Select (`MyFormSelect`)

The single-select field stores a selection as `{ text, value }`. `getValue()` returns the selected `value`; `getValueText()` returns its display text.

| Method | Argument | Result / effect | |---|---|---| | `setValue(text, value?)` | Display text and optional stored value | Sets the selection. If `value` is omitted or falsy, `text` is used for both. | | `getValue()` | — | Returns the selected value. | | `getValueText()` | — | Returns the selected display text. | | `setOptions(options)` | Array of `{ text, value }` | Replaces the available options. | | `getOptions()` | — | Returns the current options array. | | `clearOptions()` | — | Clears the options and selection. | | `resetOptions()` | — | Restores the options captured when the field was created. | | `filterOptions(prefix)` | `string` | Shows the original options whose `value` starts with the prefix. Matching is case-sensitive. |

```js window.oppo_stage.setValue("Design Requested", "DesignRequested"); window.oppo_stage.getValue(); // "DesignRequested" window.oppo_stage.getValueText(); // "Design Requested" ```

`filterOptions()` filters the options present when the field was created. Use `resetOptions()` to restore that original list; calling `setOptions()` does not change the list used by `filterOptions()` or `resetOptions()`.

Implementation example:

```js resetOptions() {

 return (this.selectValue.options = JSON.parse(
   JSON.stringify(this.initialOptions)
 ));

} ```

The component keeps `initialOptions` as the original options snapshot and restores a copy when `resetOptions()` is called.

1. 1. Multi-select (`MyFormSelectMultiple`)

The multi-select value is an array of `{ text, value }` selections. `getValue()` returns that array.

| Method | Argument | Result / effect | |---|---|---| | `checkOptionValue(text, value)` | Display text and stored value | Adds a selection. It does not check for duplicates or verify that the option exists. | | `uncheckOptionValue(text, value)` | Display text and stored value | Removes the first selection matching both values. | | `getValue()` | — | Returns the selected `{ text, value }` items. | | `setOptions(options)` | Array of `{ text, value }` | Replaces the available options. | | `getOptions()` | — | Returns the current options array. | | `clearOptions()` | — | Clears the options and all selections. | | `resetOptions()` | — | Restores the options captured when the field was created. | | `filterOptions(prefix)` | `string` | Shows the original options whose `value` starts with the prefix. Matching is case-sensitive. |

As with the single-select, filtering and resetting use the options captured when the field was created, not a later array supplied to `setOptions()`.

1. 1. Currency (`MyFormCurrency`)

The currency field keeps an object value with `currency` and `amount` properties. `getValue()` returns that object.

| Method | Argument | Result / effect | |---|---|---| | `setCaption(caption)` | `string` | Changes the field caption. | | `getCaption()` | — | Returns the current caption. | | `getValue()` | — | Returns the current currency/amount object. | | `setAmountValue(amount)` | Amount | Sets the amount. | | `getAmountValue()` | — | Returns the amount. | | `setCurrencyValue(currency)` | Currency value (normally a string) | Sets the selected currency value. | | `getCurrencyValue()` | — | Returns the selected currency value. | | `setOptions(options)` | Array of `{ text, value }` | Replaces the available currency options. | | `getOptions()` | — | Returns the current options array. | | `clearOptions()` | — | Clears the options and resets the value. | | `resetOptions()` | — | Restores the options captured when the field was created. | | `filterOptions(prefix)` | `string` | Shows the original options whose `text` starts with the prefix. Matching is case-sensitive. |

`filterOptions()` and `resetOptions()` use the options captured when the field was created, not a later array supplied to `setOptions()`.

Note: `clearOptions()` currently sets the value to `{ text: "", value: "" }`, although the normal currency value has `currency` and `amount` properties.

1. 1. Remote lookup (`MyFormRemoteLookup`)

Remote lookup values are objects. A selected item typically looks like this:

```js {

 text: "Example Company",
 value: { entity: "Company", entityid: "record-id" },
 icon: "mdi-office-building"

} ```

| Method | Argument | Result / effect | |---|---|---| | `getValue()` | — | Returns the current lookup selection object. | | `setValue(item)` | Lookup item object | Sets the selection. The field must not be read-only. | | `customSearch(text, filterSQL?, queryFilter?)` | Search text; optional SQL filter and query filter | Starts a remote search and updates the options when the request completes. This method does not return a promise or the results. | | `createEntity()` | — | Creates an entity of the lookup's configured type using the current search text. Does nothing when read-only; the created entity is added as the selected value. |

The optional `queryFilter` overrides the lookup's configured related-field filter. `setCaption()`, `getCaption()`, `setRequired()`, and `setReadOnly()` are also available as described in [Common field methods](#common-field-methods).

1. 1. Checkbox (`MyFormCheckbox`)

`getValue()` returns the checked state as a boolean. `setValue(value)` sets that state.

1. 1. Text input (`MyFormInput`)

`getValue()` returns the current input value. `setValue(value)` sets it.

1. 1. Number (`MyFormNumber`)

`getValue()` returns the number field's current value. `setValue(value)` sets it; provide a number or a numeric string accepted by the field.

1. 1. Time (`MyFormTime`)

`getValue()` returns the current time value, normally a string such as `"13:54"`; it returns `false` when the field is empty. `setValue(value)` sets the time field's value.

1. 1. Text area (`MyFormTextArea`)

The common caption, value, required, and read-only methods apply. Values are normally strings. Setting the field read-only also stops active voice transcription.

| Method | Argument | Result / effect | |---|---|---| | `toggleTranscribe()` | — | Starts or stops voice transcription. Starting may request microphone permission. | | `stopTranscribe()` | — | Stops active transcription and any associated audio recording. |

1. 1. Signature (`MyFormSignature`)

The common caption, value, required, and read-only methods apply. The value format follows the field's `signatureFormat` configuration (`pngDataUrl`, `pngBase64`, or `strokesJson`; the default is `pngDataUrl`).

| Method | Argument | Result / effect | |---|---|---| | `clear()` | — | Clears the signature and sets its value to an empty string. Does nothing when the field is read-only or disabled. |

1. 1. Date and date-time methods

`MyFormDate` and `MyFormDateTime` implement the following methods:

| Method | Argument | Result / effect | |---|---|---| | `getValue()` | — | Returns `{ date, time }`, or `null` when the field has no value. | | `getDateValue()` | — | Returns the current date-picker value. | | `setDateValue(date)` | Date-picker value | Sets the date-picker state. | | `getTimeValue()` | — | Returns the current time-picker value. | | `setTimeValue(hours, minutes)` | Numeric hours and minutes | Sets the time-picker state. | | `setCaption(caption)` / `getCaption()` | `string` for setter | Sets or returns the caption. | | `setRequired(required)` | `boolean` | Enables or disables required validation. | | `setReadOnly(readOnly)` | `boolean` | Enables or disables read-only behavior. |

• • Global access limitation:** Unlike the field types listed above, these two

components do not currently assign their instance to `window[fieldName]`. Therefore, the `window.oppo_opened...` examples in their source code will not work unless the application exposes those instances by another means. Their date/time setters update picker state; they do not directly commit a combined field value.