Context

Context can be described as information about the current environment or state. This can encompass things like the date inside the date picker, the currently selected object, and the organisation owning the currently selected object. Context can also change between different rows in a table, or when iterating through a list of objects using forEach() or calculate(). When writing Extended, it is important to be able to understand context, and how it can change. It can help you write dynamic code and understand why expressions are yielding certain results.

Keywords & Functions

Regarding context, there are several functions and a keyword that are worth highlighting. These are used very frequently when writing code, and are extremely useful for writing dynamic code.

this

this is a keyword that refers to the current context. It is commonly used in conjunction with the current object, organisation, or time period.

Current Object: On the web, the object whose page is currently open. In Configuration Studio, the currently selected object in the model.
Current Organisation: On the web, the owning Organisation of the object whose page is currently open. In Configuration Studio, the owning Organisation of the currently selected object in the model.
Current Period: On the web, the currently selected period in the date picker. In Configuration Studio, the currently selected period in the date picker.
Current User: On the web, the currently logged in user. In Configuration Studio, the user that launched the instance of Configuration Studio.

Note

When using this with the current object (this.object), it will only work with objects that can have children and behave as standalone pages. If a child only object, such as a Chart or Table is currently selected, its parent object will be considered the current object.

Expression	Result
`this.object`	The currently selected business object, or the owning business object.
`this.organisation`	The organisation the currently select object belongs to.
`this.nodetype`
`this.user`	The currently logged in User.

Examples

this.object.name                            // The name of the current object
this.organisation.id                        // The id of the current organisation

SELECT Kpi FROM this.object                 // Selects Kpis only from the current object
SELECT Kpi FROM this.organisation           // Selects Kpis from the current organisation and children

this.user                                   // Currently logged in User
t.KP001.responsible CONTAINS this.user      // True if the currently logged in user is in the responsible field of KPI 001

self

self is a keyword that can refer to the context object of a table row, or to the current context object of a calculate() based function. In both of these cases, it is possible call properties of the context object and write token expressions with them, without having to use self. However, self may still be required in more complex code with changing context. In these situations, it is common to assign self to a variable, and then utilize the variable instead of self. A well named variable can help structure code and make it more readable.

Examples

myKpis := SELECT Kpi
myKpis.table(id, name)                              // Creates a table of Kpis
    .addColumn("Owner", self.responsible)           // Adds a column with the responsible user(s) of the KPI
                                                    // .addColumn("Owner", responsible) would also give the same result

myKpis := LIST(t.KP001, t.KP002, t.KP003)           // Kpis "Revenue", "Cost", "Engagement Score"
kpiStrings := LIST()                                // Empty list

myKpis.calculate(
    curKpi := self                                  // Assigns context object in self to the variable

    newString := curKpi.id + " -- " + curKpi.name   // Forms a new string with specified format
    kpiStrings :+ kpiStrings.merge(LIST(newString)) // Creates a list with the new string and adds it to the list of KPI Strings
)

kpiStrings                                          // list of [KP001 -- Revenue, KP002 -- Cost, KP003 -- Engagement Score]

calculate

calculate() is a powerful function that is used to apply specific context to an expression. It can be used for calculating an expression for a particular object and time period, as well as iterating over and manipulating a list of objects.

If chained to an object or object variable, calculate() will use that object as the context for the expression. Otherwise, it will use the currently selected context.
If chained to a list, calculate() will iterate through each item in the list and apply the expression to that item and its context.
- A special keyword self can be used to refer to the item currently being iterated over.

Syntax	Result
`calculate(<expression>, [<startDate>], [<endDate>])`	Evaluates the expression for `startDate`, `endDate` for current context
`<object>.calculate(<expression>, [<startDate>], [<endDate>])`	Evaluates the expression for `startDate`, `endDate` for `object` context
`<list>.calculate(<expression>)`	Returns a list containing the result of evaluating the expression for each object in the list

expression: The expression that should be evaluated with the given context.
startDate: [Optional] The start date of the period context for which the expression should be evaluated.
endDate: [Optional] The end date of the period context for which the expression should be evaluated.
object: The object context that should be used for evaluating the expression.
list: The list of items for which the expression should be evaluated on each item.

Examples

calculate(actual, BOY, EOP)                         // calculates the actual YTD value of the currently selected context object


t.IND_001.calculate(target)                         // calculates the target for object with ID "IND_001" for the current time context
t.IND_001.calculate(target, BOP - 1Y, EOP - 1Y)     // calculates the target for the object with ID "IND_001" for 1 year ago from the current time context


myKpis := LIST(t.KPI001, t.KPI002, t.KPI003)
responsibleUsers := myKpis.calculate(responsible)   // returns a list of the responsible property value for each KPI in the list
responsibleUsers                                    // the list of responsible Users

myNodes := myKpis.calculate(
    curKpi := self                                  // assigns the individual Kpi currently being looped over to a variable

    curID := curKpi.id                              // assigns the id of the Kpi to a variable

    nds := SELECT Node WHERE id = curID             // queries for nodes that have the same ID
    nd := nds.first()                               // takes the first item of the nodes list (nodes list shoud either have 1 item or be empty)
                                                    // and assigns it to a variable

    nd                                              // yields the node variable as the value for the expression
)

myNodes                                             // A list of nodes with IDs that match the IDs of the KPIs in the myKpis list

Time Context Tokens

Extended has many token expressions that correspond to the context time.

Expression	Result
`this.start`	Start date of the current context period
`this.end`	End date of the current context period
`this.bop`	Beginning of the current context period
`this.bop.year`	Year of the beginning of the current context period
`this.bop.halfyear`	Half year of the beginning of the current context period
`this.bop.tertial`	Tertial of the beginning of the current context period
`this.bop.quarter`	Quarter of the beginning of the current context period
`this.bop.week`	Week of the beginning of the current context period
`this.bop.day`	Day of the beginning of the current context period
`this.eop`	End of the current context period
`this.eop.year`	Year of the end of the current context period
`this.eop.halfyear`	Half year of the end of the current context period
`this.eop.tertial`	Tertial of the end of the current context period
`this.eop.quarter`	Quarter of the end of the current context period
`this.eop.week`	Week of the end of the current context period
`this.eop.day`	Day of the end of the current context period
`this.period`	Name of the current period type
`this.dateRange`
`this.timePeriod`	Name and year of the current period
`this.timePeriod.start`	Start time of the current period
`this.timePeriod.end`	End time of the current period
`this.timePeriod.yearStart`
`this.timePeriod.yearEnd`
`this.timePeriod.number`	The positional number of the period within the context year.
`this.timePeriod.numberInYear`	The positional number of the period within the calendar year. October -> 10
`this.timePeriod.year`	The calendar year of the context time period.