Projects:DigitalCoupons/Technical Documentation

Contents 1 Introduction 2 Module Definition 3 Application Dictionary Modifications 4 Processes 4.1 DigitalCouponsOrderLoaderHook 5 Client Components Structure 5.1 OBDICO.UI.ModalDigitalCoupons 5.2 OBDICO_DetailHeader 5.3 OBDICO_CouponList 5.4 OBDICO_CouponListElement 5.5 OBDICO_ManualMode 5.6 Buttons of the main popup

Introduction

The following document explains the technical structure of the Digital Coupons for Retail module.

Digital Coupons are coupons that can be accepted in Web POS as a payment method. These coupons include the following information: Issuing company code, coupon number, expiration date and amount.

Back to Main Project page

Module Definition

Name: Digital Coupons for Retail Repository: https://code.openbravo.com/erp/pmods/org.openbravo.retail.digitalcoupons Java Package: org.openbravo.retail.digitalcoupons DB prefix: OBDICO

Application Dictionary Modifications

A new field has been added to the OBPOS_APP_PAYMENT_TYPE table: Name: EM_OBDICO_ISDIGITALCOUPON; Type: char(1).

The following tables have been created:

1. Name: OBDICO_DIGITALCOUPONS

Columns:

• OBDICO_DIGITALCOUPONS_ID (PK)
• AD_CLIENT_ID
• AD_ORG_ID
• ISACTIVE
• CREATED
• CREATEDBY
• UPDATED
• UPDATEDBY
• FIN_PAYMENT_ID
• CHECKNO
• CHECKAMT
• EXPIRATIONDATE
• OBDICO_ISSUING_COMPANY_ID
• OBDICO_SUBTYPE_ID

Constraints:

• OBDICO_DC_AD_CLIENT: AD_CLIENT_ID references AD_CLIENT(AD_CLIENT_ID)
• OBDICO_DC_AD_ORG: AD_ORG_ID references AD_ORG(AD_ORG_ID)
• OBDICO_DC_PAYMENT: FIN_PAYMENT_ID references FIN_PAYMENT(FIN_PAYMENT_ID)
• OBDICO_DC_IC: OBDICO_ISSUING_COMPANY_ID references OBDICO_ISSUING_COMPANY(OBDICO_ISSUING_COMPANY_ID)
• OBDICO_DC_ST: OBDICO_SUBTYPE_ID references OBDICO_SUBTYPE(OBDICO_SUBTYPE_ID)

Indexes:

• OBDICO_DIGITALCOUPONS_CHECKNO: by CHECKNO

2. Name: OBDICO_ISSUING_COMPANY

Columns:

• OBDICO_ISSUING_COMPANY_ID
• AD_CLIENT_ID
• AD_ORG_ID
• ISACTIVE
• CREATED
• CREATEDBY
• UPDATED
• UPDATEDBY
• CODE
• NAME
• DESCRIPTION
• AD_IMAGE_ID

Constraints:

• OBDICO_IC_AD_CLIENT: AD_CLIENT_ID references AD_CLIENT(AD_CLIENT_ID)
• OBDICO_IC_AD_ORG: AD_ORG_ID references AD_ORG(AD_ORG_ID)
• OBDICO_IC_IMAGE: AD_IMAGE_ID references AD_IMAGE(AD_IMAGE_ID)
• OBDICO_IC_CODE_UNI: Unique(AD_CLIENT_ID, CODE)

3. Name: OBDICO_ISSUING_COMP_ACCOUNT

Columns:

• OBDICO_ISSUING_COMP_ACCOUNT_ID
• AD_CLIENT_ID
• AD_ORG_ID
• ISACTIVE
• CREATED
• CREATEDBY
• UPDATED
• UPDATEDBY
• OBDICO_ISSUING_COMPANY_ID
• FIN_FINANCIAL_ACCOUNT_ID

Constraints:

