Vai al contenuto

# JavaScript Libraries Documentation

This document describes the custom JavaScript libraries used in the APEX application.

## Static Application Files

File Name | Description
--- | ---
ajaxUtils.js | AJAX utilities for dynamic updates and server communication
iframeObj.js | Jasper Reports integration wrapper

## ajaxUtils.js

Custom AJAX utility library for managing server-side communication and UI feedback.

### Functions

#### `notifica(pText, pType = null)`

Central dynamic notification function.

Parameters: - `pText` (string): Message text to display - `pType` (string, optional): Notification type - 'alert', 'success', 'error', 'warning', 'info'

Behavior: - Clears existing errors - If `pType` is provided, shows error notification at page level - If `pType` is null, shows success message

Example:

    notifica("Record saved successfully"); // Success message
    notifica("Error occurred", "error");   // Error message

#### `setSessionState(elemList, pCallback = null)`

Sets APEX session state for multiple items.

Parameters: - `elemList` (string): Comma-separated list of item IDs (without P prefix) - `pCallback` (function, optional): Callback function after session state is set

How it works: 1. Splits the element list by comma 2. Gets values for each element using jQuery 3. Creates a dictionary of item-value pairs 4. Calls APEX process `SET_ITEM_SESSION` to update session state 5. Executes callback with data and elements dictionary

Example:

    setSessionState("P22_EVENT_ID,P22_CLIENTE", function(pData, elems) {
        console.log("Session state updated");
    });

#### `ajaxExec(pName, clickObj, pParams, pCallback, pConfirm, pLoading, pAsync, pType)`

Generic AJAX execution wrapper for APEX server processes.

Parameters: - `pName` (string): APEX process name to execute - `clickObj` (jQuery object): Button/element that triggered the action - `pParams` (object): Parameters to pass to the process - `pCallback` (function): Callback function on success/error - `pConfirm` (string): Confirmation message (uses native confirm dialog) - `pLoading` (boolean): Show loading popup - `pAsync` (boolean): Execute asynchronously - `pType` (string): Response data type (default: 'text')

Features: - Prevents page unload during execution - Shows loading spinner on clicked element - Handles confirmation dialogs - Parses response and removes quotes - Executes callback with parsed data

Example:

    ajaxExec("SAVE_EVENT", clickBtn, {x01: eventId}, function(data, btn, params) {
        notifica("Event saved");
    }, "Are you sure?", true);

#### `execProcessAsync(pName, pParams, pPreExec, pCallback, pItems = null, clickObj = null, pConfirm = null, pLoading = null)`

Wrapper for async process execution with optional session state update.

Parameters: - `pName` (string): Process name - `pParams` (object): Process parameters - `pPreExec` (function): Function to execute before AJAX call - `pCallback` (function): Callback after process execution - `pItems` (string): Items to set in session state first - `clickObj`: Clicked element - `pConfirm` (string): Confirmation message - `pLoading` (boolean): Show loading indicator

Example:

    execProcessAsync("UPDATE_QTY", {x01: itemId}, null, function(data) {
        apex.region("LIST_PREL").refresh();
    }, "P22_EVENT_ID");

#### `execQueryAsync(pQuery, pPreExec, pCallback, clickObj = null, pConfirm = null, pItems = null, pLoading = null)`

Executes a SQL query asynchronously.

Parameters: - `pQuery` (string): SQL query to execute - `pPreExec` (function): Pre-execution function - `pCallback` (function): Callback with query results - `clickObj`: Clicked element - `pConfirm` (string): Confirmation message - `pItems` (string): Items to set in session state - `pLoading` (boolean): Show loading indicator

Note: Calls the `EXEC_QUERY` APEX process with the query in `x01` parameter.

## iframeObj.js

JavaScript wrapper for embedding Jasper Reports in iframes.

