Reference

↓ API • ↓ Command-Line • ↓ Datatypes • ↓ Directories • ↓ Objects • ↓ FFDL • ↓ Metadata • ↓ Queries • ↓ URIs

API Docs

API • ↓ Command-Line • ↓ Datatypes • ↓ Directories • ↓ Objects • ↓ FFDL • ↓ Metadata • ↓ Queries • ↓ URIs

The FatFractal Platform supports a variety of clientside and serverside environments.

You can access the following API docs from this page. Clicking on the links below will open a new window.

iOS API Doc	Java (Android) API Doc	JS (HTML5) API Doc	JS SVR API Doc
Download	Download	Download	Download

Command-Line Tools

↑ API • Command-Line • ↓ Datatypes • ↓ Directories • ↓ Objects • ↓ FFDL • ↓ Metadata • ↓ Queries • ↓ URIs

ffef

• Scaffold a new application
• Deploy an application, either locally or to the cloud
• Retrieve the current backend definition of your application

The executable is located in the runtime/ffnsbin directory of your install.

The forms of the command are:

Each form is described below.

newapp

ffef newapp <application name> <domain>

Scaffold a new application with the specified domain. Generally run from within a directory specifically for the application. Scaffolding creates the directory structure and configuration files for your application.

deploylocal

ffef deploylocal

Deploy the application in the current directory to the local engine.

deployFFFabric

ffef deployFFFabric

Deploy the application in the current directory to the FatFractal fabric, i.e. the cloud.

getFFDL

ffef getFFDL <local application URL>

Retrieve the FFDL application definition from the application at the specified URL. Note that this command only applies to local deployments. Should be run from the application’s directory.

When you run this command, the application’s current application.ffdl file is renamed to application.ffdl.<datetime>, and the application definition retrieved from the provided URL is saved as application.ffdl.

ff-service

The ff-service command is used to start and stop a local engine. The command should be run from the runtime directory of your install. The executable is located in the runtime/bin directory of your install.

The forms of the command are:

Each form is described below.

cl

Start the engine in the foreground.

start

Start the engine in the background.

stop

Stop the engine running in the background.

USAGE NOTE: If your engine is configured to use the default HTTP/HTTPS ports of 80/443, you may need to run the ff-service command as root (OS X/Linux/UNIX). To change the ports used by your engine, please re-run the installer.

Datatypes

↑ API • ↑ Command-Line • Datatypes • ↓ Directories • ↓ Objects • ↓ FFDL • ↓ Metadata • ↓ Queries • ↓ URIs

This table lists the backend datatypes supported by FatFractal. The unvalidated datatype may only be assigned using either the FatFractal Definition Language (FFDL) or JavaScript Serverside (JSSS).

Directory Layout

↑ API • ↑ Command-Line • ↑ Datatypes • Directories • ↓ Objects • ↓ FFDL • ↓ Metadata • ↓ Queries • ↓ URIs

Scaffolded Application

When you scaffold an application, the following directory structure is created.

Installation

When you install FatFractal on your local machine, the following directory structure is created. Depending on your installation options, not all files may be present.

FF Special Objects

↑ API • ↑ Command-Line • ↑ Datatypes • ↑ Directories • Objects • ↓ FFDL • ↓ Metadata • ↓ Queries • ↓ URIs

The FatFractal Platform supplies a few other built-in objects for particular purposes. Certain members of these special objects, as well as their datatypes, are pre-defined by the FatFractal Platform; in most cases you can add fields and subclass these objects as well.

FFUser

The FFUser object is an object, like any other, except that it has pre-defined members which are useful for managing end-users of your application. For example, FFUser objects have authentication information associated with them. Those members are:

You may use and add to the members of the FFUser object in the same way as you would to any other object in your application; however you may not remove the pre-defined members from the object definition.

The groups member is a grab bag containing all the FFUserGroup objects owned by the FFUser. The groups member starts empty, and is manipulated using methods in the client APIs.

The active member default depends on the value of ActivateUsersOnReg parameter in your application’s application.ffdl file. If ActivateUsersOnReg is true, newly created FFUser objects begin with active set to true.

System User

