FileMaker-side CWP scripts

posted by Jeremiah Small Monday, July 31, 2006

Q: Given a file with just base table references can I use the script and go to a layout in the script and create the records.

A: Sure. No problem, although Having relationships between your FileMaker TOs gives you lots of additinal options. What might help in terms of visualizing what you can do is to remember that you are always acting on layouts in virtual windows from CWP. You still have a found set and multiple windows! (nice.) Check the web compatibility bit in ScriptMaker and you will see that the “New Window” step turns into “New Window (VIRTUAL WINDOW ON WEB)” when used in a script.

One trick I use commonly to preserve a session record context with CWP is I use a CWP find to isolate my base record, and then run a FileMaker script on that record (as needed, invoking new virtual windows to create processing sets i.e line items or what have you). This can make your PHP scripting pretty simple, and really helps performance, because all the scripting becomes FileMaker side. That is to say, if you need to loop over a found set or what have you, controlling that from PHP would be very inefficient, as each iteration of the loop would require a new database transaction. If the loop is created as a FileMaker script, you simply have to find or create your base record, and then call the FileMaker script as a follow-on.

So for example a generic find function using the filemaker.php (assumes you have defined some named constants):
function findRecord($LayoutName,$CriterionArray,$scriptName="")

$findReq =& $fm->newFindCommand($LayoutName);

foreach($CriterionArray as $k=>$v)
$findReq->addFindCriterion($k,"==" . $v);


$result = $findReq->execute();

return $result;
With this function, you can establish a found record and call a
FileMaker-side processing script that may look something like this in a
simple case:
If [ not IsEmpty ( app_RNK__RankJoin::_kf_applicantID ) ]
Go to Related Record [ From table: “app_RNK__RankJoin”; Using layout:
“web_rank” (RNK__RankJoin) ]
[ Show only related records ]
Go to Record/Request/Page
[ First ]
If [ GetAsNumber ( RNK__RankJoin::applicantChoice ) = "" ]
Set Field [ RNK__RankJoin::applicantChoice; "NA" ]
Omit Record
Exit Loop If [ Get ( FoundCount ) < 1 ]
Go to Record/Request/Page
[ Next; Exit after last ]
End If
End Loop
Sort Records [ Specified Sort Order: RNK__RankJoin::applicantChoice; ascending
rnk_SCH_Schools::schoolName; ascending ]
[ Restore; No dialog ]
Replace Field Contents [ RNK__RankJoin::applicantChoice; Replace with
serial numbers: Custom values; Initial value: 1; Increment value: 1 ]
[ No dialog ]
End If
Go to Layout [ original layout ]
In a more complicated case, you might use virtual windows for subroutines:
#  Check for non-unique account name.
Close Window [ Name: "temp"; Current file ]
New Window (VIRTUAL WINDOW ON WEB) [ Name: "temp" ]
Set Error Capture [ On ]
Enter Find Mode [ ]
Set Field [ APP__Applicants::_ka_username; $username ]
New Record/Request
Omit Record
Set Field [ APP__Applicants::__kp_applicantID; $appID ]
Perform Find [ ]
Set Error Capture [ Off ]
If [ Get ( FoundCount ) > 0 ]
Close Window [ Name: "temp"; Current file ]
Set Field [ APP__Applicants::scriptResult; $result ]
Exit Script [ Result: $result ]
Close Window [ Name: "temp"; Current file ]
End If


Post a Comment

So... the FileMaker API for PHP public beta

posted by Jeremiah Small Monday, July 31, 2006

First off, the official name, "FileMaker API for PHP" has a real snappy ring to it. I'm sure that will really catch on (not). When in official capacity (i.e. onstage at Devcon) I will have to use the sanctioned official name, so I have been practicing the discipline of not abbreviating it or nicknaming it. Chris Hansen (half?) jokingly has called it FAP. I call it filemaker.php or fmphp in my code comments. It's pretty convenient for everyone that the other two established third party FileMaker API classes for PHP called themselves the cool and streamline name, "FX.php" and the charmingly cumbersome name, "FMandPHP". This leaves no conflict for fmphp or filemaker.php, so I suspect one or both of those will become the de facto nicknames for the official class.

