Install plugin in a standard way. On some modern operating system, you can have an error on the launch plugin. Use this recipe:
Open terminal and type command like this (type correct path to DataBox.fmplugin file on your system)
Example:
sudo xattr -rd com.apple.quarantine /Users/YourUserName/Library/Application\ Support/FileMaker/FileMaker\ Pro/19.0/Extensions/DataBox.fmplugin
Click the right button and open file properties
Found the certificate and import into The certificates to Trusted Root Certification folder
The DataBox main structure is a dataset. The dataset is a vector of some values or other vectors. The vector is a named list of values with a given type. Types of vectors can be numbers, texts, dates, times, timestamps or datasets.
The DataBox works with data types in the same way like the FileMaker does and it returns data in given type, not only in text format. For example, it returns the date in the format corresponding to the user locale. The dataset type vectors are a hierarchical structure containing a set of vectors with different nesting levels.
The DataBox store data in the memory of the computer. It is can be a user’s computer or FileMaker Server machine. Datasets in memory are independent of open databases in FileMaker. It’s mean if you close your FileMaker file your data will not delete and be accessible. It’s mean also, you can transfer data between databases uses DataBox.
After finishing work in the FileMaker and closing app, all datasets are deleted from memory automatically, but it’s always good to delete all created datasets after finishing work forcibly. It’s especially important when working on server, because datasets will be accumulated in server memory until the reboot of the FileMaker server.
When multi-users work with a plug-in on the server, one should remember to give unique names to datasets while using it in FileMaker scripts or calculations to avoid mess in one’s data, since datasets are stored in computer memory.
Creates a new object in plug-in memory as a vector from any string separated by the delimiter.
DB_NewDataSet ( dataSetName ; dataType ; initValues ; delimiter ; replaceSign { ; datetimeMask } )
dataSetName - the dataset name will be created
dataType - the type of new dataset
initValues - the string with values
delimiter - the delimiter in values string
replaceSign - if the dataset with dataSetName already exists, it will be replaced when replaceSign = 1
datetimeMask - optional. The format string for correct parsing Date/Time/Timestamp values. Details about datetimeMask.
Note: When datatype is equal to “dataset”, parameters “initValues” and “delimiter” are ignored, use "".
“OK” - if successful
“Object already exists” - if the dataset with dataSetName already exists and replaceSign = 0
Error description - on error
DB_NewDataSet( "num1" ; "number" ; "1 2 3 4 5 6" ; " " ; 0 ) ;
New numeric dataset will be created in memory with name “num1” and values 1,2,3,4,5,6
DB_NewDataSet( "txt1" ; "text" ; "Scarlet Keira Charlize" ; " " ; 1 );
New text dataset will be created in memory with name “txt1” and values Scarlet, Keira, Charlize. The previous dataset “txt1” will be deleted.
DB_NewDataSet( "date1" ; "date" ; "2020-11-30 2020-12-17 2020-11-02" ; " " ; 0 ; "YYYY-MM-DD" );
New date dataset will be created in memory with name “date1” and values 2020-11-30,2020-12-17,2020-11-02.
DB_NewDataSet( "ds1" ; "dataset" ; "" ; "" ; 0 ) ;
New empty dataset will be created in memory with type “dataset” and name “ds1”.
Creates a new object in plug-in memory as a table. You should define name and type for each column.
DB_NewDataSetAsTable ( dataSetName ; columnNames ; columnTypes ; replaceSign )
dataSetName - the dataset name that will be created
columnNames - the column names are given via semicolon without spaces
columnTypes - the column types are given via semicolon without space in the same order with column names
replaceSign - if the dataset with dataSetName already exists, it will be replaced when replaceSign = 1
“OK” - if successful
“Object already exist” if the dataset with dataSetName already exists and replaceSign = 0
Error description - on error
DB_NewDataSetAsTable ( "SimpleTable" ; "num;fname;sname;product;date" ; "number;text;text;text;date" ; 1 )
New dataset as empty table will be created in memory with the columns “num”, “fname”, “sname”, “product”, “date”, as in the following example:
[1]num
[2]fname
[3]sname
[4]product
[5]date
Adds values to dataset from separated text by delimiter.
DB_AddValues ( dataSetName ; values ; delimiter {; datetimeMask } )
dataSetName - the name of existing dataset
values - the values are separated by delimiter
delimiter - the delimiter in values string
datetimeMask - optional. The string format for correct parsing Date/Time/Timestamp values. Details about datetimeMask.
Number of elements in dataset - if successful
“Object already exist” - if the dataset with dataSetName already exists and replaceSign = 0
Error description - on error
DB_AddValues ("num1" ; "6 7 8 9" ; " ")
Values 6, 7, 8, 9 will be added to existing dataset “num1”
DB_AddValues ("date1" ; "2020-06-19 2020-11-17 2020-01-30" ; " " ; "YYYY-MM-DD" )
Values 2020-06-19 2020-11-17 2020-01-30 will be added to existing dataset “date1”
Adds rows to table from separated text by delimiter.
DB_AddRows ( dataSetName ; tabletext ; row_delimiter ; cell_delimiter {; skipFirstRowSign; datetimeMask ; } )
dataSetName - the name of existing dataset
tabletext - the text separated by row_delimiter and cell_delimiter
row_delimiter - the delimiter in tabletext for rows
cell_delimiter - the delimiter in tabletext for cells
skipFirstRowSign - optional. If this parameter is 1, the first row will be ignored
datetimeMask - optional. The string format for correct parsing Date/Time/Timestamp values. Details about datetimeMask.
Number of elements in dataset - if successful
“Object already exist” if the dataset with dataSetName already exists and replaceSign = 0
Error description - on error
DB_AddRows ( "SimpleTable" ; "1 Iren Collin 2021-02-01@2 Jhon Devis 2021-01-01" ; "@" ; " " ; 0 ; "YYYY-MM-DD" )
The SimpleTable will be filled with new data, as in the following example:
[1]num
1 2
[2]fname
Iren Jhon
[3]sname
Smith Trew
[4]date
2021-02-01 2021-01-01
Moves existing dataset to the end of the other existing dataset vector with type “dataset”. The moved dataset no longer exist in the source place.
DB_MoveDataSet ( dataSetNameSource ; dataSetNameTarget ; replaceSign )
dataSetNameSource - the name of existing dataset will be move to target dataset
dataSetNameTarget - the name of existing dataset, where source dataset will be moved. The dataset should have “dataset” type
replaceSign - if the vector with name of dataSetNameSource already exists, it will be replaced when replaceSign = 1
“OK” - if successful
Error description - on error
DB_NewDataSet ( "num1" ; "number" ; "1 2 3 4 5" ; " " ; 1 )
The dataset with name “num1” and values 1,2,3,4,5 will be created in memory
DB_NewDataSet ( "DS1" ; "dataset" ; "" ; "" ; 1 )
The empty dataset “DS1” will be created in memory
DB_MoveDataSet ( "num1" ; "DS1" ; 1 )
The dataset “num1” will be moved to dataset “DS1”
Sets the value to dataset element by path.
DB_SetValue ( dataSetValuePath ; value )
dataSetValuePath - the path to element needs to be set. The path is formed from the names of the nodes specified through the symbol $ and indicating the number of element in [ ]. E.g.: DS1$num1[1]
value - the new value will be set
“OK” - if successful
Error description - on error
DB_SetValue ( "DS1$num1[1]" ; "55" )
For the first element in node num1 will be set value 55
Creates dataset as sequence of numbers, dates, time, timestamps from start position to end position with some step.
DB_Seq ( dataSetName ; dataType ; start ; end {; step } )
dataSetName - the dataset name will be created
dataType - the type of new dataset. It can be: num, date, time and timestamp.
dataSetValuePath - the path to element needs to be set
start - the start value. For dataset in date format it’s better to use FM function Date() or use values from fields in date format. The same rule is used for timestamp.
end - the end value. For dataset in date format it’s better to use FM function Date() or use values from fields in date format. The same rule is used for timestamp.
step - the step of increasing or decreasing sequence, by default 1.
“OK” - if successful
Error description - on error
DB_Seq ( "num" ; "number" ; 1 ; 5 ; 1 )
DB_Seq ( "num" ; "number" ; 1 ; 5 ; -1 )
DB_Seq ( "num" ; "number" ; 0 ; 0,9 ; 0,1 )
DB_Seq ( "date" ; "date" ; Date ( 12 ; 25 ; 2021 ) ; Date ( 01 ; 10 ; 2022 ) ; 1 )
DB_Seq ( "time" ; "time" ; Time ( 08 ; 15 ; 00 ) ; Time ( 08 ; 16 ; 00 ) ; 1 )
DB_Seq ( "timestamp" ; "timestamp" ; Timestamp ( Date (02 ; 01 ; 2021 ) ; Time ( 08 ; 15 ; 00 ) ) ; Timestamp ( Date (02 ; 01 ; 2021 ) ; Time ( 08 ; 16 ; 00 ) ) ; 1 )
Deletes dataset or value by index or name.
DB_Delete ( dataSetName )
dataSetName - The dataset name or path to the value will be deleted. The path to value is formed from the names of the nodes specified through the symbol $ and indicating the number of element in [ ]. E.g.: DS1$num1[1]
“OK” - if successful
Error description - on error
DB_Delete ( "DS1" )
DB_Delete ( "DS1$num1[1]")
Returns value from dataset element by path. The name of child elements is returned for ‘dataset’ type.
DB_GetValue ( dataSetValuePath )
dataSetValuePath - the path to element needs to be gotten. The path to value is formed from the names of the nodes specified through the symbol $ and indicating the number of element in [ ]. E.g.: DS1$num1[1]
Required value - if successful
“Index is out of range” - if there is no value with given index in dataset
Error description - on error
DB_GetValue ( "SimpleTable1$num1[1]" )
Returns index of the first founded element by value.
DB_GetIndexByValue ( dataSetName ; value { ; startIndex } )
dataSetName - the name of existing dataset or path to child node of dataset
value - the value needs to be found. FFor dataset in date format it’s better to use FM function Date() or use values from fields in date format. The same rule is used for timestamp
startIndex - optional. The number of element from where the search will be started
Index of element - if successful
0 - if value wasn’t found by given path
Error description - on error
DB_GetIndexByValue ("num1" ; 23 )
DB_GetIndexByValue ("date" ; Date (02 ; 01 ; 2021 ) ; 6 )
DB_GetIndexByValue ("SimpleTable1$txt2" ; "Bell")
Returns aggregated value like minimum, maximum, sum or average for dataset or for given range of dataset.
DB_Agregate ( dataSetName ; action {; start; end } )
dataSetName - the name of existing dataset or path to node of dataset
action - the function will be applied for data
start - optional. The starting element number
end - optional. The ending element number
Aggregated value - if successful
0 - if value wasn’t found by given path
Error description - on error
DB_Agregate ( "date1" ; "min" )
DB_Agregate ( "num1" ; "sum" ; 3 ; 5 )
Displays dataset as a list with named child elements or a list of dataset child elements values.
DB_GetDataSet ( dataSetName )
dataSetName - the name of existing dataset or path to child element of dataset
Content of dataset - if successful
Error description - on error
DB_GetDataSet ( "SimpleTable1" )
Returns the following structure:
[1]num1
1 2 3 4 5
[2]txt1
Iren Jack Rolf Mark Ben
[3]txt2
Johnson Davis Brown Wilson Bell
[4]date1
2020-11-30 2020-12-17 2020-11-02 2020-11-09 2020-12-31
DB_GetDataSet("SimpleTable1$txt1")
Returns the following structure:
Iren
Jack
Rolf
Mark
Ben
Returns dataset in JSON format.
DB_GetDataSetAsJSON ( dataSetName { ; aloneElemenAsArray ; pretty } )
dataSetName - the name of existing dataset or path to child element of dataset.
aloneElemenAsArray - optional. 1 or 0. If it equals 1, single value will be given in square brackets, if it equals 0 - the value will be given without brackets. 0 is by default.
pretty - optional. 1 or 0. It’s 1 by default, and it means that strings of JSON will be separated by line break. Otherwise all text will be written in one line.
Content of dataset - if successful
Error description - on error
DB_GetDataSetAsJSON ( "SimpleTable1" )
Returns the following structure:
{
"num1": [ 1, 2, 3, 4, 5 ],
"txt1": [ "Iren", "Jack", "Rolf", "Mark", "Ben" ],
"txt2": [ "Johnson", "Davis", "Brown", "Wilson", "Bell" ],
"date1": [ "2020-11-30", "2020-12-17", "2020-11-02", "2020-11-09", "2020-12-31" ]
}
DB_GetDataSetAsJSON ( "SimpleTable2" ; 1 )
Returns the following structure:
{
"num1": 1,
"txt1": [ "Iren", "Jack", "Rolf", "Mark", "Ben" ],
"txt2": [ "Johnson", "Davis", "Brown", "Wilson", "Bell" ],
"date1": [ "2020-11-30", "2020-12-17", "2020-11-02", "2020-11-09", "2020-12-31" ]
}
DB_GetDataSetAsJSON ( "SimpleTable2$txt2" )
Returns the following structure:
[ "Johnson", "Davis", "Brown", "Wilson", "Bell" ]
Returns dataset as a separated text by delimiter.
DB_GetDataSetAsTextTable ( dataSetName { ; row_delimiter ; cell_delimiter; headerOn ; columnsOrder ; start ; end; } )
dataSetName - the name of existing dataset or path to child element of dataset
row_delimiter - optional.The delimiter in text for rows, line break - Char (10) - by default
cell_delimiter - optional.The delimiter in text for cells, space by default
headerOn - optional. Column header is off by default ( 0 ). Set the value to 1 to enable the header
columnsOrder - optional. The list of column names to be displayed in the desired order. If empty, then all columns are displayed
start - optional. The starting dataset element number
end - optional. The ending dataset element number.
Content of dataset - if successful
Error description - on error
DB_GetDataSetAsTextTable ( "SimpleTable1" )
Returns the following structure:
1 Iren Johnson 2020-11-30
2 Jack Davis 2020-12-17
3 Rolf Brown 2020-11-02
4 Mark Wilson 2020-11-09
5 Ben Bell 2020-12-31
DB_GetDataSetAsTextTable ( "SimpleTable1" ; "@" ; "#" )
Returns the following structure:
1#Iren#Johnson#2020-11-30@2#Jack#Davis#2020-12-17@3#Rolf#Brown#2020-11-02@4#Mark#Wilson#2020-11-09@5#Ben#Bell#2020-12-31@###
DB_GetDataSetAsTextTable ( "SimpleTable1" ; Char(13) ; " " ; 1 )
Returns the following structure:
num1 txt1 txt2 date1
1 Iren Johnson 2020-11-30
2 Jack Davis 2020-12-17
3 Rolf Brown 2020-11-02
4 Mark Wilson 2020-11-09
5 Ben Bell 2020-12-31
DB_GetDataSetAsTextTable ( "SimpleTable1" ; Char(13) ; " " ; 1 ; "txt2;num1" ; 2; 4 )
Returns the following structure:
txt2 num1
Davis 2
Brown 3
Wilson 4
Returns dataset as HTML table.
DB_GetDataSetAsHTMLtTable ( dataSetName ; tableParameters { ; start ; end ; customJS ; datasetWHtmlPart } )
dataSetName - the name of existing dataset or path to child element of dataset
tableParameters - The set of parameters for HTML table formatting
start - optional. The starting dataset element number
end - optional. The ending dataset element number
customJS - optional. Any JavaScript, usually functions for processing data in table is used in “cond_function” in table description
datasetWHtmlPart - optional. Name of the new dataset which will be created and consist of separate parts HTML page. The dataset will be have four variables: CSS, JSBeforeBody, JSAfterBody and Body.
Content of dataset - if successful
Error description - on error
Format of HTML table is set by description of columns and a few common parameters.
The following parameters can be set via sign equal:
header - show or hide table header, it can be ‘on’ or ‘off’
header_class - the style of header in css
header_lock - lock table header, it can be ‘on’ or ‘off’. By default is off.
inlineChildTable - show or hide nested tables, it can be ‘on’ or ‘off’
container_height - height of table container. If height not specified height equal height of document
container_class - the style of container in css
row_onclick_script - name of the FileMaker script is applied by a click on row
row_onclick_script_column_as_parameter - the parameter for script from “row_onclick_script” parameter
row_class_odd - the style of odd table rows in css
row_class_even - the style of even table rows in css
row_class_hover - the style of hover table rows in css
columns.n - the name of column from dataset, n - the number of column in html-table
columns.n.prettyname - the name of column in table will be shown in header
columns.n.width - the width of column can be set in % and px
columns.n.format - dysplaing format of numeric values (C lang printf() style) and date, time and timestamp values (like mask, ex. YYYY-MM-DD hh:mm:ss)
columns.n.class - the style of column data in css
columns.n.class_header - the style of column header in css
columns.n.class_hover - the style of hover column in css
columns.n.onclick_script - name of the FileMaker script will be applied by a click on cell
columns.n.cond_function - the function for processing data can be used for example for indicating data or for changing format of data. The function body is set in “customJS” parameter
DB_GetDataSetAsHTMLtTable ( "SimpleTable1" ; " " )
Returns the following table:
DB_GetDataSetAsHTMLtTable ( "SimpleTable1" ;
`"
header = 'on';
row_onclick_script = 'script1';
row_class_odd = ' background-color: white; color: black; ';
row_class_even = ' background-color: lightgrey; color: black; ';
row_class_hover = ' background-color: green ; color: white; cursor:pointer;';
columns.1 = 'num1';
columns.1.prettyname = '#';
columns.1.width = '5%';
columns.1.class = 'color: red; font-size: 16pt;';
columns.1.onclick_script = 'script2';
columns.2 = 'txt1';
columns.2.prettyname = 'First Name';
columns.2.width = '15%';
columns.3 = 'txt2';
columns.3.prettyname = 'Second Name';
columns.3.width = '20%';
" ;
1 ; 4 ;
)
Returns the following table:
Applies expression for each element of dataset. Stores results to the new dataset or updates source dataset.
DB_sApply ( dataSetName ; expression { ; newDataSet ; newDataSetType} )
dataSetName - the name of existing dataset or path to child element of dataset
expression - the calculation is applied for dataset elements
newDataSet - the name of new dataset will be created based on modified data. It’s optional, if the parameter is not set the data is updated in source dataset.
newDataSetType - the type of new dataset. It’s optional
Modified data in source dataset or in new dataset - if successful
Error description - on error
sApply can be considered as a loop from the first element of dataset to the last element. The expression is the body of loop and it will be evaluated for each loop iteration. For each iteration you can use two key words elemidx and elemvalue.
elemidx - is the number of the iteration in loop, like counter in loop.
elemvalue - is value of element of the iteration.
These keywords are a fast way to use element in expression without functions like DB_GetValue(). From another side, you can think about expressions like lambda-function from other programming languages (ex. C++).
The expression ids evaluated like FileMaker’s calculation, so you can use any FileMaker’s functions, including ‘Let()’ to create complex expressions.
As the expression is the text, one should set it in quotes. For convinience, one can use apostrophe signs instead of quotes inside the expression. DB_sApply replaces all apostrophe signs with quotes before evaluation.
DB_sApply ( "SimpleTable1$num1" ;
"_elemidx_ &' ' &_elemvalue_ * 10 " ;
"result" ;
"text"
)
DB_GetDataSetAsJSON ("result")
returns:
[ "1 10", "2 20", "3 30", "4 40", "5 10" ]
Creates a new dataset with unique values from source dataset. It can be applied for all vector types except for dataset type.
DB_Uniq ( dataSetFrom ; dataSetTo )
dataSetFrom - the name of source dataset
dataSetTo - the name of target dataset
The number of unique values - if successful
Error description - on error
DB_Uniq ( "SimpleTable1$num1" ; "Uniq_num" )
Sorts data in dataset. It can be applied for all vector types except fordataset type. If dataset has dataset type, it sorts data only in direct column, not in all dataset.
DB_Sort ( dataSetName { ; direction })
dataSetName - the name of existing dataset or path to child element of dataset
direction - the order of sorting, 1 for ascending, 0 for descending. 1 is by default
The number of sorted values - if successful
Error description - on error
DB_Sort( "txt1" )
DB_Sort( "SimpleTable1$txt1" ; 0 )
Groups dataset by one column and saves results to the new dataset. The new dataset has special structure: the first element is vector named by source column with grouped values, the second element is named Details, it includes vectors named R[index] - by number of grouped values. There are vectors containing grouped data inside vectors R.
DB_Group ( dataSetName ; columnName ; newDataSetName )
dataSetName - the name of existing dataset
columnName - the name of column for groupping
newDataSetName - the name of target dataset
The number of grouped values - if successful
Error description - on error
For this dataset named SimpleTable3:
[1]num1
1 2 3 4 1
[2]txt1
Iren Jack Rolf Mark Ben
DB_Group ( "SimpleTable3" ; "num1" ; "SimpleTable4" )
returns:
[1]num1
1 2 3 4
[2]Details
[1]R1
[1]num1
1 1
[2]txt1
Iren Ben
[2]R2
[1]num1
2
[2]txt1
Jack
[3]R3
[1]num1
3
[2]txt1
Rolf
[4]R4
[1]num1
4
[2]txt1
Mark
Returns number of the verison of DataBox plug-In.
DB_Version
No parameters
The number of verison - if successful
Error description - on error
DB_Version
returns 1.0.1012
Returns objects number in dataset.
DB_Lenght ( dataSetName )
dataSetName - the name of existing dataset
Objects number - if successful
Error description - on error
DB_Lenght ("SimpleTable1")
returns 4
DB_Lenght ("SimpleTable1$num1")
returns 5
Returns 1 if dataset exists in plug-in memory, otherwise 0.
DB_IsExist ( dataSetName )
dataSetName - the name of dataset
1 or 0 - if successful
Error description - on error
DB_IsExist( "SimpleTable1" )
returns 1
Returns the list of datasets stored in plugin memory, with types and lengths.
DB_EnviromentInfo
No parameters
The list - if successful
Error description - on error
YY or YYYY for years value
MM for months value
DD for days value
hh for hours value
mm for minutes value
ss for seconds value
Examples:
“YYYY-MM-DD” - for format like “2020-11-02”
“YY-MM-DD” - for format like “20-11-02”
“DD.MM.YYYY” - for format like “23.02.2020”
“MM.DD.YYYY” - for format like “02.23.2020”
“hh:mm:ss” - for format like “23:15:10”
“YYYY-MM-DD hh:mm:ss” - if you use format like “2020-11-02 23:15:10”
Note 1: We strongly recommend using leading zero for values. “02.23.2020” - is correct. “2.23.2020” - can be incorrect
Note 2: The time is always used in 24h format. The 12PM/AM format is not supported