• OBDICO_ICA_AD_CLIENT: AD_CLIENT_ID references AD_CLIENT(AD_CLIENT_ID)
• OBDICO_ICA_AD_ORG: AD_ORG_ID references AD_ORG(AD_ORG_ID)
• OBDICO_ICA_FIN_FIN_ACCOUNT: FIN_FINANCIAL_ACCOUNT_ID references FIN_FINANCIAL_ACCOUNT(FIN_FINANCIAL_ACCOUNT_ID)
• OBDICO_ICA_ISSUING_COMP: OBDICO_ISSUING_COMPANY_ID references OBDICO_ISSUING_COMPANY(OBDICO_ISSUING_COMPANY_ID)

OBDICO_ICA_ORG_UNI: Unique(AD_CLIENT_ID, AD_ORG_ID, OBDICO_ISSUING_COMPANY_ID)

4. Name: OBDICO_SUBTYPE

Columns:

• OBDICO_SUBTYPE_ID
• AD_CLIENT_ID
• AD_ORG_ID
• ISACTIVE
• CREATED
• CREATEDBY
• UPDATED
• UPDATEDBY
• OBDICO_ISSUING_COMPANY_ID
• CODE
• NAME
• DESCRIPTION
• AD_IMAGE_ID

Constraints:

• OBDICO_ST_AD_CLIENT: AD_CLIENT_ID references AD_CLIENT(AD_CLIENT_ID)
• OBDICO_ST_AD_ORG: AD_ORG_ID references AD_ORG(AD_ORG_ID)
• OBDICO_ST_IMAGE: AD_IMAGE_ID references AD_IMAGE(AD_IMAGE_ID)
• OBDICO_ST_OBDICO_IC: OBDICO_ISSUING_COMPANY_ID references OBDICO_ISSUING_COMPANY(OBDICO_ISSUING_COMPANY_ID)
• OBDICO_UNIQUE_CODE_IC: Unique(AD_CLIENT_ID, OBDICO_ISSUING_COMPANY_ID, CODE)

Indexes:

• OBDICO_ST_OBDICO_IC_ by OBDICO_ISSUING_COMPANY_ID

Based on the mentioned tables, the following windows and tabs have been created:

• Issuing Company: new window to register issuing companies
  • Issuing Company Account
  • Subtype
• Digital Coupons: A child tab of Payment In.

Processes

DigitalCouponsOrderLoaderHook

This process is in charge of iterating the synchronized order’s payments and creating the necessary entries on the OBDICO_DIGITALCOUPONS table.

Client Components Structure

OBDICO.UI.ModalDigitalCoupons

The main modal dialog is defined on the kind OBDICO.UI.ModalDigitalCoupons. This kind provides an infrastructure to extend its components from external modules.

• The newAttributes array allows to add new fields to the popup body. It can be accessed through OBDICO.UI.ModalDigitalCoupons.prototype.newAttributes.
• The bodyButtons component contains the list of buttons of the modal popup. New buttons can be added by adding them to the components array of this component. It can be accessed through OBDICO.UI.ModalDigitalCoupons.prototype.bodyButtons.components.

The components included by default on the popup are the Details Header (kind: OBDICO_DetailHeader), the Manual Mode (kind: OBDICO_ManualMode) and the List Mode (kind: OBDICO_CouponList).

There are two visibility modes for the popup: a add coupon/manual mode (from which new coupons can be added to the ticket) and a list mode (from which the coupon list can be viewed). Depending on the visibility mode, not all fields and buttons are shown.

For external fields and buttons, there are several arrays to allow complete customization of their visibility:

• extraFieldsShownInManual: Specifies the list of fields to be shown on manual mode.
• extraFieldsHiddenInManual: Specifies the list of fields to be hidden on manual mode.
• extraFieldsShownInList: Specifies the list of fields to be shown on list mode.
• extraFieldsHiddenInList: Specifies the list of fields to be hidden on list mode.
• extraButtonsShownInManual: Specifies the list of buttons to be shown on manual mode.
• extraButtonsHiddenInManual: Specifies the list of buttons to be hidden on manual mode.
• extraButtonsShownInList: Specifies the list of fields to be shown on list mode.
• extraButtonsHiddenInList: Specifies the list of fields to be hidden on list mode.

This kind implements the following methods:

