An Introduction to Flood
Flood is the core technology that we use to create export options for Flow. By its very nature, it can be used to generate any type of document, including text files, images, audio files, source code, binary files etc.
Yes. You read that correctly… Flood can export ANY type of document.
Which means you can create or modify templates to export any kind of output file, format, style, language, project structure… you name it.
For example, using Flood we have created templates that export full Xcode projects, output for Web, as well as React Components. Each export is formatted into the proper project file structure, and includes outputs for images, fonts, styles, and so on.
Black Box Model
Flood is a general purpose templating engine. At a high level, Flood accepts a template along with a data model which it combines to produce a set of generated documents. This black box model of Flood is depicted in the image below.
Typically, Flow passes to Flood a data model that represents the layout, styles and timeline for an animation. Templates come pre-packaged with Flow, but you can also add customized templates that generate code to the exact specs you want and need for your project.
Templates
In Flood’s templating system, templates are represented by flood files. A flood file is simply a bundle which contains executable code in the form of program files along with other resources. Flood files are given the .flood file extension. The following image displays the package contents of a template named Documentation.flood.
Program Files
A program file is simply a script which is executed by the Flood template engine. These files have the .flp file extension. They typically contain instructions outlining where to create directories and files within the file system. These instructions are written in the Flood language. The image below shows the contents of a program file.
Templates Files
A template file, not to be confused with a template (i.e. a flood file), is a special type of resource file found within a flood file bundle. These files have the .flt file extension. A template file is processed by the templating engine to generate a single document – or part of a document. This process is illustrated in the following image.
One
.fltfile can call another. This makes it easy to separate them into resuable chunks of logic.
A template file consists of verbatim text interleaved with generation instructions which are enclosed within special control sequences. The contents of a template file can be seen in the image below. The text highlighted in white represents the verbatim and the text highlighted in red represent the control sequences which enclose the generation instructions.
When the templating engine processes a template file its verbatim text is copied over directly to the generated document. The instructions on the other hand are executed by Flood (much like those of a program file) to produce textual output which is inserted in lieu of the instructions within the generated document. Since the output generated by template files vary based on the data-model passed in the to Flood they are considered non-static resources.
Static Resources
A template may also contain static resources which the engine can copy over to specified locations. This is useful for generating documents whose contents are unchanging. These resources may be files of any type, including images, audio files, source code etc.
Processing Templates
To begin processing a template, Flood searches the template’s top level directory for a program file named main.flp. The execution of this special file, referred to as the main program file, is what initiates the processing of the template. As such, every template must contain exactly one main program file in its top level directory. If no such file is found, Flood crashes and throws an error stating it could not find the main program file.
Executing Program Files
Flood executes a program file in the same way an interpreter executes a script. In fact, the Flood templating engine can be thought of as an interpreter in its own right. One that has been built to interpret the Flood programming language.
Flood has built-in modules which provide the core services which program (and template) files may use to generate documents. This group of modules are referred to as Flood’s runtime library. Some of the functionalities provided by these modules include:
- Executing program files
- Processing template files
- Creating Directories
- Copying files over to new locations
- Deleting Files / Directories
Typically the main program file creates the directory structure in which to generate the documents. It is also responsible for generating the documents themselves. It does so by processing templates contained within the flood file. The main program file, like any other, may also execute other program files.
Processing Template files
The Flood module provides a process function for processing a template file. The process function is typically invoked from a program file (although there are situations in which it is useful to call process from a template file). The process function takes in the path of the template file to process along with an optional outputfile path. It returns a string resulting from processing the template file. If a non nil outputfile path is provided, the returned string is also written to the specified outputfile.
To construct this string, Flood incrementally reads through the contents of the template file. As it comsumes verbatim text it appends it to the string untill it encounters the start of generation instructions, indicated by <% (an opening tag). At this point, Flood stops printing vertbatim text and begins executing generation instructions untill it runs into %> (a closing tag).
In this manner, Flood alternates between printing verbatim text and executing generation instructions untill it reaches the end of the file.
Generation Instructions
Generation instructions are used in template files. They modify the output based on the provided data model, and do so in two ways:
- by directly inserting text into the generated document.
- by altering control flow.
A for loop can be used to repeatedly process a portion of a template file, whereas an if statement can be used to skip processing a portion of a file based on some condition. Concrete examples illustrating how generation instructions impact template file processing can be found in the Flood language guide.
Data Model
At a high level, the data model is simply structured information provided to the template engine, that is used to influence a template’s generated output. In Flood, data models are provided in the form of variables. The values of which are manipulated by the generation instructions in program and temlate files.
One way to import data models is to load a JSON file containing the required data. This can be done by invoking the loadJSON(_:) function provided by the JSON module. Another way, is by importing a module whose global variables store the required data.
Flood Modules
In Flood, modules are containers of related functionality. They can define classes, global functions and global variables. In order to use a module’s functionality, it must be imported. There are two types of modules in Flood:
- implicit modules, and
- non-implicit modules.
Implicit modules are automaticly imported within Flood, where as non-implicit modules must be manually imported.
Most of the modules in Flood’s run time library are implcit modules. These are:
The JSON module is the only non-implicit module that ships with Flow.
How Flow Uses Flood
Although you now (hopefully) have a general understanding of what Flood does and how it works, the question still remains:
What does Flood have to do with Flow?
Well, as you may already know, Flow is an animation design tool which allows you to export animations to code on a variety of different platforms. But how exactly does Flow convert your animations to all these different programming languages? The answer to that is:
Flow leverages the power of Flood’s templating system.
When you export an animation to code, Flow actually passes a data model (representing the animation) to Flood along with a template which dictates the format of the exported code. Flood then processes the template to produce a set of documents which constitute the animation code. In fact, when you are chosing between the HTML or iOS export options, you are actually selecting what template Flood will process.
Importing animation data into Flood
Flow provides its data model to Flood by implicitly importing the Flow module within Flood. Prior to each code export, the app dynamically sets the values of the Flow’s global variables based on the latest animation infomration contained in the flow document.