Installation of the component

To install cleave-zen and use it in your project, you just need to follow the steps below:

1. Install the component from the OutSystems Forge.
2. Add a dependency to the module called “CleaveZen”.
3. Check all widgets and client actions you want to use.
4. Click on “Apply”.

Widgets

To use automatic formatting while typing in form input controls, follow these steps:

1. Place an input control to your UI, fill in a name and bind it to a variable of type Text.
2. Add the according CleaveZen widget for the format type you need (Credit Card, Date, Time, Numeral, Custom).
3. Set its WidgetId property to the ID of the input control you placed in step 1.
4. Configure the Options property according to your formatting requirements.
5. To also react on the detected credit card type of the CleaveZen_CreditCard widget, add an event handler for the OnTypeChanged event.
6. If you need to convert the Text values to the proper OutSystems data type (Date, Time, Decimal), use the client actions CleaveZen_GetDateValue, CleaveZen_GetTimeValue or CleaveZen_GetNumeralValue in your client flow that submits the form (e.g. the SaveOnClick handler).

Client Actions

You can also call the public client actions / functions of the Forge component in your client flows or client-side expressions:

Format text values:

• CleaveZen_Format*
  Format text as * (CreditCard, Date, Time, Numeral, Custom)
  • Value: Value to be formatted
  • Options: Type-specific format options to use
  • Result: Formatted text

Detect the credit card type or get the value of Date, Time or Numeral format as corresponding OutSystems data type:

• CleaveZen_GetCreditCardType
  Detect credit card type
  • CreditCardNumber: Credit card number to be detected
  • Delimiter: Delimiter text used in formatting
  • Result: Detected credit card type (Identifier)
• CleaveZen_GetDateValue
  Parse formatted date value to Date
  • FormattedDate: Formatted date value
  • Options: Date format options to use
  • Result: Date value
• CleaveZen_GetTimeValue
  Parse formatted time value to Time
  • FormattedTime: Formatted time value
  • Options: Time format options to use
  • Result: Time value
• CleaveZen_GetNumeralValue
  Parse formatted numeral value to Decimal
  • FormattedNumeral: Formatted numeral value
  • Options: Numeral format options to use
  • Result: Numeral value

Get the unformatted text representation of a formatted value:

• CleaveZen_UnformatCreditCard
  Unformat credit card number to simple text
  • CreditCardNumber: Formatted credit card number
  • Result: Unformatted credit card number
• CleaveZen_UnformatNumeral
  Unformat credit card number to simple text
  • FormattedNumeral: Formatted numeral value
  • Options: Numeral format options to use
  • Result: Unformatted numeral value, dot (.) as decimal mark
• CleaveZen_UnformatCustom
  Unformat credit card number to simple text
  • FormattedValue: Custom formatted value
  • Options: Custom format options to use
  • Result: Unformatted value

Format Options

Per type there is a specific options structure to configure the formatting:

• CleaveZen_FormatCreditCardOptions
  Options for creditcard formatting
  • Delimiter: Delimiter text to use in formatting, Default: space ( )
  • DelimiterLazyShow: Lazy add the delimiter only when the user starts typing the next group section
  • StrictMode: Enable credit card strict mode (expand use of 19-digit PANs for supported credit card)
• CleaveZen_FormatDateOptions
  Options for date formatting
  • DatePattern: Text list defining the date pattern, Default: ['d','m','Y']
  • Delimiter: Delimiter text to use in formatting, Default: slash (/)
  • DelimiterLazyShow: Lazy add the delimiter only when the user starts typing the next group section
  • DateMin: Min date boundary
  • DateMax: Max date boundary
• CleaveZen_FormatTimeOptions
  Options for time formatting
  • TimePattern: Text list defining the time pattern, Default: ['h','m','s']
  • Delimiter: Delimiter text to use in formatting, Default: colon (:)
  • DelimiterLazyShow: Lazy add the delimiter only when the user starts typing the next group section
  • Is12HoursFormat: Set to True to use 12-hours format
• CleaveZen_FormatNumeralOptions
  Options for numeral formatting
  • Delimiter: Delimiter text to use in formatting, Default: comma (,)
  • DecimalMark: Decimal mark, Default: dot (.)
  • DecimalScale: Number of digits after decimal mark, Default: 2
  • IntegerScale: Number of digits before decimal mark
  • PositiveOnly: Only allow positive values
  • ThousandGroupStyle: Thousands separator grouping style
  • Prefix: Prepend string that cannot be removed or changed in the input field
  • SignBeforePrefix: Set to True for the sign of the numeral should appear before the prefix
  • StripLeadingZeroes: Strip zeroes appearing at the beginning of the number, Default: True
  • Option TailPrefix is not supported as it is buggy in the cleave-zen JavaScript library.
• CleaveZen_FormatCustomOptions
  Options for custom formatting
  • Blocks: Integer list defining block lengths
  • Delimiters: Text list defining delimiters between blocks
  • DelimiterLazyShow: Lazy add the delimiter only when the user starts typing the next group section
  • Prefix: Prepend string that cannot be removed or changed in the input field
  • NumericOnly: Only allow numeric letters (0-9)
  • Uppercase: Convert value to uppercase letters
  • Lowercase: Convert value to lowercase letters