Classes

Overview

The QodlyScript language supports the concept of classes. In a programming language, using a class allows you to define an object behaviour with associated properties and functions.

Once a user class is defined, you can instantiate objects of this class anywhere in your code. Each object is an instance of its class. A class can extend another class, and then inherits from its functions and properties (declared and computed).

The class model in QodlyScript is similar to classes in JavaScript, and based on a chain of prototypes.

For example, you could create a Person class with the following definition:

//Class: Person
 constructor(firstname : string, lastname : string)
 this.firstName = firstname
 this.lastName = lastname

function get fullName() -> fullName : string
 fullName = this.firstName+" "+this.lastName

function sayHello() -> welcome : string
 welcome = "Hello "+this.fullName

In a method, creating a "Person":

var person : cs.Person //object of Person class  
var hello : string
person = cs.Person.new("John","Doe")
//person:{firstName: "John", lastName: "Doe", fullName: "John Doe"}
hello = person.sayHello() //"Hello John Doe"

Creating classes

User classes

To create a new user class in Qodly Studio, click on the + button of the Explorer and give a name to the class:

You can also select New > Class from the menu bar, enter a name and click Create:

Data Model classes

Data Model classes are automatically created when you click on the <...> button in the model editor, when a dataclass is selected. For more information, please refer to this section.

Class definition

When naming classes, you should keep in mind the following rules:

• A class name must be compliant with property naming rules.
• Class names are case sensitive.
• Giving the same name to a user class and a datastore's dataclass is not recommended, in order to prevent any conflict.

A user class in Qodly is defined by a specific method file (.4qs), stored in the /Project/Sources/Classes/ folder. The name of the file is the class name. For example, a class named "Polygon" will be based upon the following file:

Project folder
 Project
  Sources
   Classes
    Polygon.4qs

Class stores

Available classes are accessible from their class stores. Two class stores are available:

• cs for user class store
• 4D for built-in class store

cs

cs : object

Parameter	Type		Description
Result	object	<-	Class Store containing all user classes of the current project

The cs command returns a Class Store object containing all user classes defined in the current project. This command is necessary to instantiate an object from a user class.

It returns all user classes defined in the opened project, as well as Data Model classes.

Example

You want to create a new instance of an object of myClass:

instance = cs.myClass.new()

4D

4D : object

Parameter	Type		Description
Result	object	<-	Class Store containing all built-in 4D classes

The 4D command returns a Class Store object containing all available built-in classes in the Qodly application. It provides access to specific classes such as CryptoKey.

Example

You want to create a new key in the CryptoKey class:

key = 4D.CryptoKey.new(newObject("type","ECDSA","curve","prime256v1"))

Class object

When a class is defined in the project, it is loaded in the QodlyScript language environment. A class is an object itself, of "Class" class. A class object has the following properties and function:

• name string
• superclass object (null if none)
• new() function, allowing to instantiate class objects.

In addition, a class object can reference a constructor object (optional).

A class object is a shared object and can therefore be accessed from different processes simultaneously.

Inheritance

If a class inherits from another class (i.e. the extends keyword is used in its definition), the parent class is its superclass.

When QodlyScript does not find a function or a property in a class, it searches it in its superclass; if not found, QodlyScript continues searching in the superclass of the superclass, and so on until there is no more superclass (all objects inherit from the "4D.Object" superclass).

objectClass

objectClass ( object ) -> object | null

objectClass returns the class of the object passed in parameter.

instanceOf

instanceOf ( object , class ) -> boolean

instanceOf returns true if object belongs to class or to one of its inherited classes, and false otherwise.

Class keywords

Specific QodlyScript keywords can be used in class definitions:

• function <Name> to define class functions of the objects
• function get <Name> and function set <Name> to define computed properties of the objects
• constructor to define static properties of the objects
• property to define static properties of the objects with a type
• extends <ClassName> to define inheritance
• super to call the superclass
• this to reference the object being processed

info

ORDA data model classes support additional keywords:

• exposed to allow external access to the function,
• function query <attributeName> and function orderBy <attributeName> to define additional database functions for calculated attributes.

function

Syntax

function <name>({parameterName : type, ...}){->parameterName : type}
// code

Class functions are specific properties of the class. They are objects of the 4D.Function class.

In the class definition file, function declarations use the function keyword, and the name of the function. The function name must be compliant with property naming rules.

tip

Starting a function name with an underscore character ("_") will exclude the function from the autocompletion features in the code editor. For example, if you declare function _myPrivateFunction in MyClass, it will not be proposed in the code editor when you type in "cs.MyClass. ".

Immediately following the function name, parameters for the function can be declared with an assigned name and data type, including the return parameter (optional). For example:

function computeArea(width : integer , height : integer)-> area : integer

Within a class function, the this command is used as the object instance. For example:

function setFullname(firstname : string, lastname : string)
 this.firstName = firstname
 this.lastName = lastname

function getFullname()->fullname : string
 fullname = this.firstName+" "+uppercase(this.lastName)

For a class function, the currentMethodName command returns <ClassName>.<FunctionName>, for example "MyClass.myFunction".

