Please Note: Before printing, you may need to adjust the Print Size within your browser to 100%.
Getting Started - Introduction
This tutorial explains how to create and maintain systems using the Freedombase Designer, including defining Classes, applying business rules using derivation, validation, and error message calculations, by settings relationships, and by using the Kick and Cascade functions.
This tutorial assumes that you have already worked through the Introduction to the Freedombase Designer tutorial.
Please note that customising the Web interface, applying existing or new business logic through custom code (subroutines or functions), and Web enabling an existing system, are covered in other tutorials.
It is recommended that you work your way through the Introduction to the Freedombase Designer tutorial first, and this Getting Started tutorial second, before working your way through any other tutorials.
Getting Started - System - Introduction
Now that you have gained a basic understanding of the Freedombase Designer, by working through the Introduction to the Freedombase Designer tutorial, we will actually start creating and maintaining software using Freedombase.
In simple terms, software is created in Freedombase by defining the (persistent) Classes - which can include connecting to existing tables - and then adding appropriate interface and business logic around those Classes.
All Classes within Freedombase are held within a system. Systems are just ways of collecting Classes together in some sensible form. Classes in different systems can interact with each other without any restrictions.
To begin with, navigate into the System Maintenance page, and create a new system, named 'DEMO', by entering 'DEMO' in the System field, and entering 'My Demo System' in the Description field. (If a system called 'DEMO' already exists, that system will be displayed for you. If it does already exist, feel free to use any other new system name, and replace references to DEMO in this tutorial with the new system name that you chose.) To create the new system, select 'Save' in the 'File' menu. The system will be created.
As already explained, Classes are created within one System. Classes can be created on the System page.
Freedombase initally provides five blank rows for creating Classes on the System page. However, if you want to create more than five, select File - Save when you run out of space, and five more blank rows will be displayed.
Getting Started - Class (part 1) - State Class
Still in the System page, enter STATE as a class name into the Class field, and enter 1 into the Number of Key Parts field, in order to tell Freedombase to use one attribute as the unique key to the class. Enter 'State Class' into the Description field, then click File - Save to save the class. You have now created a new class in the new system.
You can also create classes in the Class page, as well as creating classes in the System page, however the System page is often more convenient to use.
Getting Started - Class (part 1) - State Attributes
In order to add Attributes, we need to navigate into either the Class or the Attribute page. The Class page is generally the most convenient to use. To quickly and easily navigate to the Class page from the System page, select 'View' hyperlink, located to the left of the class you wish to add attributes to. In this case, select View to the left of the 'STATE' class.
Please note that Freedombase has created a 'DateTimeWritten' attribute. This attribute is used by Freedombase to handle optomistic locking. You should never delete or change the DateTimeWritten attribute. You should simply ignore it.
Setting the Number of Key Parts to 1, as we have already done, tells Freedombase that the first attribute we enter will be used as the unique key to the Class. (Setting the 'Number of Key Parts' to 2 would tell Freedombase that the first two attributes entered would combine to form the primary key, etc.)
Enter STATE into the Attribute column, and CHAR[3] into the Type column. (CHAR[3] allows both U.S. and Australian style State codes or abbreviations to be used.) Click File - Save to save and add 'STATE' attribute to the state class. Note that after you have pressed File - Save, Freedombase allocates a Position for the Attribute in the position field. That position can be changed manually if needed.
Because we set Number of Key Parts to 1, and we have entered one attribute, any remaining attributes we enter will simply be standard attributes of the class, ie they will not form part of the primary key. Enter 'DESCRIPTION' into the first blank attribute name field, and enter 'CHAR[60]' in the Type field. Click File - Save, to save the second attribute into the class. You have now added all the attributes onto this class that were required.
Please note that you do not have to click on File - Save after entering every attribute; you can enter as much data as will fit on the page in one go, and then click File - Save, if you prefer.
Getting Started - Class (part 1) - Derivation
In this particular example, we only want to store each State code in uppercase. Rather than restricting users to entering State codes only in uppercase, we can tell Freedombase to convert each State code entered into uppercase for us, regardless of what casing it was entered in. In the Derivation field for the STATE attribute, enter the calculation UPCASE(STATE). For the sakes of efficiency, enter 1 into both the Derivation Sequence and the Derivation Recurse fields.
This is an example of a very simple calculation. Calculations can be very complex if needed. Both calculations, and the use of the Derivation Sequence and Derivation Recurse fields, are explained in more detail further on in this tutorial; for now, please just enter calculations as defined, without being too concerned about the details, or what else is possible using calculations.
Getting Started - Validation - Introduction
In Freedombase, all attributes are validated against their data type, every time an instance (record) is updated into a class (table) through Freedombase.
In the example below, we have also added a validation calculation, that will validate that the contents of the attribute are alpha. If any attribute within a class fails any kind of validation, then that instance will not be written into the Class. Instead, the instance will be displayed back to the user, with an appropriate error message.
For the sakes of demonstration, we will validate that any values entered into the STATE attribute on the STATE class are alpha only, ie cannot contain numeric values. In the Validation field for the STATE attribute, enter the calculation ALPHA(STATE). For the sakes of efficiency, enter 1 into the Validation Recurse field.
As with the previous derivation calculation, this is a very simple example of a validation calculation. More complex validation calculations can be created as needed. More complex calculations are covered in more detail further on in this tutorial.
Getting Started - Validation - Error Message
The error message that is displayed when an attribute fails any type of validation, can be set by the developer, using a calculation. If the developer does not set a specific error message for this attribute, then Freedombase will create a generic error message. However, generally the developer should set a specific error message, to make the error message as meaningful and as helpful as possible.
In the Error Message field for the STATE attribute, enter STATE:' must be alpha only', including the single quotes, as shown on the image below. For the sakes of efficiency, enter 1 in the Error Recurse field for STATE. Click File - Save, to save the changes for the attribute.
Getting Started - Class (part 2) - Building the Process
After the class has been defined - by defining all attributes, derivations, validations, error messages, etc, and after saving all of those - you need to build or rebuild the process for the class.
The process is essentially a set of subroutines or functions, that contain all the business logic associated with the class.
Every time a change is made to a class, the process needs to be recompiled or rebuilt.
The Compile Result field shows the current status of the Class, which may be that the process is waiting to be rebuilt, or may be that the process has been compiled successfully.
The Compile Result field will show 'Waiting to be rebuilt' if the class is currently waiting to be rebuilt. If the process has been successfully rebuilt, the Compile Result field will show success compilation messages.
If you have not selected File - Save since your last change, select it now. The system will display a 'Waiting to be rebuilt' message. Then select Utilities - (Re)build Process.
After the process rebuild has finished, successful compilation messages will be displayed in 'Compile Result' field. This may take up to 10 seconds, depending on the operating system and database you are running on, and depending of course on the complexity of the class definition.
Please note that processes can be rebuilt from either the System or the Class page. Rebuilding processes from the System page, will cause all processes for the system on display to be rebuilt. Rebuilding processes from the Class page, will cause the current process for the class on display to be rebuilt.
Getting Started - Class (part 2) - Creating Templates
If we want, we can ask Freedombase to create default Web Templates for this Class. The easiest - and safest - way to do this, is from the System page.
1. Go to the System page, with your DEMO system on display.
2. Click on Utilities - (Re)create Templates.
3. Click on 'Yes' when Freedombase asks if you are certain you want to create default templates.
We have run this command from the System page, as when the command is run from the System page, Freedombase will check that a Login page and a Main Menu page exist. If they do not exist, it will create them. It will also create a Menu page for the DEMO system that we are creating. These three pages need to exist before we can gain access to the pages created for this class.
If the Login and Main Menu pages did not exist, they will have been created, and the Main Menu page will include a link to the new DEMO system that you are creating. However, if the Main Menu already existed, Freedombase will not have updated it to include a link to the new DEMO system. If this is the case, you will need to manually modify the Main Menu template, to include a link to the DEMO system menu page. Instructions for doing this follow.
Getting Started - Class (part 2) - Linking Templates
If the Main Menu template already existed, Freedombase will not have updated it to include a link to the DEMO system menu. You will need to manually modify the Main Menu template, and rebuild the template, in order to link to the DEMO system pages that have been created.
There are several different commands that create links between pages; we will use the Go command here.
The 'Go' command, could also be called the 're-direct' command, as it redirects the user to the Template page specified in the command line of the 'Go' command.
Navigate to the Template Maintenance page in the Designer, and bring up the Menu.htm template, by entering 'Menu.htm' in the 'File' field. (Be careful of the casing, Freedombase is case sensitive.)
Menu.htm, is the primary or main Menu page within Freedombase. It is also the default page that is displayed after a user has logged in, unless you have specified a different default page for the user.
Look for the text 'Navigate' within the template, within the text area on the Template page. Unless the Menu.htm template has been modified, this text will be the header to the navigation section of the main menu. You should see commands within the navigate section of the Template, similar to the following: <a href="javascript:FreedombaseCommand('Go SystemName_Menu.htm','')" title="Go to SystemName System">SystemName</a>
In order to add a link in to the DEMO system from the Menu.htm page, add the following command into the Menu.htm template: <a href="javascript:FreedombaseCommand('Go DEMO_Menu.htm','')" title="Go to Demo System">Demo</a>. Then select File - Save, then select Utilities - (Re)build Template. The Rebuild may take up to ten seconds to run, depending on the operating system and database that Freedombase is running on, and the complexity of the template. You are now ready to test the STATE class that you have added.
Getting Started - Testing (part 1) - Logging In
To log in to the user interface (instead of the Freedombase Designer interface), open another Web browser session, and use the same path as you used to log in to the Freedombase Designer; except, instead of using 'designer.htm' at the end of the command, use 'freedombase.htm'. Then log in with the same user id and password you used to log in to the Freedombase Designer.
It is of course possible to set up separate user logins, where those users do not have access to the Freedombase Designer, but for training and testing purposes we can use the same login and password.
Getting Started - Testing (part 1) - Main Menu
The main menu should now be displayed, and you should see the Demo option within the Navigate menu to the top left of the page. Click on the Demo option.
Getting Started - Testing (part 1) - Demo System
You should now see a list of all classes within the Demo system, to the top left of the page, within the Navigate menu. At the moment there is only one class, the STATE class, so there will be only one class listed. Click on the State option.
Getting Started - Testing (part 1) - Maintenance Page
You should now see the blank Demo State Maintenance page. This page can be used to add into, to update into, and to delete from, the Demo State class; to view data in the class; to search the class (in New, Expand/Or, Shrink/And, and Invert modes); and to request to view all the data in the class, or just the results of the most recent search.
Add a new State in, setting the State Code in the State attribute, and a description of the State in the Description attribute. Click File - Save when complete. Then click File - New, and add other State. Continue until you have at least five or six States entered.
Getting Started - Testing (part 1) - Selection Page
The selection page can be used to view all data within the class, or to view only the data from the most recent search. It can also be used to sort the data, by clicking on the appropriate attribute name. In the Maintenance page, click on the View - All link. This will bring up the Demo State Selection page, with all data that you have entered on display.
Try sorting the data, by clicking on one of the attribute names; click again, to reverse the order of the sort. (Note that the first sort may not alter the data on display, if the data was already output in order.) Now select one of the States, by clicking on the hyperlinked State code. This will return you to the Maintenance page, with that State on display.
Getting Started - Testing (part 1) - Updating Data
Change the description of the State, then click File - Save. Click View - All, and confirm that the Description has been updated. Select the State code hyperlink again, to take you back to the Maintenance page, with that State on display.
Getting Started - Testing (part 1) - Deleting Data
Click the File - Delete hyperlink, and click Yes when asked if you are sure you want to delete. You will be presented with a blank page. Click the View - All hyperlink, and confirm that the State has been deleted. Click File - New, to take you back to the Maintenance page, with no data on display.
Getting Started - Testing (part 1) - Derivation
To test that the UPCASE(STATE) derivation that we added against the STATE attribute works, enter a new State, with the state code in lowercase. Click File - Save. You will see that the State code has been converted to uppercase. Click View - All, and confirm that the State code has been saved in uppercase. Click File - New, to take you back to the Maintenance page, with no data on display.
Getting Started - Testing (part 1) - Validation
To test that the ALPHA(STATE) validation that we added against the STATE attribute works, enter a new state, with the State code as a number, eg '111'. Click File - Save. The error message that we entered will display (ie '111 must be alpha only.') and the data will NOT be saved into the class. To confirm that the data has not been saved into the class, click View - All. The new State, with the numeric code, will not be in the list of States.
Getting Started - Relationships - Customer Class
Add a new Class into the 'DEMO' system, called 'CUSTOMER', with 1 key part. Set the following attributes and derivations:
Attribute: CUSTOMER
Type: INT
Derivation: IF(CUSTOMER)THEN(CUSTOMER)ELSE(UNIQUE(DEMO_CUSTOMER_CUSTOMER))
Attribute: NAME
Type: CHAR[60]
Attribute: POSTCODE
Type: INT
Attribute: STATE
Type: CHAR[3]
Derivation: UPCASE(STATE)
Getting Started - Relationships - Relationship
Set the following relationship, at the base of the Class page, for the CUSTOMER class:
Attribute: STATE
Relation: =
Points At System: DEMO
Points At Class: STATE
Points At Attribute: STATE
Type: Mandatory
Click File - Save. Then go to the System page, with the Demo system on display, and click (Re)build Processes and then (Re)create Templates. Click 'Yes' when asked if you want to overwrite existing templates.
Getting Started - Testing (part 2) - Demo Menu
Swap back to the Web browser session running the user interface, and go to the Demo system menu. You will now see two menu options on the Demo system menu; Customer, and State.
Getting Started - Testing (part 2) - Customer Page
Go into the Customer page, and create a new Customer. To create a new Customer, leave the Customer field blank; enter the Customer name; optionally enter the Customer post code; and enter a valid State code in the State field, ie enter one of the State codes that is currently in the State class. Click File - Save. Freedombase will allocate a customer number.
Getting Started - Testing (part 2) - Select Option
You do not have to enter the State code; instead, try clicking on the 'Select' link to the right of the State field. A pop up will appear, with a list of all States in the State class. Select one of the State codes displayed. The pop up will disappear, and the State code selected will be placed in the State field against the Customer. Click File - Save.
(The screenshot below shows the popup select page. The default popup select page is the Demo State selection page.)
Getting Started - Testing (part 2) - View Option
You can go directly to the State page, with the Customer's State already on display, using the View option to the right of the State attribute. Click on the View option now; the State page will appear, with that State on display. The View link, in effect, allows you to drill to related data. This is known as a single drill.
From the State page, you can also single drill to any Customer within that State, by selecting the View hyperlink to the left of each Customer. At the moment there is only one Customer for this State, so only one Customer displays. Go back to the Customer page, and add in more Customers for the same and for other States; once entered, experiment with drilling between the different customers and states, using the View option.
Getting Started - Search and Drill - New
Freedombase alows you to search on any attribute or attributes within the same class, by entering data within those attributes on any Maintenance page, and then selecting the appropriate Search option, which will usually be New.
To test this, go to the Customer page; click File - New, to display a blank page; enter or select a valid State code in the State attribute; then click Search - New. All customers with that State code will be displayed, in the Selection page.
Getting Started - Search and Drill - Wildcards
[ and ] can be used as wildcards within searches; for example, to search for all customers whose names begin with 'FR', enter 'FR]' in the Name field on the Customer Maintenance page, and click Search - New. To find all customers whose names end with 'ITH', enter '[ITH' in the Name field on the Customer Maintenance page, and click Search - New. To find all customers with 'ANE' anywhere in the name, enter '[ANE]' in the Name field, then click Search - New.
Experiment with wildcard searches for a short time, until you are confident that you can use wildcard searches easily.
Getting Started - Search and Drill - Expand and Shrink
Complex searches can also be performed, using Search - New first, then Search - Expand/Or, Search - Shrink/And, or Search - Invert/Not.
For example, to find all customers in states 'NSW' or 'QLD', enter 'NSW' in the State field, then click Search - New; click File - New to return to a blank Customer Maintenance page; then enter 'QLD' in the State field, and click Search - Expand. All customers in either of those two States will now be listed. (You may need to enter different State codes to test this, depending on what data you entered into the State class, and into the Customer class.)
You could further refine the results of the above search, to only show customers with a surname of SMITH, by entering [SMITH in the Name field, then clicking Search - Shrink.
Please note that an Expand search is equivalent to an Or search (ie 'data that matched previously or matched this time'); a Shrink search is equivalent to an And search (ie 'data that matched previously and matched this time'); and an Invert search is equivalent to a Not search (ie 'all data that did not match last time').
Getting Started - Search and Drill - Invert
To find all customers who are NOT in a particular State, enter or select the particular State in the State field on the Customer Maintenance page; click Search - New; go back to the Customer Maintenance page; enter any data anywhere into any Customer field; then select Search - Invert. All customers NOT in the initial State searched for will be displayed.
Please note, that for Search Invert to operate, there must be some data entered into any attribute; the data will not be used in the search itself; however, Freedombase will only perform any kind of Search if some data has been entered into the page.
Getting Started - Search and Drill - View the Results
To view the current Search results at any time, click on the View - Search Results option. The current search results will be displayed in the Selection page.
Getting Started - Search and Drill - Multiple Drill
To carry the search results from one class to another class, ensure that you have an active/current search result for the from class; go to either the Maintenance or the Selection page for the to class; then select the View - Search Results option on the to class page. Freedombase will drill from the from class to the to class, and display the related data. This is known as a multiple drill, as it allows the user to drill from multiple instances to other, related, multiple instances, whereas the single drill only allows drilling from one instance to another.
Please note that the number of steps between the to and the from class does not matter; as long as there is a drill path between the two classes, Freedombase will drill successfully, regardless of the number of intermediate classes. You should, however, consider the performance implications of any kind of multiple drill between 'distantly' related classes before performing a multiple drill.
Getting Started - Business Logic - Calculations
We have already seen how business logic can be added using calculations, for example converting the STATE attribute to uppercase, validating that the STATE value entered was alpha, and generating a unique customer number when no customer number was already set.
However, these examples are among the most simple calculations possible; they only involve one or two functions or statements, and they only refer to the data of the attribute that they are attached to. In a full system, the calculations would be much more complex, ie they would include many more functions or statements in each calculation; and they would also refer to other attributes within the current instance, and data in other, directly or distantly related instances.
Please note that it is also possible to apply business logic using custom code (subroutines or functions) in Freedombase; however, applying business logic using custom code (suboutines or functions) is covered in a separate tutorial. This tutorial only covers applying business logic using derivation, validation, and error message calculations.
Getting Started - Business Logic - Recursion
Recursion is one aspect of the advanced, artifical intelligence based concepts within Freedombase, that allows Freedombase to apply most business logic without requiring custom code to be written.
Because Recursion within Freedombase is an advanced concept, it may be useful for you to initially skip the recursion tutorials - starting with the bulk of this page - that cover recursion. Once you feel confident that you understand Freedombase otherwise, you can then return to these three Recursion pages in order to understand the detail.
If you do choose to skip the three Recursion pages, including this one, for now, just remember to set the value '1' within any Recurse fields that you see within Freedombase. This is usually the most useful setting. Later on, when you feel more comfortable with Freedombase, feel free to come back and read through the Recursion tutorial pages. At that time you may wish to change some of the Recurse values that you set to '1' previously.
You may recall that we set Recurse to 1 for all Calculations, as we entered them. This is not necessary, but it can provide performance advantages, so it is a good idea. It provides performance advantages, because calculations are inherently recursive; every recursion requires processing time; so setting the recursion to 1 except for when another setting is specifically required, may improve performance.
Admittedly, unless you create a very complex calculation, with multiple levels of recursion, setting Recurse to 1 will make no noticeable difference on individual trnasactions; however, it is a good habit to get into, and will probably make the software more efficient when dealing with large numbers of transactions.
The result of one calculation, may be another calculation; and the result of that calculation may be another calculation, etc, etc, etc. To handle this, Freedombase will evaluate the calculation; it will then evaluate the result of the calculation; and then evaluate the result of that calculation; until either the result stops changing - meaning the result is a literal, not a calculation; or until the maximum Recurse has been reached. By setting Recurse to 1, we guarantee that Freedombase will stop evaluating after the first iteration; that is, Freedombase will evaluate the calculation, and then stop, it will not evaluate the result of the calculation.
Please note that if Recurse is not manually set, Freedombase will apply a default maximum recurse of 99. This default can be overridden by setting values in the Control class.
There are three different kinds of recursion within Freedombase; Class, Result, and Internal.
Getting Started - Business Logic - Class Recursion
Calculations can reference other attributes within the same instance; they can also reference other attributes in other related instances (ie instances in directly or distantly related classes).
It is possible for the derivation calculation on one attribute, to alter the result of the derivation calculation on another attribute, within the same instance.
To manage this - and to make sure that all instances are fully derived before being written to file - Freedombase provides class level recursion.
Essentially, class level recursion, causes Freedombase to fully derive each attribute within the instance; and then to derive each attribute again; and to keep doing so, until the instance stops changing. This means that the impact of interdependent calculations - calculations dependent on other calculations within the same class - is fully applied before the instance is written.
However, although Freedombase provides this capacity, in most circumstances it is not necessary to use it. Usually, it is sufficient to set the Derivation Sequence on each attribute, causing the attributes to be derived in the most efficient manner. Sequencing is explained further on in this tutorial; only class recursion is explained within this page.
For example, if we stored a delivery cost against each customer, and that delivery cost was derived from the customer's state, we would need to convert the state to uppercase before we could derive the delivery cost.
If the conversion of the state attribute to uppercase occurred after the delivery cost was derived, the delivery cost calculation would probably only work with class recursion.
In this example, Freedombase would derive the delivery cost first, and the state would be converted to uppercase second. The state would have changed, and possibly the delivery cost, so Freedombase would then derive the instance a second time.
The second time, the delivery cost would be derived, and the value would change; the state would be derived, but would not change. The instance has changed, so Freedombase would derive the instance a third time.
No data would change the third time, however, so Freedombase would then stop deriving the instance, and the instance would be ready to be updated into the class, assuming it passed validation rules.
You can set the maximum recursion to use against each class, in the Recurse Levels field for each class. In this case, Freedombase will recursively derive each attribute within that class that number of times, or until the instance stops changing, whichever occurs first.
For the sakes of efficiency, it is usually better to set Recurse Levels to 1, and to use derivation sequencing, as described further on in this tutorial, instead of using class recursion. Only use class recursion when it is specifically required.
Getting Started - Business Logic - Result Recursion
Result recursion refers to the fact that the result of a calculation may be another calculation; and the result of that calculation may be yet another calculation, etc.
It is possible to set a maximum recurse against each calculation; if this is set, then Freedombase will recursively evaluate that calculation, until either the calculation stops changing, or until the maximum recurse has been reached, whichever occurs first.
If the maximum recurse has been set to 1, then the calculation will not be recursively evaluated.
One example of a useful recursive calculation, could be where the description of each line on an invoice, needs to change depending on the customer.
In this case, it would be possible to store the calculation to be used to derive the description, against each customer, in an attribute on the customer class.
The invoice class would then contain a derivation calculation, that returned the value of that attribute from the customer. The first evaluation of that calculation would return the calculation from that customer class, specific to that customer; and the second evaluation would return the actual description to be used on the invoice for that customer.
It would also be possible to store the descriptions to be used on the invoice within a separate invoice descriptions class, and then store a key or link to that class, within the customer class. This would probably be a tidier method to use, allowing a central table of invoice description types to be created and maintained. Result recursion could still be used to first retrieve the correct invoice description type expression, and then to evaluate that expression.
Getting Started - Business Logic - Internal Recursion
Calculations can contain 'embedded' or internal calculations, which can contain 'embedded' or internal calculations, etc. There is no theoretical limit on the depth of embedding of internal calculations; however, there is a practical limit; calculations need to be simple enough to be understood by the next person to work on the system!
Please note that Freedombase only derives 'embedded' or internal calculations that are actually needed; for example, in an If ... Then ... Else ... scenario, if the Then clause is executed, any embedded or internal calculations within the Else clause will not be evaluated.
For more details on calculations, and what they can contain, including internal recursion, please see the Calculation Help page.
Getting Started - Business Logic - Sequencing
The class level recursion described previously is unnecessarily complex and inefficient for most requirements; instead of using class level recursion, it is usually more sensible to sequence the derivation calculations on each class.
In the example given previously of a delivery cost, that is derived based on state, and on state being converted into uppercase, you would set a lower sequence for the state derivation, and a higher sequence for the delivery cost derivation. This way, the state is always derived before the delivery cost, preventing the need for class recursion.
Generally, Recurse Levels should be set for each class, if derivation sequencing is set, in order to improve efficiency. Setting Recurse Levels to 1, turns off class level recursion for that class.
Getting Started - Business Logic - Setting Values
Calculations are functions that return a value. A calculation cannot actually do or update anything itself; all it can do is return a value. Where the calculation is defined, determines what that value is used for, or what the value causes.
The value returned by derivation calculations, sets the value of the attribute the derivation is attached to.
The value returned by validation calculations, determines whether the value of the attribute is valid or not. (If true, ie not zero and not null is returned, the value of the attribute is valid; if false, ie zero or null is returned, the value of the attribute is invalid. If any attributes fail validation, the instance will not be written to file, regardless of how many other attributes passed validation.)
Error message calculations return the text to be used as the error message, should the attribute the error message calculation is attached to fail validation.
Calculations can also be used on templates, in order to derive and display specific values on the page being returned, and in order to determine if parts of the page should be returned or not.
Getting Started - Business Logic - Attribute Modes
Attribute Modes is another one of the advanced concepts within Freedombase. Feel free to skip this page of this tutorial, until such time as you feel you understand the basic principles of Freedombase. At that time, come back to this page, and review Attribute Modes at that time.
Calculations can contain literals, and can refer to attributes. Attributes can be referred to in three different modes; Memory; Local Stored; and Distant Stored. Which mode is used depends on how the attribute is named within the calculation.
Memory Mode - If the calculation uses the attribute name only, for example STATE, then it is referring to the value of that attribute, of the instance currently in memory. This is the mode most often used.
An example of a calculation that we have used, that uses Memory Mode, is UPCASE(STATE).
Local Stored Mode - If the calculation uses the system.class.attribute name, for example DEMO_CUSTOMER_STATE, and the calculation is within the DEMO_CUSTOMER system and class, then it is referencing the value of that attribute currently stored on file. This mode is used less frequently, and is usually only used when checking if a value has changed.
An example of Local Stored mode is IF(STATE=DEMO_CUSTOMER_STATE)THEN('The state is the same')ELSE('The operator has changed or set the state').
Distant Stored Mode - If the calculation uses the system.class.attribute name, for example DEMO_STATE_DESCRIPTION, and the calculation is NOT used within the DEMO_STATE system and class, then it is referencing the values of that attribute in all related instances within the DEMO_STATE class.
In this particular example, there will only be one related instance. If there are multiple related instances, and the attribute values are all numeric, then the value of that attribute from all related instances will be summed together and used. If there are multiple related instances, and any attribute values are non numeric, then the attribute values will be concatenated together and used. This mode is used frequently, normally when there will be one related instance with a non numeric value, or when there will be multiple related instances with numeric values.
An example of this mode is DEMO_INVOICE_OUTSTANDING. (This could be the derivation calculation on a BALANCE attribute on a customer, used to keep the customer balance up to date.)
Getting Started - Business Logic - Related Data
Defining relationships between classes allows Freedombase to create a network of paths between classes, where the data in those classes is related, either directly or distantly.
The patent that has been accepted for Freedombase, and the awards that Freedombase has been recoginised in, were granted partly for the method that Freedombase uses to achieve this; essentially, Freedombase creates a network of paths throughout all related data.
Freedombase can then use this network to find data related to other data, regardless of the closeness or distance of the relationship.
It is this method that allows Freedombase to use the third attribute mode in calculations, the Distant Stored Mode.
Getting Started - Business Logic - Cascade
Because Freedombase knows how all data fits together, Freedombase is able to track:
1. When data has changed, and
2. Where that changed data is referenced in calculations on other classes.
Freedombase can then cause that other, dependant data, to be recalculated.
To demonstrate this, we will add another class into our Demo system, according to the following:
Class: ORDER
Key Parts: 1
Attribute: ORDER
Type: INT
Derivation: IF(ORDER)THEN(ORDER)ELSE(UNIQUE(DEMO_ORDER_ORDER))
Attribute: CUSTOMER
Type: INT
Attribute: AMOUNT
Type: MONEY
Add a new attribute onto the CUSTOMER class:
Attribute: BALANCE
Type: MONEY
Derivation: DEMO_ORDER_AMOUNT
Add a new attribute onto the STATE class:
Attribute: BALANCE
Type: MONEY
Derivation: DEMO_CUSTOMER_BALANCE
Go to the System page, and rebuild all processes and all templates for the DEMO system.
Getting Started - Testing (part 3) - Testing Cascade
Swap back to the usual user interface, and go to the Customer Selection page.
View All the customers, and check that the Balance attribute is blank. Then go into the Order page, and create some orders for some customers, setting the value of the Amount attribute as you go.
Go back to the Customer Selection page, and you will see that the Balance attributes now contain summations of all the order amounts for each customer. Now also go to the State Selection page, and you will see that the Balance attribute contains the summation of all customer balances for each state.
Please Note: The Cascade function must be running, before this testing will work. As a general rule, the Cascade function will run automatically on UniVerse and QM; and will need to be manually run, or at least manually set to run automatically, on jBase and OpenInsight. To manually run the Cascade function on a one off basis, go into the Control Page in the Freedombase Designer, and click on the Utilities - Cascade option.
Please note that Cascade may take several seconds to register and apply the changes.
Getting Started - Recommendation
You should now have enough knowledge of Freedombase to create systems, excluding custom code or subroutines, and excluding customising the interface. To better embed what you have learned thus far, please work your way through the following recommendatations. Remember to rebuild the processes, and to recreate the templates, after each change, so you can test each change:
1. Add a new PRODUCT class, that contains a PRODUCT code, a DESCRIPTION, and a PRICE.
2. Add a PRODUCT attribute onto the ORDER class, that is related to the PRODUCT attribute on the PRODUCT class.
3. Derive the AMOUNT attribute on the ORDER class, by setting it to the PRICE from the PRODUCT class.
4. Once the above has been achieved, add a PRICE and a QUANTITY attribute to the ORDER class, setting PRICE from the DEMO_PRODUCT_PRICE attribute, and setting AMOUNT to PRICE*QUANTITY.
5. Once the above has been achieved, turn the PRODUCT, PRICE, QUANTITY and AMOUNT attributes into a multi dimensional table within the ORDER class, by setting PRODUCT as the controlling attribute for these attributes.
6. Play around, making other changes or improvements as you think of them. The more comfortable you are with Freedombase, the easier you will find Freedombase to use, and the easier the remaining tutorials will be.
Getting Started - Wrapup
You have now finished the Getting Started tutorial, and are now able to create simple Web based, database driven systems using Freedombase.
You also have enough knowledge to create some more complex systems; however, more complex systems are likely to require some custom code or subroutines, and and likely to require customising the Web interface. Both of these are covered in other tutorials.
