ItemImpl can contain any of the following properties:
* @param pItemImpl.addValue - function(value, displayValue) Specify a function for adding a value to the item, * where the item supports multiple values. This is called by the {@link item#addValue} method which has no default * behavior for adding a value. Currently there is no client-side functionality of Oracle Application Express dependent on this. *Note: Even if this function is defined, the default handling always calls the afterModify method.
* @param pItemImpl.afterModify - function() Specify a function that is called after an item is modified. * This is useful, for example as some frameworks need to be notified if widgets are * modified, for example their value has been set, or they have been disabled in order to keep both the native * and enhanced controls in sync. This callback provides the hook to do so. *Note: This callback is deprecated.
* @param pItemImpl.delayLoading -Specify if the item needs to delay APEX page loading. There are many places * in the APEX framework where client-side logic is run after the page has finished loading, for example Dynamic Actions * set to 'Fire on Initialization', or code defined in the page level attribute 'Execute when Page Loads'. If an item * takes longer to initialize (for example if it uses a module loader like requirejs to load additional modules, * or if the underlying JavaScript widget itself takes longer to initialize), setting delayLoading to true allows * you to tell APEX to wait for your item to finish initializing, before firing it's built in page load logic. This * allows you as a developer to ensure that your item is compatible with these built-in APEX features like Dynamic * Actions.
*When this is set to true, apex.item.create will return a jQuery
* deferred object, which will need to be resolved in order for page loading to complete.
Note: If using this option, you must ensure your item initializes as quickly as possible, and also that * the returned deferred object is always resolved, to avoid disrupting the default APEX page load behavior.
* @param pItemImpl.disable - function() Specify a function for disabling the item, which overrides the * default {@link item#disable} behavior. The default behavior sets the disabled property of the item node to true. * Providing this override could be useful for example where the item consists of compound elements which * also need disabling, or if the item is based on a widget that already has its own disable method that you want * to reuse. Ensuring the item can disable correctly means certain item related client-side functionality of * Oracle Application Express still works, for example when using the Disable action of a Dynamic Action to disable * the item. *Note: Even if this function is defined, the default handling always calls the afterModify method.
* @param pItemImpl.displayValueFor - function(value, [state]):string Specify a function that returns a string * display value that corresponds to the given value. This overrides the default behavior of the * {@link item#displayValueFor} method. The default behavior supports a standard select element and conceals the * value of password inputs. * @param pItemImpl.enable - function() Specify a function for enabling the item, which overrides the * default {@link item#enable} behavior. The default behavior sets the disabled property of the item node to false. * Providing this override could be useful for example where the item consists of compound elements which * also need enabling, or if the item is based on a widget that already has its own enable method that you want * to reuse. Ensuring the item can enable correctly means certain item related client-side functionality * of Oracle Application Express still works, for example when using the Enable action of a Dynamic Action * to enable the item. *Note: Even if this function is defined, the default handling always calls the afterModify method.
* @param pItemImpl.getValidationMessage - function():string Specify a function to return the * validation message, which overrides the default {@link item#getValidationMessage} behavior. * @param pItemImpl.getValidity - function():ValidityState Specify a function that returns a * validity state object, which overrides the default {@link item#getValidity} behavior. * The returned object must at a minimum have the Boolean valid property. It may include any of the properties * defined for the HTML5 ValidityState object. The default implementation returns the validity object of * the item element if there is one otherwise it returns { valid: true }. * @param pItemImpl.getValue - function():string Specify a function for getting the item's value, * which overrides the default {@link item#getValue} behavior. The default behavior handles * the standard HTML form elements. Ensuring the item returns its value correctly means certain item related * client-side functionality of Oracle Application Express still works, for example in Dynamic Actions to evaluate * a When condition on the item, or when calling the JavaScript function {@link $v} to get the item's value. * @param pItemImpl.hide - function() Specify a function for hiding the item, which overrides the default * {@link item#hide} behavior. This could be useful for example where the item consists of compound elements which also * need hiding, or if the item is based on a widget that already has its own hide method that you want to reuse. * Ensuring the item can hide correctly means certain item related client-side functionality of Application * Express still works, for example when using the Hide action of a Dynamic Action, to hide the item. *Note: if the item is in an element with an id that matches the name of the item with a '_CONTAINER' suffix * then the container element is hidden and this function is not called.
* @param pItemImpl.isChanged - function():Boolean Specify a function that returns true if the * current value of the item has changed and false otherwise, which overrides the default {@link item#isChanged} * behavior. This function allows the Warn on Unsaved Changes feature to work. * The default implementation uses built-in functionality of HTML form elements to detect changes. * If this function does not work correctly then changes to the plug-in item type value will not be * detect and the user will not be warned when they leave the page. * @param pItemImpl.isDisabled - function():Boolean Specify a function that returns true if the * item is disabled and false otherwise, which overrides the default {@link item#isDisabled} behavior. * Ensuring the item returns its value correctly means certain item related client-side functionality of * Oracle Application Express still works, for example client-side validation and Interactive Grid. * @param pItemImpl.getPopupSelector - function():string Specify a function that returns a * CSS selector that locates the popup used by the item. * Any plug-in item type that uses a popup (a div added near the end of the document * that is positioned near the input item and floating above it) needs to provide a CSS selector that locates * the top level element of the popup. This allows the item type to be used in the Interactive Grid region or * any other region that needs to coordinate focus with the popup. The default implementation returns null. *In addition the top level popup element must be focusable (have attribute tabindex = -1).
*For best behavior of a popup in the Interactive Grid. The popup should: *
-
*
- have a way of taking focus *
- close on escape when it has focus *
- close when the element it is attached to loses focus *
- return focus to the element that opened the popup when it closes *
- manage its tab stops so they cycle in the popup or return to the element that opened the popup at the ends *
This is used, for example, if the item is a Cascading LOV and the Cascading LOV Parent Item changes, * or when setting the item's value by using one of the server-side Dynamic Actions such as * Set Value - SQL Statement.
* @param pItemImpl.nullValue - Specify a value to be used to determine if the item is null. * This is used when the item supports definition of a List of Values, where a developer can define a * Null Return Value for the item and where the default item handling needs to know this in order to * assert if the item is null or empty. This can be done by following these steps: *From the Render function in the plug-in definition, emit the value stored in p_item.lov_null_value as * part of the item initialization JavaScript code that fires when the page loads. For example: *
* # Assumes that you have some JavaScript function called 'com_your_company_your_item'
* # that accepts 2 parameters, the first being the name of the item and the second being
* # an object storing properties (say pOptions) required by the item's client side code.
* apex_javascript.add_onload_code (
* p_code => 'com_your_company_your_item('||
* apex_javascript.add_value(
* apex_plugin_util.page_item_names_to_jquery(p_item.name)||', {'||
* apex_javascript.add_attribute(
* 'lovNullValue', p_item.lov_null_value, false, false)||
* '});' );
* Then, in the implementation of com_your_company_your_item( pName, pOptions ) you have the value defined for * the specific item's Null Return Value in the pOptions.lovNullValue property. This can then be used in your * call to {@link apex.item.create}, to set the nullValue property.
*Ensuring the nullValue property is set means certain item related client-side functionality of * Oracle Application Express still works, for example, in Dynamic Actions to correctly evaluate an is null * or is not null when condition on the item, or when calling the JavaScript function * {@link item#isEmpty} to determine if the item is null.
* @param pItemImpl.refresh - function() Specify a function to refresh the item. * This is called by the {@link item#refresh} method. The default behavior triggers event "apexrefresh" * for legacy plug-in items. * @param pItemImpl.reinit - function(value, display):function Specify a function to * initialize an item's value when it is reused in a new context. This is only called for column items every time * a new record is being edited. The default behaviour calls {@link item#setValue} and suppresses the change event. * Items that support cascading LOVs should implement this function to first set the item's value (which may also * require adding the value as an option in the item), then return a function where the cascade will take place. * @param pItemImpl.removeValue - function(value) Specify a function for removing a value from the item, * where the item supports multiple values. This is called by the {@link item#removeValue} method which has no default * behavior for removing a value. Currently there is no client-side functionality of Oracle Application Express dependent on this. *Note: Even if this function is defined, the default handling always calls the afterModify method.
* @param pItemImpl.setFocusTo - Specify the element to receive focus * when focus is set to the item using the {@link item#setFocus} method. This can be defined as either a jQuery * selector, jQuery object or DOM Element which identifies the DOM element, or a no argument function that returns a jQuery * object referencing the element. This can be useful when the item consists of compound elements, * and you do not want focus to go to the element that has an ID matching the item name, which is the * default behavior. *Ensuring the item sets focus correctly means certain item related client-side functionality of * Oracle Application Express still works, for example when using the Set Focus action of a Dynamic Action to * set focus to the item, when users follow the Go to Error link that displays in a validation error * message to go straight to the associated item, or when the item is the first item on a page and * the developer has the page level attribute Cursor Focus set to First item on page.
* @param pItemImpl.setStyleTo - Specify the element to receive style, when style is set to * the item using the {@link item#setStyle} method. This can be defined as either a jQuery selector, * jQuery object or DOM Element which identifies the DOM element(s), or a no argument function that returns a jQuery object * referencing the element(s). This is useful when the item consists of compound elements, and you do not * want style to be set to the element or just the element, that has an ID matching the item name which is * the default behavior. *Ensuring the item sets style correctly means certain item related client-side * functionality of Oracle Application Express still works, for example when using the Set Style action of a * Dynamic Action to add style to the item.
*Note: Even if this property is defined, the default behavior of {@link item#setStyle} calls the afterModify method.
* @param pItemImpl.setValue - function(value, displayValue, suppressChangeEvent) Specify a function for * setting the item's value, which overrides the default {@link item#setValue} behavior. The default behavior handles * the standard HTML form elements. Ensuring the item can set its value correctly means certain item related * client-side functionality of Oracle Application Express still works, for example * when using the Set Value action of a Dynamic Action to set the item's value, or when calling the * JavaScript function {@link $s} to set the item's value. *Note: Even when this function is defined, the default handling always calls the afterModify function and * triggers the change event according to the pSuppressChangeEvent parameter. The pSuppressChangeEvent parameter * is provided to this function for informational purpose only. In most cases it can be ignored.
* @param pItemImpl.show - function() Specify a function for showing the item, which overrides the * default {@link item#show} behavior. This is useful for example where the item consists of compound elements which * also need showing, or if the item is based on a widget that already has its own show method that you want * to reuse. Ensuring the item can show correctly means certain item related client-side functionality of * Oracle Application Express still works, for example when using the Show action of a Dynamic Action, to show the item. *Note: if the item is in an element with an id that matches the name of the item with a '_CONTAINER' suffix * then the container element is shown and this function is not called.
* @returns Returns ajQuery Deferred object when delayLoading is set to true. The jQuery deferred object must
* be resolved in order for APEX page load to complete. If delayLoading is set to false (the default), then nothing is
* returned.
*/
function create(pItemId: Element | string, pItemImpl: {
addValue: (...params: any[]) => any;
afterModify: (...params: any[]) => any;
delayLoading: boolean;
disable: (...params: any[]) => any;
displayValueFor: (...params: any[]) => any;
enable: (...params: any[]) => any;
getValidationMessage: (...params: any[]) => any;
getValidity: (...params: any[]) => any;
getValue: (...params: any[]) => any;
hide: (...params: any[]) => any;
isChanged: (...params: any[]) => any;
isDisabled: (...params: any[]) => any;
getPopupSelector: (...params: any[]) => any;
loadingIndicator: (...params: any[]) => any;
nullValue: string;
refresh: (...params: any[]) => any;
reinit: (...params: any[]) => any;
removeValue: (...params: any[]) => any;
setFocusTo: Element | string | ((...params: any[]) => any);
setStyleTo: Element | string | ((...params: any[]) => any);
setValue: (...params: any[]) => any;
show: (...params: any[]) => any;
}): any;
/**
* This function is only for item plug-in developers. It provides a way for item plug-ins to initialize * without having to render a call to a JavaScript function. The handler function is called when the page * initializes.
* @example *This namespace is used for text and message localization related functions of Oracle Application Express. */ namespace lang { /** *
Add messages for use by {@link apex.lang.getMessage} and the format functions. Can be called multiple times. * Additional messages are merged. It is generally not necessary to call this function, because it is * automatically called with all the application text messages that have attribute Used in JavaScript set to on.
* @example *Load additional messages from the server.
*When an APEX page loads it automatically loads any text messages that have attribute Used in JavaScript * set to on. This function is useful when there are strings that are not always needed on the client * but can be loaded on demand.
* @example *getMessage to get the message text.Load additional messages from the server only if they are not already loaded.
*When an APEX page loads it automatically loads any text messages that have attribute Used in JavaScript * set to on. This function is useful when there are strings that are not always needed on the client * but can be loaded on demand.
* @example *Remove all messages. This method is rarely needed. Many Oracle Application Express components rely on client-side * messages, so if you clear the messages you need to add any needed messages again.
* @example *Return the message associated with the given key. * The key is looked up in the messages added with the {@link apex.lang.addMessages}, {@link apex.lang.loadMessages}, * or {@link apex.lang.loadMessagesIfNeeded} functions.
* @example *Return true if pKey exists in the messages added with the {@link apex.lang.addMessages}, * {@link apex.lang.loadMessages}, or {@link apex.lang.loadMessagesIfNeeded} functions.
* @example *Format a message. Parameters in the message, %0 to %9, are replaced with the corresponding function argument. * Use %% to include a single %. The replacement arguments are HTML escaped. * @example *
Formats a message. * Same as {@link apex.lang.formatMessage} except the message pattern is given directly. * It is already localized or isn't supposed to be. * It is not a key. The replacement arguments are HTML escaped.
* @example *Same as {@link apex.lang.formatMessage} except the replacement arguments are not HTML escaped. * They must be known to be safe or will be used in a context that is safe.
* @example *Same as {@link apex.lang.format}, except the replacement arguments are not HTML escaped. * They must be known to be safe or are used in a context that is safe.
* @example *The apex.locale namespace contains Oracle Application Express functions related to formatting numbers and * dates according to a specific locale. For localizing text messages see {@link apex.lang}.
*/ namespace locale { /** *Used to determine if the resources needed by some of the {@link apex.locale} functions * have been loaded.
* @example *Formats a number using a database format model similar to the SQL TO_CHAR(number) function.
See the Oracle SQL Language reference section on Format Models for more information on the * pFormat parameter. The format elements RN, TM, and EEEE are not supported.
* @example *Formats the given number in a compact, locale specific way. For example in the US English locale the * number 123400 would be formatted as "123.4K" and 1234000 as "1.23M".
* *This function relies on additional resources that are loaded when the page first loads. Calling this function * before the resources are loaded returns the number as an unformatted string. See {@link apex.locale.resourcesLoaded}.
* @example ** Note: The callbacks do not return anything, therefore the default show / hide behavior will happen after the * callback.
-
*
- pMsgType: Identifies the message type. Use {@link apex.message.TYPE} to identify whether showing an error or success message. *
- pElement$: jQuery object containing the element being shown. *
-
*
- pMsgType: Identifies the message type. Use {@link apex.message.TYPE} to identify whether showing an error or success message. *
- pElement$: jQuery object containing the element being hidden. *
This function displays all errors on the apex.message error stack. If you do not want to add to the stack, * you must first call clearErrors(). Errors will display using the current app’s theme’s templates. For page level * messages (where location = “page”), error messages use markup from the page template’s ‘Subtemplate > Notification’ * attribute. For item level messages (where location = “inline”), error messages use markup from the item’s * label template’s ‘Error Display > Error Template’ attribute.
*Note Theme Developers should bear in mind the following: *
-
*
- To display errors for a theme correctly, it must define both of the template attributes described above. * In addition, for inline errors the label template must reference the #ERROR_TEMPLATE# substitution string in * either the ‘Before Item’ or ‘After Item’ attributes of your label templates. *
- As a theme developer, you can influence or override what happens when showing page level errors. For more * information, please refer to {@link apex.message.setThemeHooks}, (specifically the beforeShow * callback function, where you would need to check for ‘pMsgType === apex.message.TYPE.ERROR’ to isolate when * showing page level errors). *
The apex.model namespace contains methods used to manage client side Application Express data models. These models * store data for display by UI components. They correspond to the view-model in the Model-View-ViewModel (MVVM) pattern. * See {@link model} for details.
*This namespace contains functions to manage the lifecycle of a model:
*-
*
- Use {@link apex.model.create} to create a model. *
- Use {@link apex.model.list} to list all the existing models. *
- Use {@link apex.model.get} to return an existing model. *
- Use {@link apex.model.release} to release a model once you are done with it. *
Models are reference counted so for every call to get or
* create you must call release. Failure to do so can
* result in unused models taking up memory. Typically the APEX region associated with the model will manage
* its life cycle.
*
Models typically act as an intermediary between data persisted on the server and one or more views on the client.
* The regionId option associates the model with an APEX region for the purpose of
* fetching and saving data. Models can be created without a regionId. These are
* known as local models and they cannot fetch data from or save data to the server.
*
There are also methods such as {@link apex.model.save}, {@link apex.model.anyChanges}, and {@link apex.model.anyErrors} * that operate on multiple models. *
* *Models can be arranged in a master detail configuration. This is done by providing the
* parentModel and parentRecordId
* options when creating the detail models. A single master model can have multiple kinds of detail models. For example
* projects can have tasks and members as details. Each kind of detail model has one or more model instances; each related
* to a record in the master model. Detail instance models share the same name and field configuration but each
* has a distinct instance id and different data. A model is uniquely identified by a {@link model.ModelId}, which in the case
* of a detail model contains the detail name and instance id. Detail models are cached so that data doesn't have to be
* fetched from the server unnecessarily. The view layer typically shows a view of the detail instance model that is
* associated with the current record of the master view. As the current record of the master changes the view layer
* changes the detail model instance the detail view is showing. The view layer will get a cached instance model if
* there is one and if not will create the instance model. The maximum number of detail instances to cache is controlled
* with the {@link apex.model.getMaxCachedModels} and {@link apex.model.setMaxCachedModels} functions. It is the least
* recently used model that is kicked out of the cache. Models that have changes are not destroyed unless
* {@link apex.model.destroy} is called.
A detail model can be a master to its own set of sub-detail models. This relationship can be nested to any depth.
*/ namespace model { /** * This callback is used by the {@link model#forEach} and {@link model#forEachInPage} methods. * @param pRecord - The current record. * @param pIndex - The zero based index within the model collection of the current record. * @param pId - The identity of the current record if the model *identityField option is given. If there is no identity then this is
* undefined for tree models and is the pIndex as a string for table models.
*/
type IteratorCallback = (pRecord: model.Record, pIndex: number, pId: string) => void;
/**
* Metadata properties that the model creates and uses.
* @property deleted - true if the record has been deleted otherwise false or undefined.
* @property inserted - true if the record is newly created and inserted/added to the collection otherwise false or undefined.
* @property autoInserted - true if the record was auto inserted (these records are not saved if not also updated)
* @property updated - true if the record has had any fields changed.
* @property original - When updated is true this is the original record before any changes.
* @property record - Reference to the record that this metadata is about.
* @property parent - The parent record of this record. Only applies to tree shape models.
* @property error - true if the record as a whole has an error.
* @property warning - true if the record as a whole has a warning.
* @property message - Only present when error
* or warning are true. Describes the error or warning condition.
* @property sel - true if the record is selected and false otherwise.
* @property highlight - A string that view layers can use to provide extra styling for the record.
* @property allowedOperations.delete - true if the record can be deleted.
* @property allowedOperations.update - true if the record can be updated.
* @property canEdit - Derived from allowedOperations.update
* @property canDelete - Derived from allowedOperations.delete
* @property endControlBreak - Used by views to implement control break UI.
* @property agg - For aggregate records this is the name of the aggregate function.
* @property grandTotal - For aggregate records this is true for the overall value (grand total) records.
* @property fields - An object that maps from a field name to
* metadata about the field.
*/
type RecordMetadata = {
deleted: boolean;
inserted: boolean;
autoInserted: boolean;
updated: boolean;
original: model.Record;
record: model.Record;
parent: model.Record;
error: boolean;
warning: boolean;
message: string;
sel: boolean;
highlight: string;
allowedOperations: {
delete: boolean;
update: boolean;
};
canEdit: boolean;
canDelete: boolean;
endControlBreak: boolean;
agg: any;
grandTotal: boolean;
fields: {
[key: string]: model.RecordFieldMetadata;
};
};
/**
* Metadata related to a specific record field.
* @property changed - true if the field has changed.
* @property stale - true if the value of this field depends on other fields and those fields have changed
* and this field has not been recalculated.
* @property error - true if the field has an error.
* @property warning - true if the field has a warning.
* @property message - Only present when error
* or warning are true. Describes the error or warning condition.
* @property disabled - true if the field is disabled. Disabled fields are written to the server as empty string.
* @property highlight - A string that view layers can use to provide extra styling for the field.
* @property ck - A checksum. If present and not null indicates the record field is readonly.
* @property url - Use for cells that are links. This is the link target. The cell value is the link label.
*/
type RecordFieldMetadata = {
changed: boolean;
stale: boolean;
error: boolean;
warning: boolean;
message: string;
disabled: boolean;
highlight: string;
ck: string;
url: string;
};
/**
* Information about an observer for subscribing to this model. See {@link model#subscribe} and * {@link model#unSubscribe}.
* @property [viewId] - A unique key that can be used to unsubscribe. * A DOM element id makes a good unique key. * @property onChange - A function to receive change notifications. The signature is *function(changeType, change)*
changeType is a string describing the change such as "delete"*
change is an object with details about the change.* See each notification for details. * @property [progressView] - jQuery object to center a progress spinner over while performing an * asynchronous network operation such as {@link model#fetch} or {@link model#save}. * @property [progressOptions] - Options object for {@link apex.util.showSpinner}. */ type Observer = { viewId?: string; onChange: (...params: any[]) => any; progressView?: jQuery; progressOptions?: any; }; /** *
A model is uniquely identified by a string name and optional string instance id. The instance id is used to * support multiple detail models in a master detail arrangement. The instance id is the identity value of the * record in the master model for which the detail model pertains. The form for a model id is "name" or a * tuple array ["name","instance"]
* @example *recordIsArray.
*/
type Record = any[] | any;
/**
* A model node is a synonym for {@link model.Record} that is more naturally used when the model has a tree shape.
*/
type Node = any[] | any;
/**
* The field metadata describes the field and affects how the model uses the field. It may contain additional
* properties especially if the metadata is shared with view layers.
* @property index - Only used when records are arrays. This is the index into the array where the field
* value is stored.
* @property defaultValue - This value is used when a new record is added or an existing record is duplicated
* and noCopy is true.
* The defaultValue has no effect for the identity, meta, children, and parent fields if defined.
* If there is no defaultValue empty string is used.
* If defaultValue is a function it is called and the return value is used as the field's value. The function
* is passed the model. If the new record is a copy of an existing record the source record is also passed in.
* @property dataType - The data type of the field value.
* @property calcValue - This is a function used to calculate the value for the field. When any of the
* fields listed in the dependsOn property change this function is called.
* The function signature is calcValue( argsArray, model, record ) return *.
* The values of the fields listed in dependsOn are passed
* in the argsArray. This function is also called when a record is received from the server and
* the value of this field is null or undefined.
* @property dependsOn - An array of field names from this model that this field depends on.
* When any of the fields named in this array change then this field is either marked stale or if there is
* a calcValue function the calcValue
* function is called to recalculate the value of this field.
* @property aggregates - An array of aggregate function names or objects implementing
* the aggregate interface (TBD). The built-in aggregate function names are: "COUNT", "COUNT_DISTINCT",
* "SUM", "AVG", "MIN", "MAX", "MEDIAN".
* @property parentField - Only applies if the model has a parentModel. When a new record is added or an existing record is
* duplicated and noCopy is true the value of this field is taken from the parentField of the parentModel
* This is useful for foreign key fields but can be any field that gets a default from the parentModel.
* @property noCopy - If true the field value is not copied when a record is copied/duplicated.
* @property readonly - If true the field cannot be edited.
* @property volatile - The field is generated by the server. It cannot be edited. It is not sent back to the server. This means
* that for records stored as arrays the volatile fields should be at the end or the server must account
* for the missing volatile fields when using other field's index. Volatile fields may depend on (are calculated
* from) other fields and the value may be considered stale if the record is edited. It is up to the view
* layers to make this determination.
* @property virtual - A virtual field has no associated data. None of the other properties apply. The main purpose for
* including a virtual field is so that view layers and the model can share the same field metadata.
* This allows view layers to have fields that don't have corresponding data in the model.
*/
type FieldMeta = {
index: string;
defaultValue: any;
dataType: string;
calcValue: (...params: any[]) => any;
dependsOn: any[];
aggregates: any[];
parentField: string;
noCopy: boolean;
readonly: boolean;
volatile: boolean;
virtual: boolean;
};
/**
* A callback function to do additional access checking. See the check
* option property of {@link apex.model.create} and the {@link model#check} method.
Create a model with the given identity, options and optionally initial data. * When you are done with the model you must call {@link apex.model.release}. Or if you are sure no one else is using it * you can call {@link apex.model.destroy}.
* @example *index property. The default is false.
* @param pOptions.hasTotalRecords - Only applies if shape is "table".
* If true the sever will always provide the total
* number of records. The default is false unless paginationType is "none".
* @param pOptions.genIdPrefix - A string prefix to use when generating ids for inserted records. The default is "t".
* @param pOptions.fields - This required option defines the fields of each record.
* Each property is the name of a field. The value is a {@link model.FieldMeta} object with metadata about the field that
* the model uses.
* @param pOptions.regionId - Primary region ID that this model is associated with for the purpose of exchanging
* data with the APEX server. If there is no regionId then the model cannot use standard requests to fetch or save
* data and therefore is just a local model. The default is null.
* @param pOptions.ajaxIdentifier - The Ajax Identifier used to identify the Ajax call to fetch or save data.
* The default is null.
* @param pOptions.pageItemsToSubmit - An array of page item names to submit when fetching and saving data.
* The default is null.
* @param pOptions.regionData - Additional data to send at the region level for all requests. The default is an empty object.
* @param pOptions.fetchData - Additional data to send in fetch requests. The default is an empty object.
* @param pOptions.saveData - Additional data to send in save requests. The default is an empty object.
* @param pOptions.requestOptions - The properties of this object are included
* in the options object of {@link apex.server.plugin} for any ajax requests made by the model.
* @param pOptions.version - This is the version (could be a hash) of the model definition. The value
* is opaque to the model. It is sent in all requests; fetch, save etc. If the server detects that the version is
* different than it expects then it returns an error. This is to ensure that the client and server agree on the
* general model and field definitions. The default is 1. This option currently has no effect and is reserved
* for future use.
* @param pOptions.parentModel - Model identifier of parent (master) model or null if there is no parent.
* The default is null.
* @param pOptions.parentRecordId - Only applies if parentModel is given. The record id of the record in the
* parent model that this model is associated with. Typically this model's ModelId instance and the parentRecordId
* are the same. The default is null.
* @param pOptions.editable - If true the model is editable and false otherwise. The default is false.
* @param pOptions.onlyMarkForDelete - If false deleted records are removed from the collection.
* If true then deleted records are marked as deleted but remain in the collection. The default is true.
* @param pOptions.identityField - Name of identity field or an array of identity field names if the
* records have a multi valued primary key. Required if editable is true. It is a best practice to specify the
* identityField even if the model is not editable as it can be useful for pagination, selection, and fetching
* additional data. The default is null.
* @param pOptions.childrenField - This only applies for tree shape models. The name of the field that
* contains an array of node children. The default is null.
* @param pOptions.parentIdentityField - This only applies for tree shape models. The name of parent node
* identity field. The default is null.
* @param pOptions.metaField - The name of meta field. The meta field stores metadata about the record and
* possibly record fields The default is null.
* @param pOptions.check - A function that is called to do additional permission checking.
* @param pOptions.paginationType - One of "none", "one", "progressive".
* -
*
- none: No paging. The server has given all the data it has (it may be capped but you can't get more) *
- one: The model contains just one page at a time. When it asks the server for a new page it * replaces the previous one. *
- progressive: The model will keep adding to its collection as it gets additional pages from * the server *
This only applies to table shape models. The default is "none".
* @param pOptions.pageSize - This is the number of table rows (records) to fetch from the server. * This only applies to table shape models. The default is 100. * @param pOptions.makeLoadingIndicator - function(jQuery[] progressViews, Object[] progressOptions) * This is a function that receives an array of progress views and a corresponding array of progress options and returns * a function suitable for the {@link apex.server.plugin}loadingIndicator option.
* It can also return null to disable showing any loading indicator.
* If not specified the default is to show the standard APEX progress spinner centered over any visible view(s)
* of the model. A view informs the model about its existence by subscribing to the model and passing in the
* progressView and optional progressOptions
* options. See also the {@link model#subscribe} method and {@link model.Observer}.
* @param [pData] - Initial data to add to the model. For table shape data it is an array of
* {@link model.Record}. For tree shape models it is a {@link model.Node} for the root. For record shape data it
* is a single {@link model.Record}. If null or not given there is no initial data.
* @param [pTotal] - Total number of records in the servers collection. Only applies for table shape models.
* @param [pMoreData] - If true there is more data available on the server for this model. If false
* pData contains all the data. If omitted or null determine if there is more
* data based on pData and pTotal.
* If pTotal is not given assume there is more data on server.
* Only applies for table shape models and only if paginationType is not "none".
* @param [pDataOverflow] - If true there is more than the maximum allowed records for this model.
* Only applies for table shape models.
*/
function create(pModelId: model.ModelId, pOptions: {
shape: string;
recordIsArray: boolean;
hasTotalRecords: boolean;
genIdPrefix: string;
fields: {
[key: string]: model.FieldMeta;
};
regionId: string;
ajaxIdentifier: string;
pageItemsToSubmit: string[];
regionData: any;
fetchData: any;
saveData: any;
requestOptions: any;
version: number | string;
parentModel: model.ModelId;
parentRecordId: string;
editable: boolean;
onlyMarkForDelete: boolean;
identityField: string | string[];
childrenField: string;
parentIdentityField: string;
metaField: string;
check: model.CheckCallback;
paginationType: string;
pageSize: number;
makeLoadingIndicator: (...params: any[]) => any;
}, pData?: any[] | any, pTotal?: number, pMoreData?: boolean, pDataOverflow?: boolean): model;
/**
* Returns an array of all the currently defined model identifiers in no particular order.
* If pModelId is null or not provided all models are listed.
* If pModelId contains just a model name then just that model if any and all
* instances with the same model name if any are returned.
* If pModelId contains a model and an instance then just that model instance is included.
* Specifying pModelId is most useful when pIncludeRelated is true.
* @param [pIncludeLocal] - If true models that don't have a regionId will be included.
* @param [pModelId] - Model identifier as given in call to {@link apex.model.create} or just a model name.
* @param [pIncludeRelated] - If true then any dependents of any listed models are included.
* @returns Array of model identifiers
*/
function list(pIncludeLocal?: boolean, pModelId?: model.ModelId, pIncludeRelated?: boolean): model.ModelId[];
/**
* Returns true if any of the specified models have changes.
* @example
*
regionId
* will be included in the check for changes.
* @param [pModelId] - Model identifier as given in call to {@link apex.model.create} or just a model name.
* See {@link apex.model.list} for how this parameter is used to select which models to operate on.
* @param [pIncludeRelated] - If true then any dependents of any selected models are included in check
* @returns true if any of the specified models have changed.
*/
function anyChanges(pIncludeLocal?: boolean, pModelId?: model.ModelId, pIncludeRelated?: boolean): boolean;
/**
* Returns true if any of the specified models have errors.
* @example
* regionId
* will be included in check for errors.
* @param [pModelId] - Model identifier as given in call to {@link apex.model.create} or just a model name.
* See {@link apex.model.list} for how this parameter is used to select which models to operate on.
* @param [pIncludeRelated] - If true then any dependents of any selected models are included in check.
* @returns true if any of the specified models have errors.
*/
function anyErrors(pIncludeLocal?: boolean, pModelId?: model.ModelId, pIncludeRelated?: boolean): boolean;
/**
* Low level function to add changes for any of the specified models to a request. * Changes are added to the provided request data. This doesn't actually send the request to the server. * In most cases {@link apex.model.save} should be used rather than this function.
* @param pRequestData - An initial request object that will have all changes for the specified models added to it. * @param [pModelId] - Model identifier as given in call to {@link apex.model.create} or just a model name. * See {@link apex.model.list} for how this parameter is used to select which models to operate on. * @param [pIncludeRelated] - If true then any dependents of any selected models are included if they have changes. * @returns A function that must be called with the promise returned from the save request. */ function addChangesToSaveRequest(pRequestData: any, pModelId?: model.ModelId, pIncludeRelated?: boolean): (...params: any[]) => any; /** *Save any of the specified models that have changes. This consolidates all the model data to save into a single * request.
* @example *Release a model if it is not being used but may be used again in the future. This allows the model * to be destroyed if needed to conserve memory.
*Models are reference counted. For every call to get or create a call to release with the same model id is * required. When the reference count is zero the model is destroyed unless it is changed or if it has a * parent model, in which case it is cached.
* @example *Destroy and remove a model by its identifier. This bypasses reference counting and caching. This method should * not be used unless you are sure that no one else is using the model.
*If pModelId is a string model name and there are one or more instances
* they will all be destroyed.
Opens the specified page (pWhere) in the current window.
* @example *NO and
* setting RP to reset pagination for an Interactive Report on page 3.
* The substitution string, APP_SESSION is substituted on the server with the current session ID.APP_SESSION is substituted on the server with the current session ID.$v( "pFlowId" )
* in the current session, $v("pInstance"), which is processed on the client.
* This example demonstrates calling this function from within a JavaScript file.P1_URL".This namespace contains functions related to a popup window opened with {@link apex.navigation.popup|apex.navigation.popup}.
*/ namespace popup { /** *Sets the value of the item in the parent window (pItem) with (pValue), and then closes the popup window. * This function should only be called from an Oracle Application Express page that has been opened as a popup window, * via a call to {@link apex.navigation.popup|apex.navigation.popup}, where the call to {@link apex.navigation.popup|apex.navigation.popup} * is originating from another Oracle Application Express page.
* @example *pValue.
* @param pValue - The value to be save to the page item referenced in pItem.
*/
function close(pItem: Element | string, pValue: string): void;
}
/**
* Opens the given URL in a new typically named popup window. If a window with that name already exists, it is reused. * If no name is given or the name is "_blank" then a new unnamed popup window is opened. The names "_self", "_parent" * and "_top" should not be used. The window name is made unique so that it cannot be shared with other apps.
* *Every effort is made to focus the window. The intention is that the window will be a popup window * and not a tab. The default window features are such that most browsers should open a new window.
* *Note: To avoid being suppressed by a popup blocker, call this from a click event handler on a link or a button.
* @example *myPopupWindow.
* It is best to supply the url, name and possibly the height and width; all other parameters will have their default value.myPopupWindow.
* Some additional parameters are also set in the call, to control scrolling, resizing and the visibility of a toolbar.
* The variable myTriggeringElement is used to define the triggering element of the popup,
* a button named myButton. Using a call to {@link apex.navigation.dialog.registerCloseHandler},
* a new handler can be defined, to associate the close action of the dialog with the button.Opens the given URL in a new named window or tab (the browser / browser user preference settings may control * if a window or tab is used). If a window with that name already exists it is reused. The names "_self", "_parent" * and "_top" should not be used. The window name is made unique so that it cannot be shared with other apps. * Every effort is made to then focus the new window.
* *Unlike a popup, the new window is intended to be fully functional. This is intended to be as close
* as you can get to a normal anchor with a target (<a target="name" href="...">)
* behavior from JavaScript but with the feature of focusing the window in all browsers by default.
If option favorTabbedBrowsing is true:
* For IE, Edge, and Firefox, the user may need to manually focus the
* tab (assuming the browser is configured to open pages in tabs).
If option favorTabbedBrowsing is not true (the default):
* For IE and Firefox, the page will be opened in a new browser window
* (unless explicitly overridden by a browser setting). But it will very likely be able to focus
* the new page.
Once the named window is open the favorTabbedBrowsing setting doesn't apply to that window.
Note: Firefox, Edge, and IE will not focus a tab if that tab isn't the currently active tab in its browser window.
* *Note: For Opera the Advanced/content > JavaScript Options: “Allow raising of windows” must be checked in order for * focus to work.
* *Note: To avoid being suppressed by a popup blocker call this from a click event handler on a link or button.
* @example *url in a new window.
* The new window can be accessed from variable myWindow.pWindowName to make it unique.
* @param [pOptions.favorTabbedBrowsing] - If true, don't try to force a new window for the benefit of being able to focus it.
* @param [pOptions.noopener] - If true the new opened window does not have access to this window via its
* window.opener property.
* The default is true if the new window name is "_blank" and false otherwise.
* @returns The window object of named window or null if window was not opened. Note that if
* option noopener is true then the return value is always null.
*/
function openInNewWindow(pURL: string, pWindowName?: string, pOptions?: {
altSuffix?: string;
favorTabbedBrowsing?: boolean;
noopener?: boolean;
}): any | null;
/**
* This namespace contains functions related to a dialog opened with {@link apex.navigation.dialog|apex.navigation.dialog}. * All of the functions in the {@link apex.navigation.dialog|apex.navigation.dialog} namespace need to be run in the context of the specified dialog page.
*/ namespace dialog { /** *Executes an action and then closes the dialog window.
* @example *pAction parameter is
* a function that redirects to a different modal dialog page, specified in the URL:P3_EMPNO and P3_ENAME. The values from the page items can then be used by the
* page that launched the modal dialog, via a Dialog Closed Dynamic Action event.dialogPageId and its value of 3. The returned value can be used by the
* page that launched the modal dialog, via a Dialog Closed Dynamic Action event, to identify the
* page ID of the modal dialog that triggered the event.-
*
- a URL which will trigger a redirect in the parent page *
- a function to redirect to a different dialog page *
- false to cancel the dialog *
- an object of page items and values which will be exposed in the apexafterclosedialog event *
- an array of page item names, the values will be gathered from the page items to create * an object of page item values to be exposed in the apexafterclosedialog event *
Closes the dialog window.
* @example *Registers the internal "close" event of a dialog. The event will be triggered by fireCloseEvent and depending on
* the passed in pAction will:
-
*
- Re-use the existing dialog and navigate to a different dialog page *
- Navigate to a different page in the caller *
- Cancel the dialog *
- Close the dialog and trigger the "apexafterclosedialog" event *
myPopupWindow.
* Some additional parameters are also set in the call, to control scrolling, resizing and the visibility of a toolbar.
* The variable myTriggeringElement is used to define the triggering element of the popup,
* a button named myButton. Using a call to {@link apex.navigation.dialog.registerCloseHandler},
* a new handler can be defined, to associate the close action of the dialog with the button.Fires the internal "close" event of a dialog which was registered with the registerCloseHandler when the dialog * was opened.
* @example *myTriggeringElement is used
* to define the triggering element of the dialog, a button named myButton.
* The page items P3_EMPNO and
* P3_ENAME are returned to the launching page. The values from the page items can then be used by the
* page that launched the modal dialog, via a Dialog Closed Dynamic Action event.Opens the specified page ( pUrl ) in a dialog. The modal option determines if the page is
* a modal page or a non-modal page.
A modal page is loaded in an iframe using jQuery UI dialog widget. It is an overlay window positioned within the same browser window. * When a modal dialog is active, the user is unable to interact with the rest of the page, until the dialog is closed.
* *A non-modal page is loaded in a new window using the {@link apex.navigation.popup|apex.navigation.popup} function. A user can interact * with a non-modal dialog and content on the page.
* *Note: Typically this API call is generated by the server when the page target is a modal page or by using APEX_UTIL.PREPARE_URL. * At a minimum the url of the dialog page must be generated on the server so that the correct dialog checksum can be generated.
* @example *mybutton_static_id is used to launch the modal dialog. Using an associated Dynamic Action,
* the click of the button invokes the execution of the following JavaScript code:resizable, set to*
resizable:true
This namespace is used for all client-side page related functions of Oracle Application Express.
*/ namespace page { /** *This function submits the page. The shorter alias for this function {@link apex.submit} with the same parameters * can also be used. Depending on the value of the page's Reload on Submit attribute, the page is submitted using * Ajax or with a normal form submission post request.
* *This function triggers a {@link apex.event:apexbeforepagesubmit} event on the {@link apex.gPageContext$} which can be canceled * by an event handler. If canceled, the page is not submitted. Just before the page is submitted, this function * triggers a {@link apex.event:apexpagesubmit} event on the {@link apex.gPageContext$}, which cannot be canceled.
* @example *Displays a confirmation dialog showing a message, pMessage, and depending on the user's choice, submits the page or * cancels submitting. Depending on the value of the page's Reload on Submit attribute, the page is submitted using * Ajax or with a normal form submission post request.
* *Once the user chooses to submit the page, the behavior is the same as for the {@link apex.page.submit} function. * The shorter alias for this function {@link apex.confirm} with the same parameters can also be used.
* @example *Note: The default message is deprecated. In the future this argument will be required.
* @param [pOptions] - If this is a string, it will be used to set the REQUEST value. * If this is null or omitted, the page will be submitted with no REQUEST value. * If this is an object, you can define the following properties: * @param [pOptions.request] - The REQUEST value. For the confirm function the default is “Delete”. * @param [pOptions.set] - An object containing name/value pairs of items to set on the page prior to submission. * The object properties are page item names and the item value is set to the property value. * The default is to not set any page items. * @param [pOptions.showWait] - If true, a 'Wait Indicator' spinner is displayed, which can be useful when * running long page operations. The default is false. * @param [pOptions.submitIfEnter] - This option is not useful for the confirm function. * @param [pOptions.reloadOnSubmit] - Override the reload on submit setting of the page. * Set to one of the following: "A" (always) or "S" (success) * @param [pOptions.ignoreChange] - If true (the default) and the warnOnUnsavedChanges feature is enabled, no * warning will be given if there are changes. If false and the warnOnUnsavedChanges feature is enabled and there * are changes, a warning will be given. If warnOnUnsavedChanges feature is disabled, there is never a warning. * Set this to false if the submit will not actually save the data. * @param [pOptions.validate] - If true, check the validity of page items and models before submitting the page. * If anything is not valid then show an alert dialog and don't submit the page. The default is false. */ function confirm(pMessage?: string, pOptions?: { request?: string; set?: any; showWait?: boolean; submitIfEnter?: Event; reloadOnSubmit?: string; ignoreChange?: boolean; validate?: boolean; }): void; /** *Check if any page items or submittable Application Express {@link models} on the page are invalid. * Any errors are shown inline using the {@link apex.message.showErrors} function.
* *Note: This function does not actually perform any validation. Use HTML 5 validation attributes * or API to validate items.
* @example *Return true if any page items or Application Express models on this page have changed since last being
* sent to the server. Items that are disabled or are configured to ignore changes are not included in the check.
* This will call the pExtraIsChanged function set in
* {@link apex.page.warnOnUnsavedChanges} if one was supplied and only if no other changes are found first.
Initialize a handler that checks for unsaved changes anytime the page is about to unload. * This is safe to call multiple times. The pMessage and pExtraIsChanged parameters override any previous values. * This function is called automatically when the page attribute Warn on Unsaved Changes is set to yes. * The main reason to call this manually is to customize the parameters.
*See also {@link item#isChanged}.
* @example *Note: Most browsers do not show this message.
* @param [pExtraIsChanged] - Optional additional function to be called, checking if there are any unsaved changes. * It should return true if there are unsaved changes, and false otherwise. * It is only called if there are no changes to any models or page items. * This is useful if there are non-standard state-full inputs on the page that are not Application Express items * and do not keep their state in an Application Express model. It allows writing a custom function to detect * if those non-standard inputs have changed. */ function warnOnUnsavedChanges(pMessage?: string, pExtraIsChanged?: (...params: any[]) => any): void; /** *Call to remove the handler that checks for unsaved changes. This is useful to do before any kind of cancel
* operation where the user is intentionally choosing to lose the changes. It is not normally necessary to call
* this function because the declarative attribute Warn on Unsaved Changes with value Do Not Check will do it
* automatically. Adding the class js-ignoreChange to a link (anchor element)
* or button will cause this function to be called before the link or button action.
Return a {@link region} interface for the given region id. The returned region interface object can then be * used to access region related functions and properties.
* *Region plug-in developers can define the behavior of their region by calling {@link apex.region.create}.
* @example *pRegionId.
*/
function region(pRegionId: string): region | null;
/**
* The apex.region namespace contains global functions related to Oracle Application Express regions. * The {@link apex.region|apex.region} function provides access to a {@link region} interface for a specific region.
*/ namespace region { /** *This function is only used by region plug-in developers. It provides a plug-in specific implementation for the region.
* *Use this function to give a region plug-in a set of behaviors defined by pRegionImpl.
* The pRegionImpl parameter can provide its own implementation for standard
* methods (such as refresh, focus, widget) or omit them to get the default implementation. It can add its own methods as well.
* It should include a type string property that specifies the type of region. If the region is implemented
* with a jQuery UI style widget (using widget factory) then it should provide an implementation for the
* {@link region#widget} method and define the {@link region#widgetName} property so that the
* {@link region#call} method works.
This function is only for region plug-in developers. It will destroy and remove the behaviors associated with a * region element. It does not remove the region element from the DOM. It is not necessary to call this function * if the region will exist for the lifetime of the page. If the region is implemented by a widget that has a * destroy method then this function can be called when the widget is destroyed.
* @example *This function returns true if and only if there is a DOM element with id equal to pRegionId that has had * a {@link region} interface created for it with {@link apex.region.create}.
* *To support older regions that * don't implement a region interface (by calling apex.region.create) the default implementation of * apex.region will attempt to treat any DOM element with an id as if it were an Application Express region. * This function allows you to distinguish true Application Express regions from arbitrary DOM elements.
* @example *Returns the region that contains the pTarget element.
* Returns null if there is no pTarget element or if it is
* not in a region that has been initialized with a call to {@link apex.region.create}.
refresh-button
* when it is clicked.pTarget is not inside a region.
*/
function findClosest(pTarget: Element | string): region | null;
}
/**
* The apex.server namespace contains all Ajax functions to communicate with the Oracle Application Express server.
*/
namespace server {
/**
* This function calls the PL/SQL ajax function that has been defined for a plug-in. This function is a * wrapper around the jQuery.ajax function and supports a subset of the jQuery.ajax options plus additional * Oracle Application Express specific options.
* *The plug-in PL/SQL Ajax function is identified using the value returned by the PL/SQL package * apex_plugin.get_ajax_identifier. There are two ways to provide the plug-in Ajax identifier:
*-
*
- Provide the pAjaxIdentifier as the first argument *
- Provide information about the region(s) including the ajaxIdentifier in the * pData object structure. See pData description for details. *
{
* "regions": [ {
* "id": <region-id-or-static-id>,
* "ajaxIdentifier": <ajaxIdentifier>,
* <any other data specific to the region plug-in>
* }, ...]
* }
* The following properties are treated as special:
* @param [pData.pageItems] - Identifies the page or column items that will be * included in the request. It can be a jQuery selector, jQuery object, Element, or an array of item names. * These items will be made available in session state on the server. If pageItems contains column items then * pOptions should include the target property, so that the region session state context can be determined. * @param [pData.xnn] - Represents properties with names x01 to x20. These properties are moved out of the p_json object * and sent as x01 - x20 scalar parameters. * @param [pData.fnn] - Represents properties with names f01 to f20. These properties are moved out of the p_json object * and sent as f01 - f20 array parameters. * @param [pOptions] -An object that is used to set additional options to control the Ajax call * including before and after processing. See jQuery documentation of jQuery.ajax for these supported * options: accepts, dataType, beforeSend, contents, converters, dataFilter, headers, complete, statusCode, error, * success. The dataType option defaults to json. The async option is deprecated and will be removed in a * future release. See {@link https://docs.jquery.com/}
*The following Oracle Application Express specific options are supported:
* @param [pOptions.refreshObject] - A jQuery selector string, jQuery object, or Element * that identifies the DOM element that the {@link apex.event:apexbeforerefresh} and {@link apex.event:apexafterrefresh} * events are triggered on. If this option is not supplied these events are not triggered. * @param [pOptions.refreshObjectData] - Only applies if the refreshObject option is given. * Specifies extra data that is passed in the {@link apex.event:apexbeforerefresh} * and {@link apex.event:apexafterrefresh} events so that any handlers * defined for these events can access this data. In Dynamic Actions defined for the Before Refresh or * After Refresh events, this can be accessed from JavaScript using thethis.data property.
* For custom jQuery event handlers, this can be accessed through the pData parameter of the event handler.
* @param [pOptions.clear] - A no argument function that is called after the
* {@link apex.event:apexbeforerefresh} event has fired and before the actual Ajax call is made.
* This function can be used to clear the DOM or any other state maintained
* by the Element or component for which this Ajax request is being made.
* @param [pOptions.loadingIndicator] - Identifies the element(s) that will
* have a loading indicator (progress spinner) displayed next to it during the Ajax call. The element can be
* specified with a jQuery selector, jQuery object or Element. The loadingIndicator can also be a function that
* receives the loading indicator as a jQuery object, which it can use as is or modify or replace and attach to the
* DOM where appropriate. The function must return a reference to the jQuery loading indicator or return a no
* argument function that is called to stop and/or remove the progress indicator. For example:
* function( pLoadingIndicator ) {
* return pLoadingIndicator.prependTo(
* apex.jQuery( "td.shuttleControl", gShuttle) );
* }
* -
*
- before: Displays before the DOM element(s) defined by loadingIndicator. *
- after: Displays after the DOM element(s) defined by loadingIndicator. *
- prepend: Displays inside at the beginning of the DOM element(s) defined by loadingIndicator. *
- append: Displays inside at the end of the DOM element(s) defined by loadingIndicator. *
- centered: Displays in the center of the DOM element defined by loadingIndicator. *
- page: Displays in the center of the page. *
{
* name: "updateList",
* action: "replace"
* }
* If no queue option is given, the request is made right away without regard to any previous requests.
*The name property specifies the name of the queue to add this request to.
*The action property can be one of "wait" (the default), "replace", "lazyWrite".
*-
*
- wait: This action is the default and is used to send requests one after the other. * When the action is wait, the request is added to the named queue. If there are no other requests in that * queue, in progress or waiting, then this request is executed. Otherwise it waits on the named queue until * the ones before it are complete. *
- replace: This action is used when this current request makes any previous requests on the named queue, * in progress or waiting, obsolete or invalid. This current request aborts any in progress request and clears * out any waiting requests on the named queue and then is executed. * Waiting requests are rejected with status "superseded". *
- lazyWrite: This action is used to throttle requests to the server to persist data. This should only be used * to persist non-critical data such as user interface settings or state. Use when the data may change * frequently and only the last data values need to be saved. For example this is useful for persisting * splitter position, or tree expansion and focus state etc. The queue name is unique for each data unit. * For example if you were saving the position of two different splitters use a unique name for each one so that * latest update to one doesn't overwrite a previous lazy write of the other. When using lazyWrite Queue the * refreshObject, clear, loadingIndicator, and loadingIndicatorPosition are most likely not useful because * nothing is being loaded or refreshed. *
It is possible to mix requests with wait and replace actions on the same queue. The lazyWrite action * should not be used with a queue name that is also used with wait and replace actions.
* @param [pOptions.target] - The target element (DOM element or jQuery Selector) that this request pertains to. * This is used to get session state context from the enclosing region. This option must be provided if pageItems * property of pData contains any column items. * @returns A promise object. The promisedone method is called
* if the Ajax request completes successfully. This is called in the same cases and with the same arguments as
* the success callback function in pOptions.
* The promise fail method is called if the Ajax request completes with an error
* including internally detected Oracle Application Express errors.
* This is called in the same cases and with the same arguments as the error
* callback function in pOptions.
* The promise also has an always method that is called after
* done and error. The promise is returned
* even when queue options are used. The promise is not a jqXHR object
* but does have an abort method.
* The abort method does not work for requests that use any queue options.
* In addition the promise fail method can be be called
* with textStatus of "superseded" or "abort" depending on
* queuing options. If the {@link apex.event:apexbeforerefresh} event cancels the request
* the textStatus is "cancel".
* For an error response from the APEX server the textStatus is "APEX"
* and there may be more info in the errorThrown argument.
*/
function plugin(pAjaxIdentifier?: string, pData?: {
pageItems?: string | jQuery | Element | string[];
xnn?: string;
fnn?: string | any[];
}, pOptions?: {
refreshObject?: jQuery | Element | string;
refreshObjectData?: any | any[];
clear?: (...params: any[]) => any;
loadingIndicator?: string | jQuery | Element | ((...params: any[]) => any);
loadingIndicatorPosition?: string;
queue?: any;
target?: jQuery | Element;
}): PromiseReturns the URL to issue a GET request to the PL/SQL Ajax function which has been defined for a plug-in.
* @example *This function returns a URL to issue a GET request to the current page or page specified in pPage.
* @example *This function calls a PL/SQL on-demand (Ajax Callback) process defined on page or application level. * This function is a wrapper around the jQuery.ajax function and supports a subset of the jQuery.ajax options * plus additional Oracle Application Express specific options.
* @example *data parameter to the success callback contains the response returned
* from on-demand process.{
* "regions": [ {
* "id": <region-id-or-static-id>,
* <any other data specific to the region plug-in>
* }, ...]
* }
* The following properties are treated special:
* @param [pData.pageItems] - Identifies the page or column items that will be * included in the request. It can be a jQuery selector, jQuery object, Element, or array of item names. * These items will be made available in session state on the server. If pageItems contains column items then * pOptions should include the target property so that the region session state context can be determined. * @param [pData.xnn] - Represents properties with names x01 to x20. These properties are moved out of the p_json object * and sent as x01 - x20 scalar parameters. * @param [pData.fnn] - Represents properties with names f01 to f20. These properties are moved out of the p_json object * and sent as f01 - f20 array parameters. * @param [pOptions] -An object that is used to set additional options to control the Ajax call * including before and after processing. See jQuery documentation of jQuery.ajax for these supported * options: accepts, dataType, beforeSend, contents, converters, dataFilter, headers, complete, statusCode, error, * success. The dataType option defaults to json. The async option is deprecated and will be removed in a * future release. See {@link https://docs.jquery.com/}
*The following Oracle Application Express specific options are supported:
* @param [pOptions.refreshObject] - A jQuery selector string, jQuery object, or Element * that identifies the DOM element that the {@link apex.event:apexbeforerefresh} and {@link apex.event:apexafterrefresh} * events are triggered on. If this option is not supplied these events are not triggered. * @param [pOptions.refreshObjectData] - Only applies if the refreshObject option is given. * Specifies extra data that is passed in the {@link apex.event:apexbeforerefresh} * and {@link apex.event:apexafterrefresh} events so that any handlers * defined for these events can access this data. In Dynamic Actions defined for the Before Refresh or * After Refresh events, this can be accessed from JavaScript using thethis.data property.
* For custom jQuery event handlers, this can be accessed through the pData parameter of the event handler.
* @param [pOptions.clear] - A no argument function that is called after the
* {@link apex.event:apexbeforerefresh} event has fired and before the actual Ajax call is made.
* This function can be used to clear the DOM or any other state maintained
* by the Element or component for which this Ajax request is being made.
* @param [pOptions.loadingIndicator] - Identifies the element(s) that will
* have a loading indicator (progress spinner) displayed next to it during the Ajax call. The element can be
* specified with a jQuery selector, jQuery object or Element. The loadingIndicator can also be a function that
* receives the loading indicator as a jQuery object, which it can use as is or modify or replace and attach to the
* DOM where appropriate. The function must return a reference to the jQuery loading indicator or return a no
* argument function that is called to stop and/or remove the progress indicator. For example:
* function( pLoadingIndicator ) {
* return pLoadingIndicator.prependTo(
* apex.jQuery( "td.shuttleControl", gShuttle) );
* }
* -
*
- before: Displays before the DOM element(s) defined by loadingIndicator. *
- after: Displays after the DOM element(s) defined by loadingIndicator. *
- prepend: Displays inside at the beginning of the DOM element(s) defined by loadingIndicator. *
- append: Displays inside at the end of the DOM element(s) defined by loadingIndicator. *
- centered: Displays in the center of the DOM element defined by loadingIndicator. *
- page: Displays in the center of the page. *
{
* name: "updateList",
* action: "replace"
* }
* If no queue option is given, the request is made right away without regard to any previous requests.
*The name property specifies the name of the queue to add this request to.
*The action property can be one of "wait" (the default), "replace", "lazyWrite".
*-
*
- wait: This action is the default and is used to send requests one after the other. * When the action is wait, the request is added to the named queue. If there are no other requests in that * queue in progress or waiting, then this request is executed. Otherwise it waits on the named queue until * the ones before it are complete. *
- replace: This action is used when this current request makes any previous requests on the named queue * in progress or waiting obsolete or invalid. This current request aborts any in progress request and clears * out any waiting requests on the named queue and then is executed. * Waiting requests are rejected with status "superseded". *
- lazyWrite: This action is used to throttle requests to the server to persist data. This should only be used * to persist non-critical data such as user interface settings or state. Use when the data may change * frequently and only the last data values need to be saved. For example this is useful for persisting * splitter position, or tree expansion and focus state etc. The queue name is unique for each data unit. * For example if you were saving the position of two different splitters use a unique name for each one so that * latest update to one doesn't overwrite a previous lazy write of the other. When using lazyWrite Queue the * refreshObject, clear, loadingIndicator, and loadingIndicatorPosition are most likely not useful because * nothing is being loaded or refreshed. *
It is possible to mix requests with wait and replace actions on the same queue. The lazyWrite action * should not be used with a queue name that is also used with wait and replace actions.
* @param [pOptions.target] - The target element (DOM element or jQuery Selector) that this request pertains to. * This is used to get session state context from the enclosing region. This option must be provided if pageItems * property of pData contains any column items. * @returns A promise object. The promisedone method is called
* if the Ajax request completes successfully. This is called in the same cases and with the same arguments as
* the success callback function in pOptions.
* The promise fail method is called if the Ajax request completes with an error
* including internally detected Oracle Application Express errors.
* This is called in the same cases and with the same arguments as the error
* callback function in pOptions.
* The promise also has an always method that is called after
* done and error. The promise is returned
* even when queue options are used. The promise is not a jqXHR object
* but does have an abort method.
* The abort method does not work for requests that use any queue options.
* In addition the promise fail method can be be called
* with textStatus of "superseded" or "abort" depending on
* queuing options. If the {@link apex.event:apexbeforerefresh} event cancels the request
* the textStatus is "cancel".
* For an error response from the APEX server the textStatus is "APEX"
* and there may be more info in the errorThrown argument.
*/
function process(pName: string, pData?: {
pageItems?: string | jQuery | Element | string[];
xnn?: string;
fnn?: string | any[];
}, pOptions?: {
refreshObject?: jQuery | Element | string;
refreshObjectData?: any | any[];
clear?: (...params: any[]) => any;
loadingIndicator?: string | jQuery | Element | ((...params: any[]) => any);
loadingIndicatorPosition?: string;
queue?: any;
target?: jQuery | Element;
}): PromiseLoad JavaScript files asynchronously using RequireJS require or jQuery getScript. * It is rare that an APEX app needs to dynamically load JavaScript but if it does it should use this rather than * getScript. * The reason is that RequreJS may or may not be on a page. If it is and libraries that are RequireJS aware are loaded * they will give an error because they expect to be loaded by a call to require. If RequireJS is not on the page then * require cannot be used.
* @example *The {@link apex}.storage namespace contains all functions related browser storage features such as cookies and session storage.
* * *Local storage and session storage, collectively known as web storage, are a browser feature that securely stores key value pairs * associated with an origin (web site). The keys and values are strings. The amount of storage space for web storage is greater than * that of cookies but it is not unlimited. Another advantage over cookies is that the key value pars are not transmitted with each request.
* *Both local storage and session storage use the same API to set, get, and remove name value pairs. The difference is that * session storage goes away when the browser session ends and local storage is available even when the browser restarts. * Keep in mind that the browser is free to limit or delete data stored in local storage at the user's request. Unlike data * stored on the server local storage is not shared between browsers on different machines or even different browsers on the same machine.
* *Because APEX supports multiple applications, multiple workspaces and even instances of the same application running in multiple * workspaces there can arise conflicts with using web storage because all the apps from a single APEX instance (which is a single * origin or web site) share the same web storage space. The {@link apex.storage.getScopedLocalStorage} and {@link apex.storage.getScopedSessionStorage} * solve this problem buy partitioning the storage into a scope based on application id an optionally additional information such as * page id and region id. The scope is crated by using a prefix on all the storage keys. This avoids conflicts when different apps or * different instances of the same app use the same keys but it is not a secure partition. Consider this carefully before storing * sensitive information in web storage.
*/ namespace storage { /** *Returns the value of the specified cookie.
* @example *Sets a cookie to the specified value.
* @example *Returns true if the browser supports the local storage API and false otherwise. Most modern browsers support this feature but some allow the user to turn it off.
"setting1" to on if local storage is supported by the browser.true if the browser supports the local storage API and false otherwise.
*/
function hasLocalStorageSupport(): boolean;
/**
* Returns true if the browser supports the session storage API and false otherwise. Most modern browsers support this feature but some allow the user to turn it off.
"setting1" to on if session storage is supported by the browser.true if the browser supports the session storage API and false otherwise.
*/
function hasSessionStorageSupport(): boolean;
/**
* A storage wrapper object. This object has the same properties and functions as the native browser Storage interface.
* @property prefix - APEX specific property. The prefix for this scoped storage object. * @property length - The number of items in the scoped storage object. * @property key - Thekey( n ) function returns the nth key in the scoped storage object.
* @property getItem - The getItem( key ) function returns the value for the given key.
* @property setItem - The setItem( key, data ) function sets the value of the given key to data.
* @property removeItem - The removeItem( key ) function removes the given key.
* @property clear - The clear function removes all keys from the scoped storage object.
* @property sync - The APEX specific sync function. Use to ensure the length property is correct if keys may have been added or removed by means external to this object.
*/
type storageWrapper = {
prefix: string;
length: number;
key: (...params: any[]) => any;
getItem: (...params: any[]) => any;
setItem: (...params: any[]) => any;
removeItem: (...params: any[]) => any;
clear: (...params: any[]) => any;
sync: (...params: any[]) => any;
};
/**
* Returns a thin wrapper around the sessionStorage object that scopes all keys to a prefix defined by the options parameter. If sessionStorage is not supported, the returned object can be used but has no effect so it is not necessary test for support using {@link apex.storage.hasSessionStorageSupport} before calling this function.
"Acme" and the application id. It then sets and gets an item called "setting1".sessionStorage wrapper object.
* @param [options.prefix] - A static prefix string to add to all keys. The default is an empty string.
* @param [options.useAppId] - Whether the application id will be included in the key. The default is true.
* @param [options.usePageId] - Whether the application page id will be included in the key. The default is false.
* @param [options.regionId] - An additional string to identify a region or other part of a page. The default is an empty string.
* @returns A {@link apex.storage.storageWrapper|sessionStorage} wrapper object.
*/
function getScopedSessionStorage(options: {
prefix?: string;
useAppId?: boolean;
usePageId?: boolean;
regionId?: string;
}): storageWrapper;
/**
* Returns a thin wrapper around the localStorage object that scopes all keys to a prefix defined by the options parameter. If localStorage is not supported, the returned object can be used but has no effect so it is not necessary test for support using {@link apex.storage.hasLocalStorageSupport} before calling this function.
"Acme" and the application id. It then sets and gets an item called "setting1".localStorage wrapper object.
* @param [options.prefix] - A static prefix string to add to all keys. The default is an empty string.
* @param [options.useAppId] - Whether the application id will be included in the key. The default is true.
* @param [options.usePageId] - Whether the application page id will be included in the key. The default is false.
* @param [options.regionId] - An additional string to identify a region or other part of a page. The default is an empty string.
* @returns A {@link apex.storage.storageWrapper|localStorage} wrapper object.
*/
function getScopedLocalStorage(options: {
prefix?: string;
useAppId?: boolean;
usePageId?: boolean;
regionId?: string;
}): storageWrapper;
}
/**
* The apex.theme namespace contains functions useful for theme developers or that work closely with theme
* related functionality. The functionality in this namespace may not be fully supported by all themes particularly
* legacy, custom, or third party themes.
*/
namespace theme {
/**
* Display a standard item help dialog. This function may be useful for theme developers. * Theme requirements for the label Help Template:
*-
*
- A click handler or javascript
hrefcan invoke this function directly. For example: ** <button ... onclick="apex.theme.popupFieldHelp('#CURRENT_ITEM_ID#','&SESSION.');" ...>Help</button>
* - The preferred way it to use the built-in delegated click event handler. For this give the
* clickable help element a class of
js-itemHelpand add a *data-itemhelpattribute with the current item id. * For example: ** <button class="... js-itemHelp" data-itemhelp="#CURRENT_ITEM_ID#" ...>Help</button>
*
The second method is preferred because you get Alt-F1 keyboard accessibility. For Alt+F1 to work the
* label template Before Label and Item template attribute must include:
*
* id="#CURRENT_ITEM_CONTAINER_ID#"
helpText,
* and title. When an object is given the other parameters are ignored.
* @param [pSessionId] - Current session id
* @param [pUrl] - Override to specify the URL to use to fetch the help content. It should not include
* the p_output_format param. This is an advanced parameter that is normally not needed.
*/
function popupFieldHelp(pItemId: string | any, pSessionId?: string, pUrl?: string): void;
/**
* Open a region that supports being opened such as an inline dialog, inline popup, or collapsible region. * For a region to support this function, it must be implemented with a jQuery UI widget * that supports either open and close methods or expand and collapse methods.
* @example *myDialog.Close a region that supports being opened such as an inline dialog, inline popup, or collapsible region. * For a region to support this function, it must be implemented with a jQuery UI widget * that supports either open and close methods or expand and collapse methods.
* @example *myDialog.Test a media query. Return true if the document matches the given media query string and false otherwise.
* This is a wrapper around window.matchMedia.
(min-width: 400px)
* @returns true if the media query matches.
*/
function mq(pMediaQuery: string): boolean;
}
/**
* The apex.util namespace contains general utility functions of Oracle Application Express.
*/ namespace util { /** *Returns a new function that calls pFunction but not until
* pDelay milliseconds after the last time the returned function is called.
pFunction.
*/
function debounce(pFunction: (...params: any[]) => any, pDelay: number): (...params: any[]) => any;
/**
* Function that returns an array based on the value passed in pValue.
["Bags","Shoes","Shirts"].pSeparator parameter.
* If it's not a string, then we try to convert the value with
* apex.jQuery.makeArray to an array.
* @param [pSeparator = ":"] - Separator used to split a string passed in pValue,
* defaults to colon if not specified. Only needed when pValue is a string.
* It is ignored otherwise.
*/
function toArray(pValue: string | any, pSeparator?: string): any[];
/**
* Compare two arrays and return true if they have the same number of elements and * each element of the arrays is strictly equal to each other. Returns false otherwise. * This is a shallow comparison.
* @example *Returns string pValue with any special HTML characters (&<>"'/)
* escaped to prevent cross site scripting (XSS) attacks.
* It provides the same functionality as sys.htf.escape_sc in PL/SQL.
This function should always be used when inserting untrusted data into the DOM.
* @example *Returns string pValue with any CSS meta-characters escaped.
* Use this function when the value is used in a CSS selector.
* Whenever possible if a value is going to be used as a selector, constrain the value so
* that it cannot contain CSS meta-characters making it unnecessary to use this function.
Return an {@link htmlBuilder} interface.
*/ function htmlBuilder(): htmlBuilder; /** * Function that renders a spinning alert to show the user that processing is taking place. Note that the alert is * defined as an ARIA alert so that assistive technologies such as screen readers are alerted to the processing status. * @example *The delayLinger namespace solves the problem of flashing progress indicators (such as spinners).
* *For processes such as an Ajax request (and subsequent user interface updates) that may take a while * it is important to let the user know that something is happening. * The problem is that if an async process is quick there is no need for a progress indicator. The user * experiences the UI update as instantaneous. Showing and hiding a progress indicator around an async * process that lasts a very short time causes a flash of content that the user may not have time to fully perceive. * At best this can be a distraction and at worse the user wonders if something is wrong or if they missed something * important. Simply delaying the progress indicator doesn't solve the problem because the process * could finish a short time after the indicator is shown. The indicator must be shown for at least a short but * perceivable amount of time even if the request is already finished.
* *You can use this namespace to help manage the duration of a progress indication such as * {@link apex.util.showSpinner} or with any other progress implementation. Many of the Oracle * Application Express asynchronous functions such as the ones in the {@link apex.server} namespace * already use delayLinger internally so you only need this API for your own custom long running * asynchronous processing.
* @example *Call this function when a potentially long running async process starts. For each call to start with
* a given pScopeName a corresponding call to finish with the same pScopeName must be made.
* Calls with different pScopeName arguments will not interfere with each other.
Multiple calls to start for the same pScopeName before any calls to
* finish is allowed but only the pAction from the first call is called at most once.
Call this function when the potentially long running async process finishes. For each call to start with
* a given pScopeName a corresponding call to finish with
* the same pScopeName must be made.
* The pAction is called exactly once if and only if the corresponding
* start pAction was called.
* If there are multiple calls to finish the pAction from the last one is called.
APEX_JSON.STRINGIFY and APEX_JSON.WRITE
* procedures that take a DATE value into Date objects that the client can use.
* @example
* Gets the system scrollbar size for cases in which the addition or subtraction of a scrollbar * height or width would effect the layout of elements on the page. The page need not have a scrollbar on it * at the time of this call.
* @example *{ width: 17, height: 17 }. Note
* the actual height and width depends on the Operating System and its various display settings.Wrapper around requestAnimationFrame that can fallback to setTimeout.
* Calls the given function before next browser paint. See also {@link apex.util.cancelInvokeAfterPaint}.
See HTML documentation for window.requestAnimationFrame for details.
Wrapper around cancelAnimationFrame that can fallback to clearTimeout.
* Cancels the callback using the id returned from {@link apex.util.invokeAfterPaint}.
Returns string pText with all HTML tags removed.
Returns the nested object at the given path pPath within the nested object structure in
* pRootObject creating any missing objects along the path as needed.
* This function is useful when you want to set the value of a property in a deeply
* nested object structure and one or more of the nested objects may or may not exist.
*
options.views.grid.features.cellRangeActions
* to false.
* It works even when the options object does not contain a views.grid.features object or a views.grid object
* or even a views object.This function applies data to a template. It processes the template string given in
* pTemplate by substituting
* values according to the options in pOptions.
* The template supports Application Express server style placeholder and item substitution syntax.
This function is intended to process Application Express style templates in the browser.
* However it doesn't have access to all the data that the server has. When substituting page items and column
* items it uses the current value stored in the browser not what is in session state on the server.
* It does not support the old non-exact substitutions (with no trailing dot e.g. &ITEM). It does not support
* the old column reference syntax that uses #COLUMN_NAME#. It cannot call
* PREPARE_URL (this must be done on the server).
* Using a template to insert JavaScript into the DOM is not supported.
* After processing the template all script tags are removed.
The format of a template string is any text intermixed with any number of replacement tokens * or directives. Two kinds of replacement tokens are supported: placeholders and data substitutions. * Directives control the processing of the template. Directives are processed first, then placeholders and finally * data subsitutions.
* *Placeholders
*This is also known as a hash substitution.
*Placeholder syntax is:
*#<placeholder-name>#
* The <placeholder-name> is an uppercase alpha numeric plus "_", and "$" string that must be a property
* name in option object placeholders that gets replaced with the property value.
* Any placeholder tokens that don't match anything in the placeholders object are left as is (searching for the
* next placeholder begins with the trailing # character).
Data substitutions
*Substitution syntax is (any of):
*&<item-name>.
* &<item-name>!<escape-filter>.
* &"<quoted-item-name>".
* &"<quoted-item-name>"!<escape-filter>.
* &APP_TEXT$<message-key>.
* &APP_TEXT$<message-key>!<escape-filter>.
* &"APP_TEXT$<message-key>".
* &"APP_TEXT$<message-key>"!<escape-filter>.
* The <item-name> is an uppercase alpha numeric plus "_", "$", and "#" string. The <quoted-item-name>
* is a string of any characters except "&", carriage return, line feed, and double quote.
* In both cases the item name is the name of a page item (unless option includePageItems is false),
* a column item (if model and record options are given), a built-in substitution
* (unless option includeBuiltinSubstitutions is false),
* or an extra substitution if option extraSubstitutions is given.
The <item-name> can include a property reference. A '%' character separates the item-name from the property name.
* For example &P1_NAME%LABEL. will return the label of the P1_NAME item.
* The property name is case insensitive.
The properties and the values they return for a page item are:
*-
*
- LABEL - The item label. *
- DISPLAY - The display value of the item's current value. *
- CHANGED - 'Y' if the item has been changed and 'N' otherwise. *
- DISABLED - 'Y' if the item is disabled and 'N' otherwise. *
The properties for a column item are:
*-
*
- HEADING - The column heading text. The heading may include markup. If there is no heading * the label will be used if there is one. *
- LABEL - The column label. If there is no label the heading will be used with markup removed. *
- DISPLAY - The display value of the column value for the current row/record. *
- HEADING_CLASS - Any CSS classes defined for the column heading. *
- COLUMN_CLASS - Any CSS classes defined for the column. *
- REQUIRED - 'Y' if the column is required and 'N' otherwise. *
The <message-key> is a message key suitable for use in {@link apex.lang.getMessage} and * is replaced with the localized message text for the given key. The message must already be loaded on the * client by setting the Text Message attribute Used in JavaScript to Yes or otherwise adding it such as with * {@link apex.lang.addMessages}. * If no replacement for a substitution can be found it is replaced with the message key. The language specifier * that is supported for server side message substitutions is not supported by the client and will be ignored * if present.
* *When substituting a column item the given record of the given model is used to find a matching column name. * If not found and if the model has a parent model then the parent model's columns are checked. * This continues as long as there is a parent model. The order to resolve an item name is: page item, * column item, column item from ancestor models, built-in substitutions, and finally extra substitutions. * Column items support the "_LABEL" suffix to access the defined column label. For example if there is a * column item named NOTE the substitution &NOTE_LABEL. will return the label string for column NOTE.
* *The built-in substitution names are:
*-
*
- &APP_ID. *
- &APP_PAGE_ID. *
- &APP_SESSION. *
- &REQUEST. *
- &DEBUG. *
- &IMAGE_PREFIX. *
The escape-filter controls how the replacement value is escaped or filtered. It can be one of the following * values:
*-
*
- HTML the value will have HTML characters escaped using {@link apex.util.escapeHTML}. *
- ATTR the value will be escaped for an HTML attribute context (currently the same as HTML) *
- RAW does not change the value at all. *
- STRIPHTML the value will have HTML tags removed and HTML characters escaped. *
This will override any default escape filter set with option defaultEscapeFilter
* or from the column definition escape property.
Directives
*Directive syntax is
*{<directive-name>[ <directive-arguments>]/}
* The directive name determines what it does as described below. Directive names are case insensitive. * There can be no whitespace between the open bracket '{' and the directive name. * Directives often come in sets that work together. A directive may have additional arguments.
* *If condition directives
*Syntax:
*{if [!]NAME/}
* TRUE_TEMPLATE_TEXT
* {elseif [!]NAME2/}
* ELSE_TRUE_TEMPLATE_TEXT
* {else/}
* FALSE_TEMPLATE_TEXT
* {endif/}
* The entire text from the if directive to the matching endif directive is * replaced with the processed template text following the first if or elseif * directive that evaluates to true or the template text following the else * directive if none are true. There must be an if and endif directive. * The elseif and else directives are optional. * There can be any number of elseif directives. The directives must go in the order shown. * If directives can be nested. * That means any of the template texts can contain another if directive.
* *The if and elseif directives test the value of NAME * and if it is true process the following template text. * The NAME can be an item-name, quoted-item-name, or placeholder-name. The value of an item-name or quoted-item-name * is the value of that page item or column item. The value of a placeholder-name is the text of the placeholder. * If no data substitution or placeholder with that name exists then the value is empty string.
* *A value is false if after trimming leading and trailing spaces it is an empty string,
* or for a page item the item {@link item.isEmpty} method returns true,
* or if the value is equal to any of the values in the falseValues option.
*
*
Example:
* The page contains items P1_TITLE, P_ICON, P1_DESCRIPTION, and P1_DETAILS and all have optional values.
* The template outputs a default title if P1_TITLE is empty. An optional icon is shown only if there is a title.
* The template output includes markup for the description if it is not empty or details if it is not empty and
* nothing otherwise.
<h3>{if P1_TITLE/}&P1_TITLE. {if P1_ICON/}<span class="fa &P1_ICON."></span>{endif/}
* {else/}Untitled{endif/}
* {if P1_DESCRIPTION/}
* <p class="description">&P1_DESCRIPTION.</p>
* {elseif P1_DETAILS/}
* <p class="details">&P1_DETAILS.</p>
* {endif/}
* Case condition directives
*Syntax:
*{case NAME/}
* {when string1/}
* TEMPLATE_TEXT1
* {when string2/}
* TEMPLATE_TEXT2
* {otherwise/}
* TEMPLATE_TEXT
* {endcase/}
* The entire text from the case directive to the matching endcase directive * is replaced with the processed template text after the when directive that matches the NAME value. * The value of NAME is compared with each of the strings in the when directive and if it is equal the following * template (TEMPLATE_TEXTn) is processed. If no when directive matches then the template after * the otherwise directive is processed if there is one. The otherwise directive is optional * but it must come at the end and there can only be one. Case directives can be nested. * That means any of the template texts can contain another case directive.
* *The NAME can be an item-name, quoted-item-name, or placeholder-name. The value of an item-name or quoted-item-name * is the value of that page item or column item. The value of a placeholder-name is the text of the placeholder. * If no data substitution or placeholder with that name exists then the value is empty string. The NAME value and each string * is trimmed of leading and trailing spaces before comparison. The comparison is case sensitive.
* *Example:
* The page contains items P1_NAME and P1_DETAILS, and P1_DETAIL_STYLE that can have a value of "FULL" or "BRIEF".
* The intention is to control the markup according to the detail style.
{case P1_DETAIL_STYLE/}
* {when FULL/}
* <div class="full">
* <span>&P1_NAME!HTML.</span>
* <p class="description">&P1_DETAILS!HTML.</p>
* </div>
* {when BRIEF/}
* <div class="brief">
* <span>&P1_NAME!HTML.</span>
* </div>
* {endcase/}
* Loop directives
*Syntax:
*{loop ["SEP"] NAME/}
* TEMPLATE_TEXT
* {endloop/}
* The entire text from the loop directive to the matching endloop directive is * replaced with the template text evaluated once for each item in the NAME value.
* *The NAME can be an item-name, quoted-item-name, or placeholder-name. The value of an item-name or quoted-item-name * is the value of that page item or column item. The value of a placeholder-name is the text of the placeholder. * If no data substitution or placeholder with that name exists then the value is empty string. The NAME value should * be a separator delimited string that contains a list of items. The optional SEP argument defines the separator * character. The default separator is ":". If SEP is more than one character it is treated as a regular expression.
* *Within the loop there are two extra data substitutions available:
*-
*
- APEX$ITEM This is the value of the current item in the list. *
- APEX$I This is 1 based index of the current item in the list. *
Example:
* The following example takes a page item, P1_TAGS that contains a bar '|'
* separated list of tags such as "apples|cherries|pears" and turns it into an HTML list that can be nicely styled.
<ul class="tags">{loop "|" P1_TAGS/}
* <li class="tag-item">APEX$ITEM</li>
* {endloop/}</ul>
* Comments
*Syntax:
*{!<comment-text>/}
* This directive is substituted with nothing. It allows adding comments to templates. * The comment-text can be any characters except new line and the "/}" sequence.
* *Example:
* This example includes a comment reminding the developer to complete something. In this case
* replace a hard coded English string with a localizable text message.
<span>Name: &P1_NAME.</span> {!to do replace Name: with text message/}
* Escape open bracket '{'
*Syntax:
*{{/}
* In rare cases a lone open bracket '{' can be confused for the start of a directive if another directive * follows it on the same line.
* *Example:
* This is an example where the open bracket '{' has to be escaped.
<span>The coordinates {{/}c, d} = {if VAL/}&VAL.{else/}unknown{endif/}</span>
* Here are similar cases that don't require an escape.
*<span>The coordinates { c, d } = {if VAL/}&VAL.{else/}unknown{endif/}</span>
* <span>The coordinates {c, d} =
* {if VAL/}&VAL.{else/}unknown{endif/}</span>
* escape property
* then it will override the default escaping.
* @param [pOptions.includePageItems] - If true the current value of page items are substituted.
* The default is true.
* @param [pOptions.model] - The model interface used to get column item values. The default is null.
* @param [pOptions.record] - The record in the model to get column item values from.
* Option model must also be provided. The default is null.
* @param [pOptions.extraSubstitutions] - An object map of extra substitutions. The default is an empty object.
* @param [pOptions.includeBuiltinSubstitutions] - If true built-in substitutions such as APP_ID are done.
* The default is true.
* @param [pOptions.falseValues] - An array of values that are considered false in if directive tests.
* Empty string and item that doesn't exist are always considered false.
* The default is ["F", "f", "N", "n", "0"]
* @returns The template string with replacement tokens substituted with data values.
*/
function applyTemplate(pTemplate: string, pOptions?: {
placeholders?: any;
directives?: boolean;
defaultEscapeFilter?: string;
includePageItems?: boolean;
model?: model;
record?: model.Record;
extraSubstitutions?: any;
includeBuiltinSubstitutions?: boolean;
falseValues?: string[];
}): string;
}
}
/**
* The actions interface manages a collection of {@link actions.action} objects. An action encapsulates * the identity, state and behavior of a named operation or procedure that the user initiates via a user * interface element. Actions are most useful when an operation can be initiated in multiple ways such as with a button * or toolbar button, menu, or keyboard shortcut. The operation should be labeled consistently and if it can be * enabled and disabled that state must be kept consistent. By using an action and then associating a button and/or * menu item with that action all aspects of the action are centralized and kept in sync. This avoids duplicating * labels, icons etc.
* * *The apex.actions singleton (which is also the {@link apex.actions} namespace) manages * all the global (page level) actions. For components that can have multiple * instances on a page the global actions will not work because it is not clear which instance of the component the * action applies to. To support components the {@link apex.actions.createContext} function is used to create an actions * interface that is scoped to a specific component instance (the context). Typically the component (e.g. widget) would * call {@link apex.actions.createContext} when it is created and {@link apex.actions.removeContext} * when it is destroyed.
* *For global actions and any other created actions contexts the methods on the actions object are used to add, * remove, lookup, and invoke actions. There are also methods to manage keyboard shortcuts. Additional state can be * stored in the action if desired. If any of the action properties change then {@link actions#update} must be called.
* *Actions are associated with other controls that invoke the action. It is also possible to invoke * the action explicitly with the {@link actions#invoke} method. To toggle actions the {@link actions#toggle} * method is used and for radio group actions the {@link actions#set} method is used to change the value. * The following sections describes how to associate actions with various controls.
* * *To associate a button element with an action give it a class of js-actionButton and a data-action * attribute with the name of the action as its value. The button icon, label text, title, aria-label, hide/show, * and disabled state are all updated automatically.
*For this automatic updating to work buttons should use the following classes:
*-
*
- t-Button-label if a button has a text label this class should be on an element that wraps the text. * This is useful when the button also has an icon or other non-text label content. This class does not * go on the button element. If this class is not used then the content of the button element will be the * label text. *
- t-Button--icon if a button has an icon this class should be on the button element. If the action has an * icon and the button has this class then any elements with the icon type class will be updated with * the icon. Any classes on the icon element that are not the icon, the icon type or start with "t-" * will get removed. *
- t-Button--noLabel if a button has no visible label this class should be on the button element. A button with * no visible label text will have the button's aria-label attribute set to the button label. Also if there * is no title the label will be used as the title. *
If the action label or title are null they will be initialized with the text and title attribute value respectively * from the first button (in document order) associated with the action. This is useful if the server has * already rendered a localized button for the action. The title comes from the button title attribute. The label comes * from the first found of; aria-label attribute, title attribute if button has class t-Button--noLabel, * content of the descendant element with class t-Button-label, and finally the button element content. If disabled * is null it will be taken from the button disabled property. If you don't want the label, title, or icon to be updated * add attribute data-no-update="true".
* *Example:
* <button class="js-actionButton" data-action="undo">Undo</button>
* A checkbox can be associated with a toggle action by giving the input element (or a wrapping parent element) * a class of js-actionCheckbox and a data-action attribute with the name of the action as its value. The checkbox * should have a label element. The icon, label text, title, hide/show, disabled state, and checked state are all * updated automatically. For hide to work correctly use a wrapping element.
* *If the label has the class t-Button then it should be marked up like a button and the same classes described for * a button are used to update the label and icon (except a visually hidden child element is used for the label * in place of aria-label). Otherwise the label element content will be updated with the label and the icon is not used. * If the action label or title are null they will be initialized from the markup. If the checkbox label is marked up * like a button then the label comes from the text of a child element with class t-Button-label or if the label * has class t-Button--noLabel then from a child element with class u-VisuallyHidden. If you don't want the label, * title, or icon to be updated add attribute data-no-update="true".
* *Example:
* <input id="abc" type="checkbox" class="js-actionButton" data-action="optionA"><label for="abc">Option A</label>
* or
* <div class="js-actionButton" data-action="optionA">
* <input id="abc" type="checkbox"><label for="abc">Option A</label>
* </div>
* A radio group is a set of input elements of type radio and sharing the same name value. A radio group can be * associated with a radio group action by giving the element that wraps the radio group a class of * js-actionRadioGroup and a data-action attribute with the name of the action as its value. The wrapper element * aria label is kept in sync with the action label. The radio group as a whole does not have a disabled state, * icon or title. When the radio action value changes (or when update is called) the checked state (and disabled state) * of each radio input is updated.
*The element with class js-actionRadioGroup can also have attributes: data-item-start, data-item, data-item-end, * data-item-wrap to override action properties labelStartClasses, labelClasses, labelEndClasses, and itemWrapClasses * respectively.
*If the action label is null it will be initialized from the wrapper element aria-label. If the wrapping element * has no children when the action is added or when updateChoices is called (after the choices have been changed) then * the choices are rendered as radio input, label pair elements. The action labelStartClasses, labelClasses, * labelEndClasses values are used for the classes of the label elements. If there is an icon it will be used * as the label. The label will be included as a hidden but accessible label. The label element will have a title * if there is a title property or if the choice has an icon. The title comes from the label property if the title * property isn't given.
* *Example:
* <div class="js-actionRadioGroup" data-action="itemSize">
* <input id="lc1" type="radio" name="RG1" value="s"><label for="lc1">Small</label>
* <input id="lc2" type="radio" name="RG1" value="m"><label for="lc2">Medium</label>
* <input id="lc3" type="radio" name="RG1" value="l"><label for="lc3">Large</label>
* </div>
* To associate a select element with a radio group action give it a class of js-actionSelect and a data-action * attribute with the name of the action as its value. Select lists used with actions are assumed to not have an * associated label element. The select element aria label, title, value, and disabled state are kept in sync with the * action. When the radio action value changes (or when update is called) the select element value is updated and * also the disabled state of each option element.
*If the action label or title are null they will be initialized from the select element aria-label and * title attributes. If the select element has no children when the action is added or when updateChoices is called * (after the choices have been changed) then the choices are rendered as option elements. The choice group property * is used to put options in optgroup elements. The group property value is used as the optgroup label. The choices * need to be sorted first by group value.
* *Example:
* <select class="js-actionSelect" data-action="itemSize">...</select>
* For {@link menu} widget menu items of type action, toggle, or radioGroup simply specify the * action name as the value of the action property. Values for * label, icon, iconType, disabled, hide, and accelerator are taken from the action (accelerator is taken from * the action shortcut property). It is possible to override action values such as label and icon by specifying them * in the menu item.
* Examples: * { type: "action", action: "undo" },
* { type: "toggle", action: "myToggleAction" },
* { type: "radioGroup", action: "myRadioAction" }
* Shortcuts are not an actual widget or a DOM Element. The keyboard event handler for invoking actions in * response to shortcut keys is in this module and is registered on the context element * (body for the global context).
* * *To integrate actions with other UI controls:
*-
*
- Devise a way to specify the action name. For example using a class such as * js-actionRadioGroup and an attribute such as data-action attribute on an appropriate element. * For widgets the action name could be passed as an option to the initialization function. *
- Register an observer call back using {@link actions#observe} to get notified when the action is added, * removed, or updated. Use this callback to update the state of the UI control such as enabling or * disabling it or changing the label or icon. *
- Call the invoke method when it is time to invoke the action. *
This is type name of the actions context as given in the {@link apex.actions.createContext} call. * The typeName of the global context apex.actions is "global".
*/ typeName: string; /** *This is the Element context that actions are scoped within as given in * the {@link apex.actions.createContext} call.
*/ context: Element; /** *Add an {@link actions.action} object or an array of {@link actions.action} objects to this actions context. * The action name must be unique within the context and the shortcut if any must be unique * within the context and valid. Debug warnings are logged if any of these conditions are not met. * See also {@link actions#remove}.
* @example *log1 returned by {@link apex.actions.createContext}.Add one or more {@link actions.action} objects from simple list markup. This is useful in cases where it is easier * to render list markup than an array of action objects. This does not support adding actions * with functions but action functions can be added either before or after.
*The markup expected by this method overlaps with what the {@link menu} widget expects.
* *Expected markup:
* An element with a <ul> child. The
* <ul> has one or more <li>
* elements each one representing an action.
* The <li> element can contain either an
* <a> or <span> element.
| Action property | *Comes from | *
|---|---|
| name | *li[data-id] | *
| label | *a or span content | *
| title | *a[title] or span[title] | *
| href | *a[href] | *
| target | *a[target] | *
| disabled | *true if li[data-disabled=true] false otherwise | *
| hide | *true if li[data-hide=true] false otherwise | *
| shortcut | *li[data-shortcut] | *
| icon | *li[data-icon] If the value has a space the icon is the word after the space * otherwise it is the whole value | *
| iconType | *li[data-icon] If the value has a space the type is the word before the space | *
If there is no name or label or the value of <href> equals
* "separator" then no action is created for that <li>.
* If the <li> has a <ul>
* child the <ul> is processed recursively.
Remove one or more {@link actions.action} objects from this actions context. * See also {@link actions#add}.
* @example *log1 returned by {@link apex.actions.createContext}.Remove all actions from this actions context.
* @example *Lookup and return an action by name. If you modify the properties of the action * you may need to call {@link actions#update} to update any associated UI elements or shortcuts. * If you modify the choices of the action then call {@Link actions#updateChoices}.
* @example *Return an array of actionName, label pairs for all actions in the context. For actions with * choices there is an array item for each choice.
* @example *Update any UI elements associated with the action after it changes. Calling update will * notify any observers that the action has changed. Debug warnings will be logged and * the return value is false if the action has a problem with the shortcut.
* @example *Call this only if the set of choices for an action has changed. This will * notify any observers that the set of action choices has changed.
* @example *Enable UI elements associated with the action by setting disabled property to false.
* This is a convenience method to enable without having to call {@link actions#lookup} and
* {@link actions#update}.
Disable UI elements associated with the action by setting disabled property to true.
* This is a convenience method to disable without having to call {@link actions#lookup} and
* {@link actions#update}.
Hide UI elements associated with the action by setting the hide property to true.
* This is a convenience method to hide without having to call {@link actions#lookup} and
* {@link actions#update}.
Show UI elements associated with the action by setting the hide property to false.
* This is a convenience method to show without having to call {@link actions#lookup} and
* {@link actions#update}.
Invoke the named action. Even though pEvent and pFocusElement are optional it is recommended to * always include them.
* @example *Toggle the named action. This should only be used for toggle actions. * Toggle actions have get and set methods and don't have a choices property.
* @example *log1 returned by {@link apex.actions.createContext}.Return the current value of a radio group or toggle action.
* @example *Set the value of a radio group action or toggle action.
* @example *Add a keyboard shortcut synonym for an action. Debug warnings are logged if there are problems. * See also {@link actions#removeShortcut}.
*This allows an action to have more than one shortcut key to invoke it.
* The shortcut property of the action is not affected.
Remove a keyboard shortcut synonym for an action. * See also {@link actions#addShortcut}
* @example *Return a list of all shortcuts in the context.
* @example *Return the friendly display string for a keyboard shortcut name.
* @param pShortcutName - Keyboard shortcut to get the display string for. * @param pWithMarkup - Optional default is false. If true wrap the display name in HTML markup. * @returns A friendly version of the shortcut. * The display string is sensitive to the operating system. See {@link apex.actions.setKeyCaps}. */ shortcutDisplay(pShortcutName: apex.actions.shortcutName, pWithMarkup: boolean): string; /** *This is used to disable all shortcuts temporarily. Call at the start of a user interaction * that should have shortcuts disabled for example a custom popup. Call {@link actions#enableShortcuts} when * finished. It is called automatically when APEX modal dialogs or menus open. * Calls can be nested. For each call to disableShortcuts there should be a corresponding * call to {@link actions#enableShortcuts}.
*/ disableShortcuts(): void; /** *This is used to enable all shortcuts after they were disabled with {@link actions#disableShortcuts}. * It is called automatically when APEX modal dialogs or menus close. * Calls can be nested. For each call to {@link actions#disableShortcuts} there should be a corresponding * call to enableShortcuts.
*/ enableShortcuts(): void; /** *Register a callback function to be notified when an action changes. * This is used to update UI elements associated * with an action when that action state changes. The most common elements including * buttons, checkbox and radio group inputs, select lists, and menus are already handled.
* @param pCallback - function notifyObservers( action, operation ) * operation is one of "add", "remove", "update", or "updateChoices" */ observe(pCallback: (...params: any[]) => any): void; /** *Remove callback.
* @param pCallback - The function that was added with {@link actions#observe}. */ unobserve(pCallback: (...params: any[]) => any): void; } /** *The htmlBuilder interface is used create HTML markup. It makes it easy to generate markup that is * well formed and properly escaped. It is simpler and safer than using string concatenation and doesn't * require the overhead of using a template library. For simple templates see {@link apex.util.applyTemplate}
* @example *{ id: "nameInput", label: "Name", size: 10, maxChars: 15 }
* the resulting markup will be:*
<label for='nameInput'>Name</label><input type='text' id='nameInput' class='specialInput' size='10' maxlength='15' value='' />Add markup.
* @param pMarkup - The markup to add. No escaping is done. * @returns This htmlBuilder instance for method chaining. */ markup(pMarkup: string): this; /** *Add an attribute.
* @param [pName] - Attribute name. A leading space and trailing = is added and the value is quoted. * If not given just the value is added without being quoted. * @param pValue - Attribute value. This will be escaped. * @returns This htmlBuilder instance for method chaining. */ attr(pName: string, pValue: string): this; /** *
Add an optional attribute. The attribute and its value is only added if the value is a non-empty * string or a non-zero number or true.
* @param pName - Attribute name. A leading space and trailing = is added and the value is quoted. * @param pValue - Attribute value. This will be escaped. * @returns This htmlBuilder instance for method chaining. */ optionalAttr(pName: string, pValue: string): this; /** *Add an optional Boolean attribute. The attribute is added only if the value is true.
* @param pName - Attribute name. A leading space is added. * @param pValue - If true the attribute is added. If false the attribute is not added. * @returns This htmlBuilder instance for method chaining. */ optionalBoolAttr(pName: string, pValue: boolean): this; /** *Add element content. The content is escaped.
* @param pContent - The content to add between an element open and closing tags. * @returns This htmlBuilder instance for method chaining. */ content(pContent: string): this; /** *
Remove all markup from this builder interface instance. Use this when you want to reuse the builder * instance for new markup.
*/ clear(): void; /** *Return the HTML markup.
* @returns The markup that has been built so far. */ toString(): string; } /** *The item interface is used to access methods and properties of an Oracle Application Express item. * You get access to the item interface for a page or column item with the {@link apex.item|apex.item} function.
* *An item interface can apply to either a page item or column item. * Page items are items on the page backed by session state in any region. * Column items are created by region types such as Interactive Grid that support editable columns. * The state of a column item, including its value, changes according to the editing context (active record) * of the region and is typically backed by data in an Oracle Application Express {@link model}.
* *Plug-in developers can define the behavior of their item by calling {@link apex.item.create}.
*/ declare interface item { /** *The DOM element that best represents the value of the Oracle Application Express item. If the item doesn't exist * then the value is false.
* @example *The jQuery object for this item element. If the item doesn't exist then it is the empty jQuery object $(). * This is primarily for plug-in developers.
*/ element: jQuery; /** *The id of the DOM element of the item. If the item doesn't exist then the value is false.
*/ id: string | false; /** *Returns the current value of an Oracle Application Express item. The initial value of a page item comes from * session state when the server renders the page. The initial value of a column item comes from the * corresponding field value of the active record of the Oracle Application Express {@link model}. This function * always returns the current value of the item, which may have been changed by the user or with the {@link item#setValue} * method since it was initialized.
* *There are two shorthand functions related to getValue. The {@link $v} function that returns an item's value in the string format * it will be sent to the server. This will either be a single value, or if the item supports multiple values, will be * a ':' colon separated list of values. The {@link $v2} function, which is just a shortcut * to getValue and returns either a single value, or an array of values. See also {@link item#setValue}.
* @example *Sets the Oracle Application Express item value. This function sets the current value of the * item. For page items the session state is not affected until the page is submitted (or the item * is explicitly saved to the server using ajax or a dynamic action). For column items the region * such as Interactive Grid takes care of writing the value back to the Oracle Application Express {@link model} * when appropriate.
* *Normally a change event is explicitly triggered on the item node when the value is set. This allows * cascading LOV functionality and dynamic action change events to work. * The caller may suppress the change event for the item being set, if needed. The change event should be * suppressed when the value is set while processing a change event triggered on the same item, to prevent * an infinite loop. The {@link grid} widget relies on the change event to update the model. If you suppress * the change event on a column item you may need to call the {@link grid#setActiveRecordValue} method.
* *There is a shorthand function for setValue {@link $s}. See also {@link item#getValue}.
* @example *pSuppressChangeEvent has not been passed, the default behavior of the
* change event triggering for P1_ITEM will occur.pSuppressChangeEvent parameter,
* the change event will not trigger for the P1_ITEM item.pValue parameter sets the hidden return value.
* @param [pSuppressChangeEvent] - Pass true to prevent the change event from being triggered
* for the item being set. The default is false.
*/
setValue(pValue: string | string[], pDisplayValue?: string, pSuppressChangeEvent?: boolean): void;
/**
* Enables the Oracle Application Express item value that has been disabled, making it available for editing. * Not all items support being disabled. This only applies to items that can be edited. * See also {@link item#disable}.
* @example *Disables the Oracle Application Express item, making it unavailable for editing. * Not all items support being disabled. This only applies to items that can be edited. See also {@link item#enable}.
* @example *Shows the Oracle Application Express item. When using the show function, it is important to understand the following:
*-
*
- If the item being shown is rendered on a page using table layout (meaning the page references a page
* template with Grid Layout Type set to 'HTML Table'), and the call to show has specified to show the entire
* table row (
pShowRow= true), then it is assumed that everything pertaining to the item is contained in that * row, and the entire row will be shown.
* - If the item being shown is rendered on a page using table layout, and the call to show has specified
* not to show the entire table row (
pShowRow= false, or not passed), then the function will attempt to show * the item's label, where theforattribute matches theidof the item.
* - If the item being shown is rendered on a page using grid layout (meaning the page references a page
* template with Grid Layout Type set to either 'Fixed Number of Columns', or 'Variable Number of Columns'),
* and the item references a Label template that includes a Field Container element with a known
id* (so where the Field Container > Before Label and Item attribute includes an HTML element with * id="#CURRENT_ITEM_CONTAINER_ID#"), then it is assumed that everything pertaining to the item is contained * in the Field Container, and this will be shown.
* - If the item is a column item then just the column value is shown. The exact behavior depends on the * type of region. For example, in Interactive Grid just the cell content is shown not the whole column. *
See also {@link item#hide}.
* @example *Hides the Oracle Application Express item. When using the hide function, it is important to understand the following:
*-
*
- If the item being hidden is rendered on a page using table layout (meaning the page references a page
* template with Grid Layout Type set to 'HTML Table'), and the call to hide has specified to hide the entire
* table row (
pHideRow= true), then it is assumed that everything pertaining to the item is contained in that * row, and the entire row will be hidden.
* - If the item being hidden is rendered on a page using table layout, and the call to hide has specified
* not to hide the entire table row (
pHideRow= false, or not passed), then the function will attempt to hide * the item's label, where theforattribute matches theidof the item.
* - If the item being hidden is rendered on a page using grid layout (meaning the page references a page
* template with Grid Layout Type set to either 'Fixed Number of Columns', or 'Variable Number of Columns'),
* and the item references a Label template that includes a Field Container element with a known
id* (so where the Field Container > Before Label and Item attribute includes an HTML element with id="#CURRENT_ITEM_CONTAINER_ID#"), * then it is assumed that everything pertaining to the item is contained in the Field Container, and this * will be hidden.
* - If the item is a column item then just the column value is hidden. The exact behavior depends on the * type of region. For example in Interactive Grid just the cell content is hidden not the whole column. *
See also {@link item#show}.
* @example *Adds the given value to the current list of values of an item that supports multiple values. * Not all multi-valued items support this method.
* @example *Removes the given value from the current list of values of an item that supports multiple values. * Not all multi-valued items support this method.
* @example *Call to refresh the item. What it means for an item to be refreshed depends on the item. Not all items * support refresh. Typically an item such as a select list that has a list of options will refresh the * available options from the server. In most cases it is not necessary to call this method directly because * the declarative Cascading LOV Parent Items takes care of it automatically.
* @example *Places user focus on the Oracle Application Express item, taking into account how specific items are * designed to receive focus.
* @example *Sets a style for the Oracle Application Express item, taking into account how specific items are * designed to be styled.
* *Note: Using setStyle is not a best practice. It is better to add or remove CSS classes * and use CSS rules to control the style of items. Also keep in mind that the exact markup of native and plug-in items can * change from one release to the next.
* @example *Returns the display value corresponding to the value given by pValue for the Oracle Application Express item. * This method is intended for items that have both a value and display value, such as select lists.
*If the item type does not have a display value distinct from the value then pValue is returned;
* meaning that the value is the display value. For item types that have a display value but don't have access
* to all possible values and display values then this function only works when pValue is the current value of the item.
* For the native items, this only applies to item type Popup LOV.
* For item types such as select lists that have access to all their values, if pValue
* is not a valid value then pValue is returned.
pValue as described above.
*/
displayValueFor(pValue: string, pState: {
readonly: boolean;
disabled: boolean;
}): string;
/**
* Return a ValidityState object as defined by the HTML5 constraint validation API for the * Oracle Application Express item. If a plug-in item implements its own validation then the object may not contain * all the fields defined by HTML5. At a minimum it must have the valid property. If the item doesn't support * HTML5 validation then it is assumed to be valid.
* *This function does not actually validate the item value. For many item types the browser can do the * validation automatically if you add HTML5 constraint attributes such as pattern. Validation can be done * using the HTML5 constraint validation API.
* *Developers rarely have a need to call this function. It is used internally by the client side validation * feature. Item plug-in developers should ensure this function works with their plug-in.
* @example *Return a validation message if the Oracle Application Express item is not valid and empty string otherwise.
* *The message comes from the element's validationMessage property. An APEX extension allows specifying a * custom message, which overrides the element's validationMessage, by adding a custom attribute named * data-valid-message. If the item has this attribute then its value is returned if the item is not valid. * As the name implies, the text of the message should describe what is expected of valid input, rather than * what went wrong.
* @example *A model holds data in memory for use by the UI layer. It corresponds to the view-model in the Model-View-ViewModel * (MVVM) pattern. The UI can both read and write the data. * A model can notify interested parties (subscribers) when the data changes. The data comes (is fetched) from * the server and updates can be written back (saved) to the server.
* *Models are created and managed with functions of the {@link apex.model} namespace. * A model is uniquely identified by a {@link model.ModelId}, which is a string name and optional string instance id.
* *A model can hold data of different shapes. They are:
*-
*
- table: The data is an ordered collection of records. In database or UI terms the record might be called a row. * See {@link model.Record}. *
- tree: The data is a single root record and each record including the root can have an ordered collection of * any number of child records. When dealing with trees it is common to call the records nodes. See {@link model.Node}. *
- record: The data is a single record. In some cases this is treated as a collection of one. *
Each record can have any number of named fields. See {@link model.Record}. All records in the collection must have
* the same set of fields although the value of some fields may be null. In database or UI terms the fields
* might be called columns. The actual storage of a record could be an object or an array. If records are objects then the
* fields of the record are the properties of the object. If the records are arrays the fields of the record are
* elements of the array and the {@link model.FieldMeta} index property is used to
* map from the field name to the record array index.
The model has very few restrictions on the values of fields and doesn't know the data type of the field. * However typically when the model data is backing APEX items or HTML form controls the values will all be strings. * The model optionally uses the following fields for specific purposes:
*-
*
- identity: A string value that uniquely identifies the record. There can be multiple identity fields.
* Required for editable models. See {@link apex.model.create} option
identityField.
* - meta: An object with additional metadata about the record. See {@link apex.model.create} option
metaField.
* - children: (tree shape only) An array of the child records (nodes). See {@link apex.model.create} option
childrenField.
* - parent identity: (tree shape only) A string value that identifies the parent record (node) of this record (node).
* Required for editable tree shaped models. See {@link apex.model.create} option
parentIdentityField.
*
Another special case is for field values that have a display value in addition to their intrinsic value. These
* composite values have the form: { d: "display value", v: value }
* When comparing values during {@link model#setValue} only the value is considered not the display value.
* Also when the changes are saved to the server just the value is included without being wrapped
* in an object. Other special fields such as identity or parent etc. cannot have this structure.
Aggregations:
*Aggregations are just rows that the server includes in order among all the other rows marked with meta data
* property agg: true. The aggregate record has most fields empty except for the
* aggregate fields that contain the aggregate value.
Retrieve model data from the server. Data is requested starting at the given offset (or 0 if offset is
* not given). Data is fetched in model option pageSize chunks.
* Can use either the callback argument or the returned promise to determine when the request is complete.
pOffset is beyond the end of the data or master record is
* inserted or deleted. If and only if a promise is returned, pCallback will be called.
* It receives no arguments when resolved and an Error argument when rejected.
*/
fetch(pOffset?: number, pCallback?: (...params: any[]) => any, pNoProgress?: boolean): PromiseFetch all the data from the server into the model. This repeatedly calls {@link model#fetch} until the server reports
* there is no more data. This is only for table shape models.
* Data is fetched in model option pageSize chunks.
Use with caution. Loading too much data onto the client can take a long time and cause the browser to * become unresponsive.
* @example *-
*
- offset: the current offset in the model that was just added *
- total: total records in the model (see {@link model#getTotalRecords}) *
- done: true if all the data is fetched false otherwise. When true this is the last time the callback is called. *
Fetches fresh data from the server for the given records. The existing records in the model are replaced
* with the new returned record from the server. The model must have a identityField
* option defined for this to work.
* Can use either the callback argument or the returned promise to determine when the request is complete.
pCallback is not called.
*/
fetchRecords(pRecords: apex.model.Record, pCallback?: (...params: any[]) => any): PromiseSave all changed model data to the server. The current changes are copied to the save request except
* that volatile fields are not included (they are omitted/deleted i.e. not null or undefined) and the metadata
* has the op property added with value "d" if the record was deleted,
* "i" if the record was inserted, and "u" if the record was updated.
* If the record has no metadata field defined then one is added. For array
* records it is the last element, for object records it is property _meta.
It is possible to continue making changes to the model while a save is in progress. * Can use either the callback argument or the returned promise to determine when the request is complete.
* *See also {@link apex.model.save}.
* @param [pCallback] - A function to call when the save request is complete. * callback( error, responseData ); * The callback is passed an Error argument or array of server errors only * if there is an error. Otherwise error is null. * @returns A promise if the save is initiated and null otherwise (there is already a save in progress or * there is nothing to save). If and only if a promise is returned, pCallback will be called. The promise receives no * arguments when resolved and an Error argument when rejected. */ save(pCallback?: (...params: any[]) => any): PromiseGive the model data. This is used in cases where the model doesn't get data from the server or at least * not using the built in mechanisms.
* @param pData - Model data to set. * @param [pOffset] - Offset at which to add the data. */ setData(pData: any[], pOffset?: number): void; /** *Remove all data from the model.
*/ clearData(): void; /** *Returns the total number of records in the model collection or -1 if unknown.
* *For table shape models the total number of records may not be known or it may be an estimate. * If the pagination type is "none" then the total records is known and it is the same as what is in the collection. * If the pagination type is "progressive" and the model has paged to the end (all pages * have been received and the server has said there is no more) then the total records is known and it * is the same as what is in the collection (which could be different from what is actually on the server). * If the server has told the model how many records it has then that is returned. This is an estimate of what * the client model may eventually hold. This value may change as new pages are fetched. * If the server has not told the model how many records it has then the total is unknown. *
*For tree shape models the total number of records is not often needed. * It is also not readily available so the nodes must be counted. The total doesn't include nodes that * have not yet been fetched and never returns -1 (unknown) even if there are nodes that haven't been fetched. *
*For record shape the number is always 1.
* *Note: Includes records that are marked for delete in the count. * Also includes aggregate records if any in the count.
* @returns The number of records or -1 if unknown. */ getTotalRecords(): number; /** *Returns the total number of records from the server's perspective or -1 if unknown.
* *For table shape models the server provides the total but for editable grids the number of inserted records * is added and the number of deleted records subtracted. This is so the number reflects what is likely * to be on the server after changes are saved.
* *For tree shape models this is not supported; returns -1.
* *For record shape models the number is always 1.
* *Note: Aggregate records are never included.
* @returns The number of records or -1 if unknown. */ getServerTotalRecords(): number; /** *Iterate over the model collection. Calls pCallback for each record in the model.
* Similar to Array.prototype.forEach. The model shape must be table or tree.
* This will never fetch new data. This includes aggregate records if any.
* For shape tree see also {@link model#walkTree}.
The callback receives the record, the zero based index of the record, and the identity (recordId) * of the record.
* @example *this
* when calling pCallback.
*/
forEach(pCallback: apex.model.IteratorCallback, pThisArg?: any): void;
/**
* Transform a copy of the table shape model data into another data structure according to the provided template rules. * The transformed output data structure is returned.
* @example ** select job, deptno, avg(sal) as avg_sal from emp group by job, deptno
* {
* a: {
* b: [<items go here>]
* }
* }
* An indexed field is the name of a record field wrapped in square brackets. * This creates an array for each unique value of the field. For example a path * of "a/[ENABLED]/b" where the field ENABLED can have values of "yes" and "no" results in output:
*
* {
* a: [
* {
* b: [<items for records with enabled = yes go here>]
* },
* {
* b: [<items for records with enabled = no go here>]
* }
* ]
* }
* -
*
- string: A string is the name of a record field and the resulting value is the value of that field or
* if it begins and ends with a single quote then the value is the text inside the single quotes or
* if it begins with ( and ends with ) the string inside the parens is the
* name of a record field and the resulting value is the raw value of that field not the display value
* or
showNullAsvalue.
* - function: The resulting value is the return value of the function * f(pContext, self, record, index, id) *
- object: the resulting value is a new object where the properties of the new object * are the same as the properties of this template object and the value of * the properties support the same options as item. *
- array: The resulting value is a new array where the value items in the new array * come from the template items in this array. The template items support the same * options as item. *
Array.prototype.sort that will sort the output array after all
* records are processed.
* @param pOptions.filter - Filter function( model, record, index, id) return true to include and
* return false to skip the given record.
* @param pOptions.showNullAs - A string to substitute for null field values.
* @param pOptions.includeAggregates - If true aggregate records are included otherwise they are
* skipped this is done before the filter function is called.
* @param pOptions.offset - Offset index of first record to process defaults to 0.
* @param pOptions.count - Count of records starting at offset
* to process. Defaults to all the data currently in the model.
* @param [pContext] - This is the output object to return with data arrays filled in based on the
* template rules. If pContext is not given an empty object is used as a starting point. All functions
* are called in the context of this object. Note: if the template rule(s) don't
* have a path then pContext can be an array.
* @returns The output data structure. Same object as pContext if it was given.
*/
transform(pOptions: {
template: {
path: string;
filter: (...params: any[]) => any;
uniqueIndexField: string;
item: any | any[] | string | ((...params: any[]) => any);
sort: string;
}[];
filter: (...params: any[]) => any;
showNullAs: string;
includeAggregates: boolean;
offset: number;
count: number;
}, pContext?: any): any;
/**
* Iterate over a range (page) of the model collection. This is only valid for table shape models.
* Calls pCallback for pCount
* records in the collection starting at pOffset.
* If the model doesn't yet contain the requested records they will be fetched from the server
* by calling {@link model#fetch}. If the collection has fewer records than requested or if there is an error
* fetching data from the server then pCallback is called with a null record.
The callback receives the record, the zero based index of the record, and the identity (recordId) * of the record.
* @example *pageSize page of records
* starting at offset currentPageOffset.pCallback for.
* @param pCallback - Function called for each record in the model collection.
* The function is given the current record, index, and id.
* @param [pThisArg] - Value to use as this when calling
* pCallback.
*/
forEachInPage(pOffset: number, pCount: number, pCallback: apex.model.IteratorCallback, pThisArg?: any): void;
/**
* Return the index of the record within the collection. The collection may include aggregate records. * Useful because {@link model#forEachInPage} method takes a starting index/offset.
* *Only applies to table and tree shape models. Throws an error if the model shape is record. * For tree shape models returns the index of the node among its siblings.
* @param pRecord - The record to return the index of. * @returns The record index or -1 if not in collection. */ indexOf(pRecord: apex.model.Record): number; /** *Return the record at the given index within the model collection. Only applies to table shape models.
* @example *Given a record return the unique identifier (id) for the record. The id is used in calls to * {@link model#getRecordMetadata} and {@link model#getRecord}. If the model has multiple * identity fields this returns a string representation of the combined fields.
* @example *someRecord
* and uses it to get the record metadata.Return the metadata object for the record given by the record id. This only applies to models that
* define an identity field with option identityField.
Upper layers can store information related to the record here. The metadata should be related to the * record itself and not the view of it.
* @example *someRecord
* is updated.pRecordId.
*/
getRecordMetadata(pRecordId: string | string[]): apex.model.RecordMetadata;
/**
* Call this method if any properties of the metadata returned by {@link model#getRecordMetadata} are changed * external to this module. Most record or field metadata should not be changed externally. However it may * be useful and reasonable to externally change metadata that comes from the records initially such as canEdit * or custom metadata properties. * The result of calling this method is sending a {@link model#event:metaChange} notification.
* @param pRecordId - Value of the record's identity field or array of values of the record's * identity fields or value returned by {@link model#getRecordId}. * @param [pFieldName] - Name of record field that has a metadata change if any. */ metadataChanged(pRecordId: string, pFieldName?: string): void; /** *Return metadata object for given field name. The field metadata is supplied when the model is created
* in option property fields.
Return the index/key to use for the given field name when accessing that field of a record. * Use the value returned from this method to access a record field without using {@link model#getValue}. * This will work regardless of if the records are stored as objects or arrays.
* @example *selectedRecords.Determine if the model has been changed in any way. See also {@link model#getChanges}.
* *Note: Auto inserted records don't count as changes unless they are also updated but * they are returned by {@link model#getChanges}.
* @example *Return an array of record metadata for all changed records. * Do not make any changes to the data structure returned. See also {@link model#isChanged}.
* @example *clearChanges before refresh
* the interactive grid would prompt the user to save changes.Return true if the model has any errors.
* @example *Return an array of record metadata for all records with errors. * Do not make any changes to the data structure returned.
* @returns Array of record metadata for error records. */ getErrors(): apex.model.RecordMetadata[]; /** *Select or unselect the given record.
* *This method should only be used by view widgets to persist the view selection state in metadata property
* sel.
* Note there is no notification about this metadata change. Listen to the view for selection change events. Also
* use the view to change the selection.
Unselect all the selected records. See also {@link model#setSelectionState}.
* *This method should only be used by view widgets to persist the view selection state in metadata property
* sel.
* Note there is no notification about this metadata change. Listen to the view for selection change events. Also
* use the view to change the selection.
Return the number of currently selected records. This only applies if a view is storing selection state * in the model. See also {@link model#setSelectionState}.
* *This is used by views that store view selection state in the model to return the selection count.
* @returns The number of selected records. */ getSelectedCount(): number; /** *Return an array of the selected records. This only applies if a view is storing selection state * in the model. See also {@link model#setSelectionState}.
* *This is used by views that store view selection state in the model to return the selection.
* @returns The selected records. */ getSelectedRecords(): apex.model.Record[]; /** * Determine if the given record can be edited. * *For a record to be editable:
*-
*
- the model must have the
editableoption set to true and
* - the type of the record must allow edit or *
- if the record has no type or doesn't specify if it can be edited the default type must allow edit *
- and if the model specifies an additional
checkcallback * function it must allow or deny the edit
*
For a record to be deletable:
*-
*
- the shape must not be record and *
- if the shape is a tree the record must not be the root record *
- the model must have the
editableoption set to true and
* - the type of the record must allow delete or *
- if the record has no type or doesn't specify if it can be deleted the default type must allow delete *
- and if the model specifies an additional
checkcallback * function it must allow or deny the delete
*
For any record or one or more specific records to be addable:
*-
*
- the shape must not be record and *
- if the shape is a tree the parent record is required and must have a children collection *
- the model must have the
editableoption set to true and
* - if the shape is tree the type of the parent record must allow add or *
- if the shape is table or the parent record has no type or doesn't specify if it allows add the * default type must allow add *
- and if the model specifies an additional
checkcallback function * it must allow or deny the add
* - then, for tree shape only, if adding is allowed and
pRecordsToAdd* is given then check if the type of each record to add is a valid child type for the parent using * validChildren type property.
*
For a record to be draggable:
*-
*
- the shape must not be record and *
- the model must have the
editableoption set to true and
* - the type of the record must allow drag or *
- if the record has no type or doesn't specify if it can be dragged the default type must allow drag *
- and if the model specifies an additional
checkcallback function * it must allow or deny the drag
*
Determine what drag operations are allowed for a set of records. Not all views support dragging. * Dragging is a view operation. The model provides this method simply to allow type based configuration * of available drag operations. Note: The model types option is not currently documented and may change * in the future.
* @param pRecords - array of records to determine drag operations for or null when dragging * an external record into this model. * @returns object with allowed drag operations. The properties are: "normal", "ctrl", "alt", "shift", "meta". * The standard values are "move", "copy" or "add". Other values are allowed. The normal property is required. * The default is:{ normal: "move", ctrl: "copy" }
* or if pRecords is null { normal: "add" }
*/
dragOperations(pRecords: apex.model.Record[]): any;
/**
* Low level operation permission checking. Better to use {@link model#allowEdit}, {@link model#allowDelete}, * {@link model#allowAdd}, {@link model#allowDrag}. * The purpose is to determine what kinds of edits are allowed.
* *If the model is not editable (editable option is false) then no operations are allowed. * Also no operations are allowed on deleted records or aggregate records.
* *Operation checking is based on the type of the record (as determined by the type field) and the type * information given to the model in the types option. Type names are strings. The special type name * "default" is used to provide a default when records don't have a type or the type of the record doesn't * specify a value for the operation. Note: The model types option is not currently documented and may change * in the future.
* *Operations are strings. The standard operation permissions are "canAdd", "canDelete", "canEdit", * "canDrag". You can define your own as well.
* *First the record itself is checked to see if it allows the operation by checking if the record metadata contains
* the specified permission.
* Next the type of the record is checked to see if it allows the operation.
* If the record has no type or the operations for that type didn't specify a value for the operation then
* the default type is checked to see if it allows the operation.
* The value of an operation is true or false or a function that returns true or false. The function is
* called in the context of this model with arguments pRecord, pAddAction, pRecordsToAdd.
* If the model options includes a check function then it is called with the result so far and all the
* same arguments as this check function. See {@link model.CheckCallback}.
Return the record for a given record id. This only considers records that are currently fetched * into the model. The server may have a record with the given record id but if it hasn't yet been * fetched into the model, it will not be found with this method.
*For table or tree shape models that define an identityField
* option, call with the value of the record's identity field or if the records have multiple identity fields
* call with an array of ids or a string representation of the combined identity fields as returned by
* {@link model#getRecordId}.
For table shape models that don't define an identityField option
* call with the index of the record. This is the same as {@link model#recordAt}.
*
For record shape models call with no record id to get the one and only model record.
* @example *["AXB9", "00003"].pRecordId is found.
*/
getRecord(pRecordId?: string | string[]): apex.model.Record | null;
/**
* Get the value of a record field given the record itself * or omit the record when the model shape is record. See also {@link model#setValue}.
* @example *Set the value of a record field given the record itself * or omit the record when the model shape is record. See also {@link model#getValue}.
* *An error is thrown if the record does not allow editing or the field does not allow being set.
* @example *-
*
- "SET": The value was set. *
- "DUP": The value was not set because of duplicate identity. This can only happen when setting an * identity field. Note: Even if the new value is unique on the client it may still result in an * error when saving because the client in general does not have all the data that the server does. *
- "NC": The value was not set because the new value is equal to the old value. *
- null: The record is not in the model. *
Get the value of a record field given the record id. * This is only useful when the model shape is table or tree. * If there are many field values to get or set use {@link model#getRecord} followed by {@link model#getValue} * or {@link model#setValue}. See also {@link model#setRecordValue}.
* @example *Set the value of a record field given the record id. * This is only useful when the model shape is table or tree. * If there are many field values to get or set use {@link model#getRecord} followed by {@link model#getValue} * or {@link model#setValue}. See also {@link model#getRecordValue}.
* @example *Sets the validity and associated validation message of a record or record field.
* @example *checkRecord, that returns
* an error message if the record is not valid and null if it is valid. It then sets the validity of the record.
* Delete one or more records from a table or tree. *
*If the onlyMarkForDelete
* option is true the records are just marked for delete.
* Records marked for delete will be included in data returned by {@link model#forEach}, {@link model#forEachInPage},
* {@link model#walkTree}, etc. and can be found by {@link model#getRecord}. They will be deleted once the
* {@link model#clearChanges} method is called explicitly or implicitly after data has been saved successfully.
*
If the onlyMarkForDelete option is false
* the records are deleted right away and are no longer part of the model. In either case the deleted records
* are on the change list so the delete can be persisted.
If pRecords contains records that cannot be found in the collection
* or finds records that can't be deleted they are ignored and a debug warning is given.
Return true if the record exists in the model and has a change that can be reverted * (is updated or is deleted). See also {@link model#revertRecords}.
* @example *Revert one or more records to the way they were when first added to the model or last saved. * This undoes any changes made to the records. See also {@link model#canRevertRecord}.
* @example *pRecords if some of the records had no changes to revert.
*/
revertRecords(pRecords: apex.model.Record[]): number;
/**
* Inserts a new record into the collection. Only applies to tree and table shape models. * For tree shape models the record is inserted under the given parent node. The model must * allow adding new records. See {@link model#allowAdd}.
* @param [pParentRecord] - Parent tree node. Only for tree shape models, must be null otherwise. * @param [pAfterRecord] - Record after which to insert the new record. If not given * the new record is inserted at the beginning. * @param [pNewRecord] - The new record to insert. If not given a new record is created using defaults. * The identity, meta, children, and parent fields if any will be initialized. * @returns The temporary primary key of inserted record. */ insertNewRecord(pParentRecord?: apex.model.Record, pAfterRecord?: apex.model.Record, pNewRecord?: apex.model.Record): string; /** *Moves the given records to a new position in the collection (table or parentRecord's children) or, for * tree shape only, to a new parent node.
* *For tree shape models if there is a parentIdentityField
* the moved records will have the parent identity field
* set to the identity of the new parent record.
Copies the given records and inserts the copies into the collection (table or parent node's children) or, for * tree shape only, to a new parent node.
* @example *Return the root node of the tree. An error is thrown if the model shape is not tree.
* @example *Return the child at pIndex of node pNode.
* *This method must only be used on tree shape models.
* @example *Return the parent node of the given node. Only supported for tree shape models that have an
* identityField option defined.
This method must only be used on tree shape models.
* @param pNode - The node to get the parent of. * @returns Parent node or null for the root node and undefined otherwise */ parent(pNode: apex.model.Node): apex.model.Node; /** *Returns the number of children that node pNode has, or null if the answer is not yet known.
* A node that has its children lazy loaded may not know how many children it has until they are loaded.
This method must only be used on tree shape models.
* @example *Returns true if the node pNode has children, false if it does not,
* and null if not yet known.
* A node that has its children lazy loaded may not know if it has any children until they are loaded.
* @example
*
Fetch child nodes for node pNode.
* This method is only used for trees that lazy load data from the sever as needed. The top level
* of nodes should not be lazy loaded.
This is an asynchronous operation. When it completes the pCallback
* function is called with a status argument. Where status is:
*
-
*
- > 0 (or true) if 1 or more children were fetched. *
- 0 if the node has 0 children. *
- Error if there was an error fetching the children. *
Can use either the callback argument or the returned promise to determine when the request is complete.
* @param pNode - The node record to fetch children for. * @param [pCallback] - callback function that is called after nodes have been fetched or there is an error. * @returns A promise that receives count of children fetched when resolved and an Error argument when rejected. */ fetchChildNodes(pNode: apex.model.Node, pCallback?: (...params: any[]) => any): PromiseTraverse the tree shape model. Methods of the pVisitor object
* are called as follows:
-
*
- First the visitor
nodemethod is called for the *pNodepassed towalkTree.
* - If the node has children the remaining steps are done. *
- The visitor
beginChildrenmethod is called.
* - For each child node
walkTreeis called performing these steps recursively.
* - The visitor
endChildrenmethod is called.
*
pNode or null if
* pNode is the root. If this argument is omitted or undefined and
* the model has the identityField option defined the parent node
* will be determined automatically. If this argument is omitted or undefined and
* the model does not have the identityField option defined then
* the parent parameter in each call to the visitor node method is null.
*/
walkTree(pNode: apex.model.Node, pVisitor: {
node: (...params: any[]) => any;
beginChildren?: (...params: any[]) => any;
endChildren?: (...params: any[]) => any;
}, pParentNode?: apex.model.Node): void;
/**
* Subscribe to model change notifications by adding an observer.
* @example *viewId property if there is one. One is generated if not given in
* pObserver
*/
subscribe(pObserver: apex.model.Observer): string;
/**
* Unsubscribe to model change notifications.
* @example *viewId
* returned when subscribing.Get the value of the given model option. The model options are provided in the call * to {@link apex.model.create}. See also {@link model#setOption}.
* @example *onlyMarkForDelete option.hasTotalRecords option.Set the value of the given model option. The model options are provided in the call * to {@link apex.model.create}. See also {@link model#getOption}.
* *The options that can be set are:
*-
*
- genIdPrefix *
- pageItemsToSubmit *
- fetchData *
- saveData *
- regionData *
- parentRecordId *
- editable *
- pageSize *
The region interface is used to access region related methods and properties. You get access * to the region interface for a region with the {@link apex.region|apex.region} function.
* *Plug-in developers can define the behavior of their region by calling {@link apex.region.create}.
*/ declare interface region { /** *The jQuery object for the region element.
*/ element: jQuery; /** *Identifies the parent (master) region ID, if the region is the detail region of a master detail relationship. */ parentRegionId: string; /** *
Identifies the type of the region. Regions that don't implement a custom region interface have type "generic".
*/ type: string; /** *For regions that are implemented with a jQuery UI style widget, this is the name of the widget. For other * widget implementations it is null. It is used internally by the {@link region#call} method.
*/ widgetName: string; /** *Cause the region to get new data from the server or otherwise refresh itself. Not all regions support refresh. * Exactly what happens depends on the type of region.
* *This function should be used in place of the legacy way of refreshing a region, which was to trigger the * apexrefresh event on the region element.
* *The default implementation triggers the legacy apexrefresh event on the region element for backward compatibility * with old regions that don't implement this interface.
* @example *Cause the region to take focus. Not all native or plug-in regions support taking focus. It is up to the * specific region to determine where focus will go. Some regions manage focus such that there is a single * tab stop (or limited number of tab stops) and they may put focus to where the user last had focus within * the region.
* *The default implementation sets focus to the first element in the region that is capable of being tabbed * to.
* @example *Returns the widget associated with the region or null if the region isn't implemented with a widget. * Some advanced region types such as Calendar, Interactive Grid, or Tree are implemented using a widget. * This function provides access to the widget typically by returning a jQuery object for the widget element. * You can then call widget methods on the jQuery object. See also the {@link region#call} method.
* @example *selection-add-row action.Calls a method on the widget associated with the region. This method only applies to * regions that are implemented with a jQuery UI style widget.
* @example *emp and two equivalent ways of invoking the
* getSelectedRecords method.Return an alternative loading indicator for the given element. Not all regions have this method so * check if it exists before calling. For regions that support column items and when the column items may * not be visible on the screen at all times this allows the region to * place the loading indicator in an appropriate location. This can return the loading indicator passed in * or return a completely new loading indicator.
* @param pElement - DOM element that may represent a column item. * @param pLoadingIndicator$ - A loading indicator that can be inserted in to the DOM where desired and returned or ignored. * @returns loadingIndicator jQuery object or null if the region has no alternative for given element. */ alternateLoadingIndicator(pElement: Element, pLoadingIndicator$: jQuery): jQuery; }