Every FatFractal application has a special user, with username and guid system. This user has read and write permission to everything in the application, similar to root on *nix systems. In a local deployment, you may login as system (using password system) for convenience in modifying objects in your datastore. Additionally, all serverside custom code is run as the system user.

Logged-In User

The client SDKs provide methods to retrieve the FFUser object of the currently logged-in user:

FatFractal *ff = [FatFractal main];
FFUser *loggedInUser = ff.loggedInUser;

FatFractal ff = FatFractal.getMain();
FFUser loggedInUser = ff.getLoggedInUser();

var ff = new FatFractal();
...
var loggedInUser = ff.FFUser(ff.loggedInUser());

User login and registration is always done via HTTPS for over-the-wire security. User passwords are stored as hashes using the PBKDF2 function, using SHA1-HMAC for its random number generator, and every hash is created using a unique random 128-bit salt per user.

See Managing Users and the API Reference.

FFUserGroup

The FFUserGroup is a system object for managing sets of FFUser objects. One of the primary functions of the FFUserGroup is to provide a simple way to add and remove OAPs to sets of FFUsers; see Permissions.

FFUserGroup has the following members:

See Managing Groups and the API Reference.

FFGeoLocation

The FFGeoLocation object encapsulates geolocation information across clients and facilitates geo-queries. This object is used in conjunction with the GEOLOCATION backend datatype.

FFGeoLocation has the following members:

See the API Reference.

Subclassing

You may want to extend the functionality of FF Special Objects by subclassing them. Doing so involves three steps:

1. Subclass the class you would like to extend.
2. Add any new members you’ve added to the objecttype definition of the original objecttypein your application.ffdl file.
3. Register your new class with the FatFractal library, so that it maps to your new class instead of the built-in one.

Example

Let’s say we want to subclass FFUserGroup so that it includes a new string member called notes. Here’s how we would do it:

1. Define a new class, which we will call NotesUserGroup:
   • iOS
   • Java (Android)

   @interface NotesUserGroup : FFUserGroup
   @property (strong, nonatomic) NSString *notes;
   @end
   

   public class NotesUserGroup extends FFUserGroup
   {
       private String m_notes;
   
       public String getNotes() { return m_notes; }
       public void setNotes(String notes) { m_notes = notes; }
   }
   

2. Change the FFDL definition of FFUserGroup:

   CREATE OBJECTTYPE FFUserGroup (groupName STRING, users GRABBAG /FFUser, notes STRING)
   

3. Register NotesUserGroup with the FatFractal library:
   • iOS
   • Java (Android)

   [ff registerClass:[NotesUserGroup class] forClazz:@"FFUserGroup"];
   //
   // IMPORTANT: Right now, registerClass:forClazz: will only take effect for the
   // FatFractal object on which you invoke it. This means that if you have multiple
   // 'FatFractal' objects then you would need to invoke registerClass:forClazz:
   // on each one. In the next release this behaviour will be changed so that
   // registerClass:forClazz: will take effect across all instances.
   //
   

   FFObjectMapper.registerClassNameForClazz(NoteUserGroup.class.getName(), "FFUserGroup");
   

FFDL

↑ API • ↑ Command-Line • ↑ Datatypes • ↑ Directories • ↑ Objects • FFDL • ↓ Metadata • ↓ Queries • ↓ URIs

FFDL has two principal uses on the FatFractal Platform:

1. Used in an application’s application.ffdl file, FFDL is used to set defaults for the application on startup.
2. When retrieving the backend state representation for a running application, FFDL is returned representing the current state of the application.

SET command

SET commands take the general form

SET <parameter> <value>

Options for <parameter> and associated options for <value> are given in the following tables.

Registration parameters

Learn Mode parameters

Push parameters

See Push Notifications.

Other parameters

Security parameters

CORS

The CORS parameter instructs your backend to include the Access-Control-Allow-Origin header in its responses, listing the provided origins as the value. This will allow XMLHttpRequests (XHRs) from a browser with one of the listed origins to proceed.

For example, the FatFractal Data Browser has a base URL of https://system.fatfractal.com. In order to send XHRs to your backend, your FFDL file should include:

SET CORS https://system.fatfractal.com

Note that you may provide multiple origins to the CORS parameter, separated by spaces.