### Configuration

    var j_datasource = "default";      // Jasper datasource name
    var j_username = "jasperadmin";    // Jasper server username
    var j_password = "jasperadmin";    // Jasper server password
    var j_def_outp = "pdf";            // Default output format (HTML, PDF)

### Iframe Class

#### Constructor

    var Iframe = function(parentObj, id, attr) { ... }

Parameters: - `parentObj`: Parent DOM element - `id`: Iframe element ID - `attr`: Additional attributes

### Methods

#### `setCss(css)`

Sets CSS styles on the iframe.

Parameters: - `css` (object): CSS properties dictionary

Example:

    iframe.setCss({ width: "100%", height: "600px", border: "none" });

#### `setUrl(Url)`

Sets the iframe source URL.

#### `getUrl()`

Returns the current iframe URL.

#### `refresh()`

Reloads the iframe content.

#### `hide()`

Hides the iframe (display: none).

#### `show()`

Shows the iframe (display: block).

#### `jasperReport(dir, datasource, params, output, username, password)`

Generates a Jasper Reports URL and loads it in the iframe.

Parameters: - `dir` (string, required): Report path in Jasper server - `datasource` (string): Data source name (default: "default") - `params` (object): Report parameters as key-value pairs - `output` (string): Output format - 'pdf' or 'html' (default: 'pdf') - `username` (string): Jasper server username - `password` (string): Jasper server password

URL Format:

    /jri/report?_repName={dir}&_repFormat={output}&_dataSource={datasource}&_repLocale=it_IT&_repTimeZone=Europe/Rome&{params}

Example:

    var rptFrame = new Iframe(container, "reportFrame");
    rptFrame.jasperReport(
        "apcb/scheda_evento_rpt",
        "default",
        { P_EVENT_ID: eventId, P_TIPO: "PREVENTIVO" },
        "pdf"
    );

## Usage in APEX Pages

### Time Input Masks

The application uses inputmask library for time fields:

    Inputmask("99:99", {
        placeholder: "HH:MM"
    }).mask($("#P22_ORA_INI_EVENTO"));

### SweetAlert2 Integration

Used for enhanced confirmation dialogs:

    Swal.fire({
        title: 'Conferma',
        text: 'Vuoi continuare?',
        icon: 'warning',
        showCancelButton: true
    }).then((result) => {
        if (result.isConfirmed) {
            // proceed
        }
    });

### Interactive Grid Refresh

    // Refresh a specific interactive grid
    apex.region("LISTA_PRELIEVO").refresh();

    // Refresh with callback
    apex.region("OSPITI").widget().interactiveGrid("getViews", "grid").model.fetchRecords();

## Migration Notes

When migrating to React TypeScript:

1. AJAX Utilities - Replace with:
2. Axios or fetch for HTTP requests
3. React Query or SWR for data fetching

4. Toast library (react-toastify) for notifications

5. Session State - Replace with:

6. React Context or Redux for state management
7. URL parameters for shareable state

8. Session storage for persistence

9. Jasper Reports - Options:

10. Keep Jasper and embed via iframe
11. Migrate to SSRS, Crystal Reports
12. Use PDF libraries (QuestPDF, iTextSharp)

13. Use React-PDF for client-side PDF generation

14. Input Masks - Use:

15. react-input-mask
16. @react-input/mask

17. Material-UI TextField with InputProps

18. SweetAlert2 - Replace with:

19. MUI Dialog components
20. react-confirm-alert
21. Custom modal component

### Example React Migration

    // ajaxUtils.js equivalent in React
    import { toast } from 'react-toastify';
    import axios from 'axios';

    export const notifica = (text: string, type?: 'success' | 'error' | 'warning' | 'info') => {
      if (type) {
        toast[type](text);
      } else {
        toast.success(text);
      }
    };

    export const executeProcess = async <T>(
      processName: string,
      params: Record<string, any>
    ): Promise<T> => {
      const response = await axios.post(`/api/processes/${processName}`, params);
      return response.data;
    };