So what about this new kid on the block? If you already have a test server with PHP on it, you can just grab the "Bundle" with the class, examples and docs here:

FWIW, the package installers do a really nice job of installing PHP 5.12 with no hassle, so if you have been using the default 4x build that came with your Mac, don't hesitate to upgrade with the package installer. The filemaker.php class is compatible with PHP 4x as advertised, but the bundled example php files contain some 5x only functions, making it kind of pointless to try learning with the examples on a 4x install.

Once you have the bundle open, Look for a directory called “apidoc” in the main bundle directory. This has an index file for the html documentation. Tip for those using the package installer. Grab a separate copy of the bundle too. This contains all the portable stuff, including the docs, and examples.

To see what all the l33t haxors are saying, check out these discussions:

The FMI sponsored web forum for filemaker.php.

Check out FMForums

and is dedicated to the subject

If anyone finds more must-see-TV about PHP-for-FileMaker-developers or FileMaker-for-PHP-developers, please do post it.

Okay, so now you have it downloaded and installed... what next?

Being a self-taught “functional” programmer, the object oriented nature of filemaker.php isn’t immediately intuitive for me. If you're anything like me, I suggest you get a dedicated sandbox machine to load a copy of FMSA (subscribing to FSA is by far the cheapest way to get a developer license) and PHP. Your sandbox could be an old PC or a virtual machine. Whatever you choose, get the sample files up and running, then just start goofing around and breaking stuff. A sandbox is the key, because that way you can dump all your hacked up junk periodically and unpack a clean copy of the original bundle. Or if worst comes to worst, you can nuke and pave the whole machine. I find examples to be most useful in seeing how to employ the API. I am working on a full featured example for my Devcon session. Feel free to poke around in my hosted copy of it, but be warned that it is unreleasedeased and under active development. It still needs a few little UI niceties, like a continue link on the success messages and whatnot, or at times might be broken or unavailable altogether (hey, it's in a sandbox). All FileMaker communication is 100% filemaker.php; no FX.php or FMandPHP cheats here ;) Comments welcome.

Side note: I have been saying this for a "long time", and I would still like to see the documentation include a the list of valid properties for a FileMaker object inline with the documentation for setProperty() and getProperty() methods. For now we can work a little harder and see it, but such a list can be built...

(from the documentation, such that it is...)

Get an associative array of property name => property value for all current properties and the values currently in effect. This allows introspection and debugging when necessary.

return: All current properties.

array getProperties ()

Set $prop to a new value for all API calls.

void setProperty (string $prop, string $value)
string $prop: The name of the property
string $value: Its new value.

Returns the currently set value of $prop.

return: The property's current value.
string getProperty (string $prop)
string $prop: The name of the property.
So if we write a little script like this:


// require the filemaker.php class
require_once "./lib/fmphp/FileMaker.php";

// create filemaker.php object
$fm = new FileMaker("FMServer_Sample","localhost","Admin","");

// set an array with the properties of our new $fm object
$properties = $fm->getProperties();

// echo the contents of the $properties array using the preformatted
print_r() function

echo '<pre>';
echo '</pre>';


We get an array like this
[charset] => utf-8
[locale] => en
[logLevel] => 3
[hostspec] => localhost
[recordClass] => FileMaker_Record
[prevalidate] =>
[database] => FMServer_Sample
[username] => Admin
[password] =>
...but still. Why should we have to work for this? At least they put the username and password back in as arguments to the main class, so there is no longer a need to set those properties if you want to operate on the database with anything other than the values set in config/filemaker-api.php :s

The bummer is, where are the properties like
[debug] => true
[commandurl] => http://Admin:admin@localhost:80/fmi/xml/FMPXMLRESULT.xml?

...well it's a beta, and we have to have something to dream about. It's the FileMaker way :)


Post a Comment