In the application code, class functions are called as member methods of the object instance and can receive parameters if any. The following syntaxes are supported:

• use of the () operator. For example, myObject.methodName("hello")
• use of a "4D.Function" class member method:
  • apply()
  • call()

Parameters

Function parameters are declared using the parameter name and the parameter type, separated by a colon (:). The parameter name must be compliant with property naming rules. Multiple parameters (and types) are separated by commas (,).

function add(x, y : variant, z : integer, xy : object)

If the type is not stated, the parameter will be defined as variant.

For more information on parameters, please refer to this page.

Return value

You declare the return parameter (optional) by adding an arrow (->) and the return parameter definition after the input parameter(s) list, or a colon (:) and the return parameter type only. For example:

function add(x : variant, y : integer)->result : integer
 result = x+y

You can also declare the return parameter by adding only : type and use the return expression (it will also end the function execution). For example:

function add(x : variant, y : integer): integer
 // some code
 return x+y

Example 1

// Class: Rectangle
constructor(width : integer, height : integer)
 this.name = "Rectangle"
 this.height = height
 this.width = width

// Function definition
function getArea()->result : integer
 result = (this.height)*(this.width)

// In a project method


var rect : cs.Rectangle
var area : number

rect = cs.Rectangle.new(50,100)  
area = rect.getArea() //5000

Example 2

This example uses the return expression:

function getRectArea(width : integer, height : integer) : integer
 if (width > 0 && height > 0)
  return width * height
 else
  return 0
 end

function get and function set

Syntax

function get <name>()->result : type
// code

function set <name>(parameterName : type)
// code

function get and function set are accessors defining computed properties in the class. A computed property is a named property with a data type that masks a calculation. When a computed property value is accessed, QodlyScript substitutes the corresponding accessor's code:

• when the property is read, the function get is executed,
• when the property is written, the function set is executed.

If the property is not accessed, the code never executes.

Computed properties are designed to handle data that do not necessary need to be kept in memory. They are usually based upon persistent properties. For example, if a class object contains as persistent property the gross price and the VAT rate, the net price could be handled by a computed property.

In the class definition file, computed property declarations use the function get (the getter) and function set (the setter) keywords, followed by the name of the property. The name must be compliant with property naming rules.

function get returns a value of the property type and function set takes a parameter of the property type. Both arguments must comply with standard function parameters.

When both functions are defined, the computed property is read-write. If only a function get is defined, the computed property is read-only. In this case, an error is returned if the code tries to modify the property. If only a function set is defined, QodlyScript returns undefined when the property is read.

The type of the computed property is defined by the return type declaration of the getter. It can be of any valid property type.

note

Assigning undefined to an object property clears its value while preserving its type. In order to do that, the function get is first called to retrieve the value type, then the function set is called with an empty value of that type.

info

In addition to function get and function set, ORDA classes also support the function query and function orderBy computed properties (named calculated attributes).

Example 1

//Class: Person

property firstName, lastName : string

constructor(firstname : string, lastname : string)
 this.firstName = firstname
 this.lastName = lastname

function get fullName() -> fullName : string
 fullName = this.firstName+" "+this.lastName

function set fullName( fullName : string )
 p = position(" ", fullName)
 this.firstName = substring(fullName, 1; p-1)
 this.lastName = substring(fullName, p+1)

//in a method
fullName = person.fullName // Function get fullName() is called
person.fullName = "John Smith" // Function set fullName() is called

Example 2

function get fullAddress()->result : object

 result = newObject

 result.fullName = this.fullName
 result.address = this.address
 result.zipCode = this.zipCode
 result.city = this.city
 result.state = this.state
 result.country = this.country

constructor

Syntax

// Class: MyClass
constructor({parameterName : type, ...})
// code

A class constructor function, which accepts optional parameters, can be used to create and initialize objects of the user class.

When you call the new() function, the class constructor is called with the parameters optionally passed to the new() function.

There can only be one constructor function in a class (otherwise an error is returned). A constructor can use the super keyword to call the constructor of the super class.

You can create and type instance properties inside the constructor (see example). Alternatively, if your instance properties' values do not depend on parameters passed to the constructor, you can define them using the property keyword.

Example

// Class: MyClass
// Class constructor of MyClass
constructor (name : string)
 this.name = name

// in a method
// you can instantiate an object
var o : cs.MyClass
o = cs.MyClass.new("HelloWorld")  
// o  ==  {"name":"HelloWorld"}

property

Syntax

property <propertyName>{, <propertyName2>,...}{ : <propertyType>}

The property keyword can be used to declare a property inside a user class. A class property has a name and a type.

Declaring class properties enhances code editor suggestions, type-ahead features and error detection.

Properties are declared for new objects when you call the new() function, however they are not automatically added to objects (they are only added when they are assigned a value).

Property names must be compliant with property naming rules.

The property type can be one of the following supported types:

propertyType	Contents
text	Text value
date	Date value
time	Time value
boolean	Boolean value
integer	Long integer value
number	number value
picture	Picture value
blob	Scalar Blob value
collection	Collection value
variant	Variant value
object	Object with default class (4D.Object)
4D.<className>	Object of the 4D class name
cs.<className>	Object of the user class name