• setManualMode: Logic executed when the manual mode is shown.
• setListMode: Logic to be executed when the list mode is shown.
• addCoupon: Sends the onAddNewCoupon event to all the child components of the popup.
• resetFields: Sends the onResetFields event to all the child components of the popup.
• resetAllFields: Sends the onResetAllFields event to all the child components of the popup.
• initComponents: Performs the initialization of the kind’s components.
• executeOnHide: Logic executed the popup is hidden.
• executeOnShow: Logic executed the popup is shown. Sends the *onShowDigitalCoupons event to all child components to notify that the popup has been shown.
• getAmount: Helper function to set the Details Header.
• setCouponList: Function to rebuild the list view.
• addCouponToList: Utility function to add coupons to the list view.
• setDetailHeader: Function to set the Details Header.
• addCouponModel: Function that verifies the expiration date of a coupon and adds it to the ticket if the information is correct.
• isValidDate: Helper function to check the validity of a date.

OBDICO_DetailHeader

This kind implements the header shown on the popup, both in Manual Mode and on List mode. This header includes the following information:

• The amount of coupons added (for the current payment method).
• The sum of the amount of the added coupons
• The amount remaining to pay on the ticket.

The kind implements the following functions:

• setCount: Sets the given number as the new coupon number.
• setTotalAmount: Sets the given number as the new total amount.
• setRemaining: Sets the given number as the new remaining.

OBDICO_CouponList

This kind implements the list of coupons shown in list view. By default it is only visible in list view.

It implements the following function:

• addCoupon: Adds a new coupon (kind: OBDICO_CouponListElement) to the coupon list.

OBDICO_CouponListElement

This kind implements a coupon element/model on the coupon list (View List mode). This component includes a list of values to be shown, and a button to remove the coupon from the payment.

The values shown on the component can be extended or modified using the valueArray element of the component (accessed via OBDICO_CouponListElement.prototype.valueArray). Currently printed values are:

• The issuing company: OBDICO.UI.LineIssuingCompany
• The subtype.
• The coupon amount: OBDICO.UI.LineAmount
• The expiration date: OBDICO.UI.LineExpirationDate
• The check number: OBDICO.UI.LineCheckNumber

Special elements used on the valueArray element:

• OBDICO.UI.Separator: Prints a / to separate fields
• OBDICO.UI.LineSeparator: Forces a line jump between fields.

All meaningful values define a printValue function, which returns how the value will be shown.

OBDICO_ManualMode

This kind defines the Manual view, which allows to add coupons to the payment. The components of this kind are defined as part of an array (newAttributes), which allows extensions from external modules. Currently shown fields are Issuing Company (kind: OBDICO.UI.IssuingCompany), Check Number (kind: OBDICO.UI.Checknumber), Amount (kind: OBDICO.UI.Amount) and Expiration Date (kind: OBDICO.UI.ExpirationDate).

This kind implements the following methods:

• initComponents: Initializes the list components of this kind.
• addNewCoupon: Validates the data entered on the fields, and creates a new coupon model. This model is used by the addCoupon function of the main popup, which adds the coupon to the payment. If addNewCoupon finds errors in the coupon fields, it shows an error popup.
• resetFields: Resets all the fields to their default value, if exists.
• resetAllFields: Resets all the fields to the empty value.

Fields added to the newAttributes array may implement the following fields and methods:

• mandatory: This field defines if the field should be marked as mandatory. If true, the field label will be marked with an asterisk.
• isValidValue: This function defines which values are accepted, and also allows to define the optional/mandatory logic.
• resetValue: This function allows the definition of a default value.
• getCustomValue: This function allows the customization of the field before the value is set to the coupon (e.g. the amount is converted to number using this function).

Buttons of the main popup

By default, the following buttons are included on the popup definition:

• View List (OBDICO.UI.ModalDigitalCoupons_btnList): switches to the List Mode view. It is only available while on Manual Mode view.
• Add Coupon (OBDICO.UI.ModalDigitalCoupons_btnManual): switches to the Manual Mode view. It is only available while on List view.
• Add (OBDICO.UI.ModalDigitalCoupons_btnAdd): triggers the addNewCoupon function of the Manual Mode. It is only available while on Manual Mode view.
• Close (OBDICO.UI.ModalDigitalCoupons_btnClose): Closes the popup.