Customize your Runtime Creating your first BoxLang Module.pdf

Led by Brad Wood

Your runtime. Your way. Endless possibilities! In this session we’ll teach you how to customize your runtime, contribute built-in-functions and tags/components to your BoxLang runtime. Intimidated by Java? Don’t be! We will show you how to create your very first BoxLang runtime module without a single line of Java code!

1. WELCOME
Into the Box 2025: The Future is Dynamic!

2. www.intothebox.org
GET STARTED
Creating your first BoxLang Module

Customize your Runtime

3. Brad Wood
•Lead developer of CommandBox CLI
•BoxLang Framework Architect
•I’ve made 9,722 commits on GitHub since 2011
Senior Software Architect
[email protected] @bdw429s

4. ●BoxLang’s entire runtime is modular and extensible
●This was the case from day one of this project
●We have a ModuleService which is very similar to
ColdBox/CommandBox/ContentBox, but at the runtime level
●The BoxLang core allows anything to be dynamically registered
●Modules can be written entirely in Java, in BoxLang, or in a mix of both. You choose!
●Ortus has written dozens of “official” modules
●You can write your own private or public modules
●Publish your modules directly to ForgeBox for the world to use
BoxLang Modules

5. ●BIFs (Built In Functions)
●Components (formerly known as tags)
●Classes
●Interceptors (listening to core BL runtime event announcements)
●Custom Components (AKA Custom Tags)
●Jars
●Configuration
●Caches
●JDBC Drivers
●Custom Contexts/scopes
BoxLang Modules

6. ●Default locations
○boxlang_modules/ folder in the working directory
○modules/ folder inside the BoxLang home folder
●You can configure additional folders in the boxlang.json file
●You can configure additional folders via env variable
Module Locations

7. ●A folder
●A ModuleConfig.bx class
○configure()
■settings
■interceptors
○onLoad()
○onUnload()
●bifs/ folder
●components/ folder
●libs/ folder
Module Structure
The only requirement is the
ModuleConfig.bx
Everything else is optional!

8. ●A folder
●A ModuleConfig.bx class
○configure()
■settings
■interceptors
○onLoad()
○onUnload()
●bifs/ folder
●components/ folder
●libs/ folder
Module Structure

9. ●configure() method
○Runs when module is registered, but before it’s activated. Responsible for
creating settings structure which defines default settings for the module.
The user can override these in their BoxLang config!
●onLoad() method
○Runs when the module activates and can register additional items with
the runtime, or setup anything the module needs
●onUnload() method
○Runs when the module is unloaded (or the runtime shuts down). Clean up
and unregister any custom items.
ModuleConfig.bx

10. function configure() {
variables.settings = {
mySetting= "value",
anotherSetting= "another value"
}
}
Module Settings
ModuleConfig .bx

11. {
"modules": {
"myModule": {
"settings": {
"mySetting": "override value"
}
}
}
}
Module Settings Override
boxlang.json

12. function onLoad() {
boxRuntime.getConfiguration().registerMapping( "/foobar", "C:/foo/bar");
println( "This module is LOADED!" )
}
Module onLoad
ModuleConfig.bx

13. ●Every module gets an automatic class mapping created that points to the
root of the module
●/bxModules/moduleName/
●Customize the mapping name in your ModuleConfig.bx
this.mapping = "waffle"
●You can access files inside the module
fileRead( "/bxModules/myModule/resources/settings.json" )
●You can create classes from inside the module
new bxModules.myModule.models.FooService()

Automatic Mapping

14. ●Each module has a dedicated class loader, pointed at the lib/ folder.
●This is for 3rd party jars, or even custom Java classes you write
●Each module is an “island” so they won’t cloud the system
classloader with potentially different versions of the same library
●There is a namespace registered for Java class paths

new com.foo.JavaClass@myModule()

Module Classloader

15. There is not a specific convention for custom tags, but since there is a
mapping created that points to the root of the module and custom tags
are searched for in any mapping, you can just place a .bxm or .bxs
folder in the root of your module and it will be usable as a custom
component/tag.
Module Custom Components

16. ●BIFs -> Built In Functions
●First-class headless global functions like now() or fileRead()
●You can OVERWRITE core BIFs. Be careful! With great power comes
great responsibility.
●Add bx class to bifs/ folder
●Name of class is name of BIF
●Needs @BoxBIF annotation
●invoke() method runs it
●BIF arguments are passed along to the invoke() method
Register BIFs

17. import ortus.boxlang.runtime.types.DateTime;

@BoxBIF
class {

function invoke(){
return new DateTime();
}

}
BIF Example
bifs/Now.bx

18. ●Create one alias for the BIF with
@BoxBIF( "nowButCooler" )
●Create many aliases with
@BoxBIF( [
"nowButCooler",
"now2point0",
"nowBrad"
] )
BIF Aliases

19. ●Register BIF as member method on a type
@BoxMember( "array" )
●If the BIF name starts with the type name, then the
member method removes that text from the name
arrayAppend() becomes just myArr.append()
○Get fancy
@BoxMember( { "string": { "name": "append", "objectArgument": "string" } })
BIF Member Methods

20. @BoxBIF
@BoxMember( "array" )
class {

function invoke( Array arr, string str ){
arr.append( str.ucase() );
return arr;
}

}
BIF Member Example
bifs/ArrayAppendUcase.bx

21. myArr = [];

arrayAppendUcase( myArr, "brad" )

myArr.appendUcase( "brad" )
BIF Member Example

22. ●Components -> used to be called tags
●Components have both a template and a script sytnax
●First-class global like bx:http or bx:mail
●You can OVERWRITE core components. Be careful!
●Add bx class to components/ folder
●Name of class is name of component
●Needs @BoxComponent annotation
●invoke() method runs it
Register Components (tags)

23. Component Annotations
@BoxComponent
@BoxComponent( "MyAlias" )
@BoxComponent( "MyAlias", "AnotherAlias" )

@AllowsBody( false )

@RequiresBody( true )

24. ●invoke() arguments
○context - The BoxLang Context
○Struct attributes - The attributes passed by the user
○body - A function that represents the body of the component
○Struct executionState - Data about execution
Component invoke() method

25. @BoxComponent
@AllowsBody( false )
class {

function invoke( context, attributes, body, executionState ){
echo( "hello " & attriutes.name ?: "world" );
}

}
Component Example
components/SayHello.bx

26. <!--- Templating --->
<bx:sayHello name="Brad">

// Scripting
bx:sayHello name="Brad";
Component Example

27. @BoxComponent
@RequiresBody( true )
class {
function invoke( context, attributes, body, executionState ){
var buffer = newBuffer();
var bodyResult = processBody( context, body, buffer );
// handle return, break, or continue
if ( bodyResult.isEarlyExit() ) {
return bodyResult;
}
echo( buffer.toString().Ucase() );
}
}
Component Example 2
components/Scream.bx

28. <!--- Templating --->
<bx:scream>
I like spam!
</bx:scream>

// Scripting
bx:sayHello {
echo( "I like spam!" );
}
Component Example 2

29. Thank You!
The Future of Modern Development Starts Here, with you! ??????