Dive Into Fluid
This is a collection of examples and tutorials for the Fluid templating library.
Fluid is a C# implementation of Liquid, which was originally written by Shopify. There are multiple implementations for Liquid in different languages.
Most Liquid syntax works in Fluid. If something isn’t in this guide, but you can find it in other Liquid documentation, there’s a non-trivial chance it will work in Fluid.
I have tried to be clear about “Liquid” vs. “Fluid.” If something is specified as “Liquid,” then it will likely work in all implementations of the language. Something referenced as “Fluid” is just for this implementation.
I assumed no prior Liquid knowledge or functionality for this guide. For the code here, I pretended there was no Liquid doc; that Fluid was an original, standalone library; and I tested everything in “pure” Fluid (2.2.6, as of this writing)
No matter what the original Liquid doc says, what’s in this guide is gospel for Fluid. All code samples were executed in Fluid.
Also note that this is a guide mainly for C# developers. If you work with Liquid at the templating level, there’s a lot here for you as well, but this guide will dig down into the code under the implementation.
– Deane
- Introduction: The Four Levels of Fluid Development
An guide to the different ways you might develop with Fluid
- Basic Template Execution
How to parse and execute a template
- Definitions
Some basic definitions of Liquid and Fluid terms
- Filters
How to modify or format data when it’s output
- Conditionals and Operators
How to implement logic by comparing values
- Looping
How to loop over collections of objects
- Arrays
How to access arrays and dictionaries
- Passing Data into Templates
How to pass data into templates and how templates locate that data
- Member Access and Controlling Template Data
How data can be restricted in the model
- Fluid Values
How to create custom values and behaviors to use in your templates
- Value Convertors
How values are converted to be used in templates
- Value Resolution
How templates locate values when encountering template tokens
- Virtual Members Using GetValue
How to create custom members on values
- Custom Filters
How to write your own filters to custom format data
- Variable Assignment
How variables are assigned inside templates and what you can do with them
- Checking for Values: True and Falsey
How to determine is a variable is available to a template
- Including Other Templates
How to re-use templates by including one into another
- Whitespace Control
How to control the whitespace left over when tags execute
- Custom Tags and Blocks
How to create custom language constructs to extend Fluid
- Custom Parser Tags and Blocks
How to reconfigure the parser to detect and execute custom constructs
- Troubleshooting: No Output
What to look at if you’re not getting output
Chapters still to be written:
- Layouts and MVC Integration
- Performance
Built-In Filter References
I originally stubbed out the following pages by reflecting the static classes in the Fluid.Filters namespace (v.2.2.7). All the filters below are automatically available in the default Fluid implementation, with the exception of the color filters (they exist, but they need to be enabled).
As noted above, there is a lot of carryover from Liquid to Fluid, especially around filters. In fact, most filters were specifically tested against the original Liquid implementations, and some even had quirks built into them so they would behave the same and result in compatible, portable templates.
Remember, if you don’t find a filter you want, and you can develop in C#, writing your own filters is quite easy.