CREATE command

COLLECTION

The syntax to create a collection is

CREATE COLLECTION /<collection name> [OBJECTTYPE <objecttype>[, <objecttype>, ...]]

If OBJECTTYPE is provided, then the collection may only contain objects of the listed objecttypes. Otherwise, the collection may contain objects of any objecttype.

OBJECTTYPE

The syntax to create a new objecttype is

CREATE OBJECTTYPE <objecttype name> (<member>[, <member>, ...])

Each <member> is given as follows:

<member name> [ ENCRYPTED ] <backend datatype>

ENCRYPTED applies only to the backend datatype STRING; if provided, the member is stored encrypted on your app’s backend. For the supported backend datatypes, see Backend Datatypes.

ALIAS

Aliases allow you to set up shorter names for referring to grab bags, as a convenience. The syntax to create an alias is

CREATE ALIAS ON OBJECTTYPE <objecttype name> GRABBAG <grab bag name> AS <alias>

EVENT HANDLER

The syntax to associate a CRUD event or trigger to an event handler is

CREATE [ CRUD ] HANDLER <handler name> [ PRE | POST | ASYNC ] ON /<collection name> [ Create | Update | Delete ] AS <script type>:<script text>

See Custom Code.

EXTENSION

A server extension (or API extension) is another method for triggering serverside code, which, in this case executes on HTTP GET requests to a specified URI. The syntax to associate a server extension name to its code is

CREATE EXTENSION /<extension name> [ UNSECURED ] AS <script type>:<script text>

By default, a server extension can only be triggered by a user who is logged in. The optional UNSECURED keyword allows users that are not logged in to execute the extension.

See Custom Code.

PERMIT command

The PERMIT command is used to set default OAPs for individual users and/or groups with the specified permissions on collections. These defaults may be altered in code during runtime using FatFractal’s declarative security. The syntax for the PERMIT command is

PERMIT read:<group>[,<group>,...] write:<group>[,<group>,...] ON /<collection name>

See Permissions and Managing Users.

SCHEDULE command

The SCHEDULE command is used to schedule execution of serverside code. The syntax of the SCHEDULE command is

SCHEDULE <task name> <schedule> AS <script type>:<script text>

<schedule> is given in cron syntax:

<minute (0-59)> <hour (0-23)> <day of month (1-31)> <month (1-12)> <day of week (0-6)>

Each parameter may also be the character *, indicating all.
See Custom Code.

Metadata

↑ API • ↑ Command-Line • ↑ Datatypes • ↑ Directories • ↑ Objects • ↑ FFDL • Metadata • ↓ Queries • ↓ URIs

Whenever you create an object, the FatFractal Platform returns metadata about that object. The FatFractal Platform provides a built-in datatype, FFMetaData, to encapsulate this metadata. As for all built-in types, each of the FatFractal APIs provides an FFMetaData type appropriate for the API’s platform.

For information on how to retrieve the metadata for an object using a specific API, see the API Reference.

Query Language

↑ API • ↑ Command-Line • ↑ Datatypes • ↑ Directories • ↑ Objects • ↑ FFDL • ↑ Metadata • Queries • ↓ URIs

The following table lists the query operators available on the FatFractal Platform. See Queries and Data Modeling.

NOTES:

• Operations are always performed left to right
• Parentheses will group operations as you would expect
• Single quotes are used to define a literal string, rather than double-quotes

URI Structure

↑ API • ↑ Command-Line • ↑ Datatypes • ↑ Directories • ↑ Objects • ↑ FFDL • ↑ Metadata • ↑ Queries • URIs

URLs on the FatFractal Platform are extensions of your application’s base URL:

<scheme>://<domain name>.fatfractal.com/<application name>

Or, if you are working locally:

<scheme>://localhost/<application name>

There are two groupings of allowed URLs:

<scheme>://<domain name>.fatfractal.com/<application name>/ff/resources/collection/guid

<scheme>://<domain name>.fatfractal.com/<application name>/ff/ext/extName

For information on how resources are organized on the FatFractal Platform, see Resource Hierarchy. For information on finding objects using queries and traversals, see Queries and Data Modeling, respectively.