Object scripting API – object g

Object evalGlobalObj defines functionality available for the object scripting using the g object.

Usable only in the application (locally processed) scripts.

All definitions are in the TypeScript latest edition.

export class evalGlobalObj {

// ******************* #datetime – functions related with date time manipulation **************
/** Return date difference from current datetime in minutes
 * * day has 1440 minutes so that 1 day old date return 1440
 * * day in future returns negative value, date in history positive
 * @example dateAgeMin(dtCreated) > 1440 checks if record is more than a 1 day old
 */
dateAgeMin(strDate: string | Date): number;


/** Returns primary user/client currency
 * @param getMark optional when true function returns currency mark instead of name
 * @example function returns EUR/USD/CZK/... with mark==true returns €/$/Kč/...
 */
currency(getMark?: boolean): string;


/** Function check if assertion is valid. Valid values are positive integer values or true
 * @param test – any value
 * @return true – test is valid non zero value or true
 *   false – otherwise
 * 
 * User function for attribute checks because it raise warning only if return false
 */
assert(assertion: any): boolean;


/** Returns true if date is in history */
isHistory(strDate: string | Date): boolean;

/** Method for testing date behavior on safari
 * NEVER USE IN PRODUCTION
 */
testDate(strDate: string): string;


/** returns date part of datetime 
 * @item field in the  date or string format
 * @short when true, short date format is returned
*/
getDate(item: string | Date, short: boolean = false): string;


/** returns date part of datetime */
getTime(item: string): string;


/** Return nearest largest time rounded to time-minute interval, default is 30 */
dtRound(roundTo?: number): string;


/** Returns actual timestamp as date or actual datetime shifted bacward or forward 
 * @param what name of the interval to shift (units of the interval)
 * @param count how much shift (size)
 * @param startDate optional date to start instead of current date time
*/
dtDate(what?: 'Date' | 'Month' | 'FullYear' | 'Hours', count?: number, startDate?: Date): Date;

/** Returns first day in month 
 * @param day – number of day to return (never relative!) or first (= 1) or last – last day of month
 * @param month – date month or month shift
 * @param year – year month or month shift
 * @param rel – true – relative calculation, relative to the current date or date from point attr
 *    – false calculated directly from values in attributes
 * @param sql – true – value returned as string for database (without '' around)
 * @param point – date – when passed relative calculation is made according the that date
 * @return
 *    day/month/year if the rel is false
 *    relative shift if the rel is true
 * @example firstInMonth( 1, -1, 0, true) return 1. of the month before actual month */
dayInMonth(day: number | string, month: number, year: number, rel: boolean = false, sql: boolean = false, point: Date = undefined): Date | string;

/** returns date differnce between start and end for user (string) 
 * @param start – first date to compare
 * @param end – last day to compare
*/
dateDiff(start: string | Date, end: string | Date): string;

/** Returns actual timestamp as string. Equal to @now */
get now(): string;

/** Function supporting calculating future working days – return date in future that gives enought working days 
 * @param dateIn – when interval starts
 * @param dayCount – how many woring days should shift
 * @param retDate – when true, it returns Date, when false (default) – convert it to the string
*/
dtfWorkDays(dateIn: Date | string, dayCount: number, retDate = false): Date | string;

/** Convert the start – end  to the human-readable interval
 * 
 * Notes:
 * * Works both intervals longer than a day and shorter than a day
 * * Works negative intervals – displays the negative value
 * 
 * @param dtStart : Date | string  – start of the interval (null-safe)
 * @param dtEnd : Date | string – end of the interval (null-safe)
 * @param workingOnly : boolean = true 
 *  – when true (default) function calculates in the working days only; for intervals shorter than a single day does not )
 * @param negativeWarning : boolean = true 
 *  – when true (default) negative values are returned with mark field around <mark>negative value</mark>
 * @return interval for user reading 
 *  * When start or end is null return is empty string
 */
dtInterval(dtStart: Date | string, dtEnd: Date | string, workingOnly: boolean = true, negativeWarning: boolean = true): string;

/** returns variant accoring the content;
 * * DEPRECIATED (and probably never used); stupid, use ?: instead
 * * When what is set returns first (if 3 attributes are given) or second variant (if 2 attrbitutes are given)
 * * When what is empty or undefeind, returns last vairant
 */
ifset(what: any, first: string, second?: string): string;

/** send information to the log 
 * @example =global.log('me')
 */
log(info: any, desc?: string): boolean;
/** returns true if used devices is mobile */
get isMobile(): boolean

/** Returns true if application is running as an application */
get isApp(): boolean

/** Returns true if user started script with ctrlClick */
get isCtrl(): boolean

/** check and set the offline mode
 * @param newVal – optional, when not set function return current value
 *  when set value is set from the newVal
 * @return boolean
 * – when no attributes provided – returns current settings
 * – when settings provided – return true if value changes or false when not changed
 * _Rmeber:_
 * * g.isOffline() should be used with parentheisffá
 */
offline(newVal?: boolean): boolean

/** return true / false is user assigned computer to be safe or not */
get isSafeComputer(): true | false | undefined

/** returns current date as string */
get today(): string 

/** Return application name loaded for client from settings 
 * For some unresolved reason didn't work shorter name appName but applName worsh
 * @example see mainPage subtitle for probably only single use
 */
get applName(): string


/** Returns number of days between to dates
 * _Warnings:_
 * * Not tested what exactly returns – should be verified before using
 * * Always returns non-negative value unusable for testing what date is before another
 */
days_between(d1: string | Date, d2: string | Date): string 

/** Returns icon of the given name optionally with hint on that 
 * @param iconName – name of the icon to get on output
 * @param tooltip – translated tooltip (use lang.get('tooltipName')), not only the name
 * If name is long (over 80chars) it is expcted that it contains direclty icon svg but it should start with <svg
 */
icon(iconName: string, tooltip?: string): string 

/** Evaluates content and returns first valid attribute
 *
 * Valid = does not contain @
 * _Warnings and notes:_
 * * Do not use for emails. Email contains @ and thus is cosidered to be invalid string
 * * Replaces a??b and a?b?c:d conditions with more secure way, rember that ''?2 returns '', although ''?2:3 returns 3
 *
 * Checked conditions:
 * * No @paramName strings with @
 * * Not null
 * * Not empty
 *
 * @param ...args strings – returns first valid string or '' – emtpty string
 */
valid(...args: string[]): string 

/** Function checks if exists enum 
 * @param enumName name of the checked enum
 * @param enumType – enum / userEnum; by default userEnum is checked (system enum has not reason not to exists...)
 * 
 * Both table and detail checks existence of the user enum automatically and don't display columns for not-defined enums
 * so that function has only rare usage in complex conditions
 */
existEnum(enumName: string, enumType: iattrDataType = 'userEnum'): boolean 

/** Translates enum value with the translation from enumeration (if enum is loaded)
 * @param enumName name of the enum in the format 'tsk/DecisionStatus'
 * @param enumType – enum|multiEnum|userEnum|multiUserEnum
 * @param defVal – default values used in case that enum is not in the list 
 * field is translated using the global list; allowed only for enum (not multienum)
 * @param defIcon – name of the default icon used with defVal
 * @param spanClass?:boolean|string – optional name of the class that is arund the enum val / icon
 */
enumVal(short: string, enumName: string, presForm?: enumPresentation, enumType?: iattrDataType, defVal?: string, defIcon?: string, spanClass?: string | boolean): string 

/** Returns field stored in the system enum
 * @param short short from string to identify lined, if empty / undefined function return ''  – empty string
 * @param enumName name of the system enum
 * @param fieldName name of the field to return; raises error if field not exist!
 * @param defaultValue optional value returned when field does not exists, if not defined, function raises error
 * @return content of the field form enum
 */
enumField(short: string, enumName: string, fieldName: string, defaultValue?: iAttrVal): iAttrVal 

/** Checks, if short is valid value from enum
 * @param short – null or short enum value 
 * @param enumName – name of the system enum
 * @return boolean – true – short is defined and from enum; false – elsewhere
 */
isEnumShort(short: string, enumName: string): boolean 

/** Checks, if needlw is in the string
 * Use it instead of includes when
 * * value can be null
 * * value can be number  (e.f. list of numbers – than it can also be a single number and is converted to the number)
 * 
 * This is more safe control
 * @param needle – value to search
 * @param str – value from database to searach in
 * * if str is boolean value, the value is returned as a function result
 * @param acceptNullNeedle – when true an needle is null, function returns true (nothing is everywhere), by default null is error
 * @return true if needle is in the str 
 */
isIn(needle: string, str: iAttrVal, acceptNullNeedle?: boolean): boolean 

/** Translates shorts in the string to the translation.
 * * Shorts should be in the form (<short>) and complete field is replaced with the translation
 * * Don't confuse function with g.enumVal. This function search for shorts in the complete (created by group_concat sql function)
 * @param value string to fill
 * * @example L1 L3
 * * @example (L1) (L3)
 * @example: see method tskSubjectCompetence that creates string processed by this methods
 * @param returnMask optional mask that can be filled with the ${enum} string and add additional taxts aroung
 * mask is used only in case that a value is found – enum value is place on the {e} location
 * * @example '({e})<br/>
 */
multienumVal(value: string, enumName: string, presForm?: enumPresentation, returnMask?: string): string 

/** Format multiUserEnum to the format similar with system enum */
multiUserEnum(value: string, enumName: string,): string 

/** Return first short from the multi enum field
 * Used when some other field is managed by the multiEnum field and should work with only single velur
 */
multiEnumSingleShort(value: string, enumName: string, retEmpty: string): string 

/** Returns icon from enum
 * @param short enum value to translate
 * @param enumName name of the enum in the module/enum structure
 * @param nameOnly optional, when true, function returns only icon name, not icon
 * 
 * Warning: use nameOnly for dynamicIcons. They are used in futher processing!
 */
enumIcon(short: string, enumName: string, nameOnly: boolean = false): string 

/** Return name of the object static icon 
 * Faster version of the =global.enumIcon('objName', 'frm/objectName')
 * If user has no right to use object, function returns undefined
 * @param objName name of the object or directly the obj
 * @param nameOnly?: boolean – when true, function returns only name of the icon, not icon
 * @param withHint?:boolean -when true, function returns not only icon but span that contains both icon and hint that shows name of the object
 * nameOnly is ignored with withHint
 * @return returns object icon translated or not
*/
objectIcon(objName: string | fdataObject, nameOnly?: boolean, withHint?: boolean): string 

/** Returns name of the object IDFieldname */
objectIDFieldName(objName: string): string 


/** Joins list of words like +
 * Note: It is usefull in case when command should separate variable name from next string
 * @param sep what separator id between items
 * * * nothing – no separator
 * * * nbsp – all content on the single line with space but nonbreakable
 * @param words – list of words to join
 */
join(sep: string, ...words: string[]): string 

/** Creates line from the content with spaces between
 * * Omit elements that are invalid
 * * Date object transfers to correct straing
 */
joinSpace(...words: any[]): string 

/** Convert date field or field from database to the humans-ready format 
 * @param format supports DT, D, T (datetime, date only, timeonly)
*/
dtForPerson(item: string | Date, format: string = 'DT'): string 

/** If field has value returns value with icon in front of it; otherwise empty string
 * @param field field to print
 * @param iconName name of the icon to use before item
 * @example subtitle:"=global.iconed(obj.mark, mark)"
 */
iconed(field: undefined | string, iconName: string): string 

/** return classID of the class which name is in the attribute, 
 * Returns undefined if class is not allowed for user not defined in the paramater */
classID(className: string): string 

/** Function returns true, if object has defined group in the about->groups */
objIsInGroup(objName: string, group: string): boolean 

/** Returns true if object has defined  user attributes (not only allowed but really some defined) */
hasUserAttributes(objName: string): boolean 


} // end of evalGlobalObj