Property List

Intro

Property List is a data serialization technique for use in FileMaker solutions. Since FileMaker doesn’t currently provide a native structured data type for variables, developers use various techniques to pack or serialize data. The most common use case is when you need to send more than one parameter to a script. However, the same technique can be used when exchanging data with web services, WAN PSOS calls, script stack results, or in database blobs.

Inspired by the serialization technique of JSON, PHP serialize(), and other FileMaker developers, I started developing this technique in 2007.  Specific goals of the project included simple and lightweight syntax, good performance, and scalable support for any number of nested hierarchies. Other developers brought further enhancements with performance tuning. Later we used transforms to native PHP objects to support interoperation with the wide variety of web services that already provide PHP APIs.

The extensive use of Property List for script parameters and script results at Dr. Bott LLC was is a building block for the Procedural Programming approach described in Idiomatic FileMaker.

Download

You can download the latest file here: property-list-current.zip Last updated October 6th, 2015.

The property list functions were open sourced in 2013 with a MIT license. Feel free to send us feedback and contributions that might be suitable for integration into the package.

Getting Started

Structure

first=Juan
last=Pérez
age=21
about=This placeholder¶name is used¶regularly.
formula=1+1=2

A Property List is an extension of the Value List string. Every property is separated by a line break, just like values in a value list. The property is defined by a key, a separator ‘=’, and then a value. The value is terminated by the line break. Keys can be any set of characters except for line break or ‘=’. The the value may contain ‘=’ characters, but line breaks must be escaped. Values may also be empty. Escaping line breaks can be a little tricky, so use the #() function to assemble your properties.

Assembling Property Lists

A property list might only have a single property in it.

Set Variable [ $first_pl ; Value: "message=Hello World!" ]

When you have opaque or user entered data, use the # ( ) function to handle encoding and escaping.

Set Variable [ $second_pl ; Value # ( "customer_note" ; Order::CustomerNote ) ]

When you are ready to handle multiple properties in a list, use FileMakers List() function to put them together.

List (
    # ( "message" ; "Hello World!" ) ;
    # ( "customer_note" ; Order::CustomerNote ) ;
    # ( "verbose" ; True ) ;
    # ( "power_factor" ; 7 ) ;
)

Put additional items together by using List(), store value lists or even property lists as values.

List (
    $old_list ;    // append to an existing property list
    # ( "new_item" ; $foo ) ;
    # ( "messages" ; $first_pl ) ;    // nest another property list by allowing #() to escape it as a value
    # ( "fruit" ; List ( "Apple" ; "Banana" ; "Orange" ) ) ;
    # ( "details" ; List (    // feel free to declare nested property lists inline
        # ( "user_id" ; Order::UserID ) ;
        # ( "history_count" ; 2 ) ;
        # ( 1 ; "Oldest history text" ) ;  // you may use numbers as keys, or mix
        # ( 2 ; "Newer history text" ) ;
    ) ;
)

Reading Property Lists

Reading a value from a simple property list with key. Results returned are ALWAYS text. If a key isn’t found, it returns empty.

#Get ( "1=foo¶2=bar" ; 1 ) // returns: foo
#Get ( "1=foo¶2=bar" ; 3 ) // returns empty/null

Read nested structures by drilling down

GetAsNumber ( #Get ( #Get ( $struct ; "details" ) ; history_count ) )	// returns: 2
GetValue ( #Get ( $struct ; "fruit" ) ; 2 )			// returns: "Banana"

Always cast non-text data types back into the type you need. This is especially important if you are going to compare a number extracted from a property list with another number field or variable.

GetAsBoolean ( #Get ( $struct ; "is_verbose" ) )

Since Property Lists are delimited with line breaks, you can count the number of elements in the top tier.

ValueCount ( $struct )

Requirements

Property List functions are implemented as custom functions. This means, once installed, they can work on any of the FileMaker platforms including FileMaker Go on iOS or on the server (PSoS, CWP, WebDirect, Scheduled). These functions could have been implemented as scripts, but because they are typically used throughout a solution’s code, they are most convenient as custom functions.

Performance

One design strength of Property List is it’s lean markup. Because of this, rich data can be encoded without adding very much size. If storage or bandwidth is a premium for you, such as cellular data between a client and server, then Property List would be an excellent choice for use.

Over the years, the functions have been optimized for maximum run-time performance. We’re comfortable with the current level of performance. If you have a special big-data situation, I’d recommend looking at variable repetitions, using the database, or unloading heavy work to a plug-in installed at a client, robot, or the server.

Chris Irvine recently completed a performance survey of several popular options. Compare the results when you are trying to pick a N-V-P platform to standardize on.

Security

Nowhere in the Property List functions do we call Evaluate(). Using these functions will not expose you to FileMaker Expression Injection attacks. However, once you have retrieved a value using #Get(), we recommend you validate and coerce to the proper data type. Even if the data being provided comes from your own code, defensive programing is a good way to detect bugs and avoid the nasty.

Be aware that FileMaker 12 and later allows local variable to be pre-set when initializing a script via the URL protocol. Be sure to explicitly initialize every variable you use. If you do allow data to be provided this way, validate it.

People

Contributors

  • Chris Irvine
  • Perren Smith
  • James Sturm

Special Thanks

  • Jeremy Bante
  • Dan Smith

About the Author

Chris Irvine is a Senior Technology Consultant at Threeprong.com LLC, certified in FileMaker 12 and 13. Threeprong provides process efficiency consulting, custom development on multiple platforms, FileMaker performance scaling, and IT solutions for businesses across many industries.