info

The property keyword can only be used in class methods and outside any function or constructor block.

Example

// Class: MyClass

property name : string
property age : integer

In a method:

var o : cs.MyClass
o = cs.MyClass.new() //o:{}
o.name = "John" //o:{"name":"John"}
o.age = "Smith"  //error with check syntax

extends <ClassName>

Syntax

// Class: ChildClass
extends <ParentClass>

The extends keyword is used in class declaration to create a user class which is a child of another user class. The child class inherits all functions of the parent class.

Class extension must respect the following rules:

• A user class cannot extend a built-in class (except 4D.Object and ORDA classes which are extended by default for user classes).
• A user class cannot extend a user class from another project.
• A user class cannot extend itself.
• It is not possible to extend classes in a circular way (i.e. "a" extends "b" that extends "a").

Breaking such a rule is not detected by the code editor or the interpreter, only the check syntax will throw an error in this case.

An extended class can call the constructor of its parent class using the super command.

Example

This example creates a class called Square from a class called Polygon.

//Class: Square

//path: Classes/Square.4dm

extends Polygon

constructor (side : integer)

 // It calls the parent class's constructor with lengths
 // provided for the Polygon's width and height
 super(side,side)
 // In derived classes, super must be called
 // before you can use 'this'
 this.name = "Square"



 function getArea() -> result : integer
  result = this.height*this.width

super

super : object
super( param...paramN : any ) : object

Parameter	Type		Description
param	any	->	Parameter(s) to pass to the parent constructor
Result	object	<-	Object's parent

Description

The super command makes calls to the superclass.

super serves two different purposes:

1. Inside a constructor code, super allows to call the constructor of the superclass. When used in a constructor, the super command appears alone and must be used before the this keyword is used.
   • If all class constructors in the inheritance tree are not properly called, error -10748 is generated. It's up to the developer to make sure calls are valid.
   • If the this command is called on an object whose superclasses have not been constructed, error -10743 is generated.
   • If super is called out of an object scope, or on an object whose superclass constructor has already been called, error-10746 is generated.

constructor(t1 : string, t2 : string)
super(t1) //calls superclass constructor with a string param
this.param = t2 // use second param

2. Inside a class function, super designates the prototype of the superclass and allows to call a function of the superclass hierarchy.

super.doSomething(42) //calls "doSomething" function declared in superclasses

Example 1

This example illustrates the use of super in a class constructor. The command is called to avoid duplicating the constructor parts that are common between Rectangle and Square classes.

  //Class: Rectangle

constructor(height : integer, width : integer)
  this.name = "Rectangle"
  this.height = height
  this.width = width

function sayName()
  return("Hi, I am a "+this.name+".")

function getArea()-> area : integer
  area = this.height*this.width

  //Class: Square

extends Rectangle

constructor(side : integer)

  // It calls the parent class's constructor with lengths
  // provided for the Rectangle's width and height
super(side, side)

  // In derived classes, super must be called before you
  // can use 'This'
this.name = "Square"

Example 2

This example illustrates the use of super in a class member function.

You created a Rectangle class with a function:

  //Class: Rectangle

function nbSides() -> sides : text
  sides = "I have 4 sides"

You also created the Square class with a function calling the superclass function:

  //Class: Square

extends Rectangle

function description() -> desc : text
  desc = super.nbSides()+" which are all equal"

Then you can write in a method:

var square : object
var info : text
square = cs.Square.new()
info = square.description() //I have 4 sides which are all equal

this

this : object

Parameter	Type		Description
Result	object	<-	Current element or object

Description

The this command returns a reference to the currently processed object.

In most cases, the value of this is determined by how a function is called. It can't be set by assignment during execution, and it may be different each time the function is called.

When executing a formula object created by the formula or formulaFromString commands, this returns a reference to the object currently processed by the formula. For example:

o = newObject("prop",42,"f",formula(this.prop))
val = o.f() //42

When a constructor function is used (with the new() function), its this is bound to the new object being constructed.

//Class: ob

constructor  

 // Create properties on this as
 // desired by assigning to them
 this.a = 42

// in a method  
o = cs.ob.new()
val = o.a //42

When calling the superclass constructor in a constructor using the super keyword, keep in mind that this must not be called before the superclass constructor, otherwise an error is generated.

In any cases, this refers to the object the method was called on, as if the method were on the object.

//Class: ob

function f()
 return this.a+this.b

Then you can write in a project method:

o = cs.ob.new()
o.a = 5
o.b = 3
val = o.f() //8

In this example, the object assigned to the variable o doesn't have its own f property, it inherits it from its class. Since f is called as a method of o, its this refers to o.

Example

You want to use a project method as a formula encapsulated in an object:

var person : object
var g : string
person = newObject()
person.firstName = "John"
person.lastName = "Smith"
person.greeting = formula(Greeting)

g = person.greeting("hello") // returns "hello John Smith"
g = person.greeting("hi") // returns "hi John Smith"

With the Greeting method:

declare(param : string) -> vMessage : text
vMessage = param+" "+this.firstName+" "+this.lastName