5.2 XML Request Commands for Web Companion
5.2 XML Request Commands for Web Companion
A request is sent to FileMaker and Web Companion from the browser as an HTTP request. HTTP has many methods for a request. Post and get are the most common and the get method of a hyperlink is used in this section. The post method is more common with form submission and will be discussed in section 6.5, "Using the Form Element to Make HTTP Requests." A request made to Web Companion must be formatted as other HTTP requests. The location of the server may be included in a hyperlink, followed by a port number (if any) and the location of the CGI. The initial query is to Web Companion itself. It asks the web server to find the CGI with "fmpro?". All other information after the question mark (?) is the request commands processed by the Web Companion CGI. Each additional piece of the request is separated with the ampersand character (&) and name-value pairs or other CGI commands. These calls to Web Companion are shown here:
fmpro? fmpro?doThis&doThat&anotherRequest&action
You should remember that the request must be URL-encoded (ready for HTTP request). If you have any database names or layout names with spaces, for example, they must be converted or they may cause errors. The space character may be changed to "+" or "%20." You can use the External("Web-ToHTTP", parameter) function in a script or calculation to make the conversion for you. An example script step is included:
Set Field [ myfilename, [External("Web-ToHTTP", Status(CurrentFileName) ]
5.21 Database and Layout
A request is placed to a specific database and layout. Example requests are shown in Listing 5.1. When you make a web request for a layout, FileMaker Pro navigates to an open file and to a particular layout, as with a Go to Layout[] Script step. Any fields residing on the named layout in that database are accessible to the request. FileMaker Pro does not need to physically open the layout but has access to just those fields. The command for specifying the correct database is the parameter -db, and the command for layout is the parameter-lay.
 |
-db=Xtests.fp5 -lay=web -db=Xtests.fp5&-lay=web fmpro?-db=Xtests.fp5&-lay=web& ...
|
Naming Suggestions
Web Companion will produce well-formed and valid XML from your database. Well-formed XML does not like spaces in element names. Web Companion will convert these to an underscore (_). If your database is named Invoice Items.FP5, it will be converted to Invoice_ Items.FP5. The same will apply to layout names, field names, script names, value list names, and relationship names. The FileMaker Pro Help topic, "Designing cross-platform databases", suggests that filenames should not contain these characters: quotation mark ("), slash (/), backslash (<), colon (:), asterisk (∗), question mark (?), greater than or less than (> or <), or vertical bar, also called a pipe character (|). XML uses greater than, less than, and slash symbols (>, < and /) for tags, so these should not be used in any names in your database.
5.22 Actions
Every request needs an action to be fulfilled by Web Companion. These perform the equivalent of menu commands or script steps in FileMaker Pro databases. Common actions on the web or in the database are Create a New Record, Find a Record, Edit a Record, and Delete a Record. Privileges for any of these actions depend upon the permission set for them in the Password dialog of the database or through the Web Security files.
"Name=value" pairs are often appended to the request to create and edit records or used as search criteria to find a record. The name is the name of the field in the database, and the value is whatever will appear in the field upon action completion. At least one name=value is required for a new or edit action. In addition, deleting or editing a record requires a special parameter, -recid (RecordID), to verify that the action is performed upon the correct record. The following are some examples:
firstname=Joe&lastname=Brown&-recid=5846 company=Procter+&+Gamble&date=03/05/97
Create New Records
-new—This creates a new record in the database. Any fields specified in the request are populated and your defined auto-enter fields are triggered. The RecordID (-recid) and any field data are returned by this action and can be used in the next action. Equivalent to the New Record/Request script step or menu command, it creates the new record and places all your named fields with the values supplied in the request. The result is a well-formed and valid XML document containing the fields on the layout, the contents, and the RecordID. If you do not specify a -format, no record will be created and you may get a browser error.
|
fmpro?-db=Xtests.fp5&firstname=Joe&lastname=Brown&-new
fmpro?-db=Xtests.fp5&-lay=web&firstname=Joe&lastname=Brown&-format=
-dso_xml&-new
<?xml version="1.0" encoding="UTF-8" ?>
<FMPDSORESULT xmlns="http://www.filemaker.com/fmpdsoresult">
<ERRORCODE>0</ERRORCODE>
<DATABASE>Xtests.fp5</DATABASE>
<LAYOUT>web</LAYOUT>
<ROW MODID="1" RECORDID="36488">
<firstname>Joe</firstname>
<lastname>Brown</lastname>
<RecordID>36488</RecordID>
</ROW>
</FMPDSORESULT>
|
It is important to note that the fields on the layout are what drives the response from WC. If you add or delete fields to the layout or change layouts, you can get different records back from FileMaker. As an exercise, duplicate the layout "web", name it "dweb", change the fields that appear on it, and then modify your request to call dweb instead of web. For extra credit, change the format parameter to use the fmpxmlresult DTD. (Hint: It's called fmp_xml.)
Duplicate Records
-dup—Duplicating a record is similar to creating a new record. A new RecordID is created for this record and auto-enter fields are populated, but all other data is copied from the specified record you are duplicating. Supply a -recid for the record you want to duplicate. The results returned will be for the new record. If you supply field values, these will not be entered into the new record. Duplicate creates the new record with the same data but changes the internal RecordID. Use this step to return a new record, which may be edited.
fmpro?-db=Xtests.fp5&-lay=web&-recid=234&-format=-dso_xml&-dup
Edit Records
-edit—Requires the parameter -recid to know which record to update. You can get the -recid from a -new or -find. Just like -new, any fields specified in the request are updated. All other fields retain their original data. Any field that would auto-enter upon modification will do so unless you supply a value. A sample request to edit is shown in Listing 5.3. There is no specific equivalent in the database, as any record is updated by entering new information in any field and exiting the record. The XML returned by this action is the record designated by the -recid, with all the fields on the specified layout. Like the -new action, this returned record can be used in the next action.
|
fmpro?-db=Xtests.FP5&-lay=web&-format=-dso_xml&firstname=Jane&lastname=
Doe&-recid=36488&-edit
<?xml version="1.0" encoding="UTF-8" ?>
<FMPDSORESULT xmlns="http://www.filemaker.com/fmpdsoresult">
<ERRORCODE>0</ERRORCODE>
<DATABASE>Xtests.fp5</DATABASE>
<LAYOUT>web</LAYOUT>
<ROW MODID="2" RECORDID="36488">
<firstname>Jane</firstname>
<lastname>Doe</lastname>
<RecordID>36488</RecordID>
</ROW>
</FMPDSORESULT>
|
Delete Records
-delete—Requires the parameter -recid to delete the correct record. This is equivalent to the Delete Record script step or menu command. Listing 5.4 shows some -delete requests. If you do not specify a layout in this request, you will get all the field data back from the default layout. XML is not returned with this action, and the record is removed from the database. Perform another action after -delete to return to the record or records needed. If you specify a layout, you will get back the current record as it was before deleting with only those fields on that layout. Consider this distinction and the possibilities. You could save the record even as you delete it. This may be advantageous if you need to log the delete action or provide a "rollback" if the transaction should not be completed.
|
fmpro?-db=Xtests.fp5&-format=-dso_xml&-recid=36488&-delete
fmpro?-db=Xtests.fp5&-format=-dso_xml&-lay=web&-recid=36488&-delete
<?xml version="1.0" encoding="UTF-8" ?>
<FMPDSORESULT xmlns="http://www.filemaker.com/fmpdsoresult">
<ERRORCODE>0</ERRORCODE>
<DATABASE>Xtests.fp5</DATABASE>
<LAYOUT>web</LAYOUT>
<ROW MODID="2" RECORDID="36486">
<firstname>Jane</firstname>
<lastname>Doe</lastname>
<RecordID>36486</RecordID>
</ROW>
</FMPDSORESULT>
|
Find Records
-find—Like the database, you place the search criteria into appropriate fields. This is accomplished through Web Companion by appending name=value pairs to the request or using the -recid. The internal record ID is returned along with any found records and can be used for subsequent actions. The attribute <RECORDID> is in every <ROW> element regardless of the action. The -find action performs the combined script steps as Enter Find Mode[], Set Field [name, value], and Perform Find [].
You can also find all records by using -findall. This action does not require any name=value pairs or record IDs. It simply returns all records in the named database and is equivalent to Show All Records.
Another option is -findany. It will randomly return a record from the current database. While this does not have a direct command or single script step equivalent, random records could be used to supply a parameter result, such as a dynamic picture for a catalog "special."
These find requests return the results depending on the type of request and the number of records that match the criteria. -find with the parameter -recid or the -findany request will return only one record (or none). If no records are found, you get an error code of 401 just as you would in the database. Listing 5.5 shows some example find requests and example results of requests.
|
<!-- requests -->
fmpro?-db=Xtests.fp5&-lay=web&-recid=36488&-find
fmpro?-db=people.fp5&-lay=web&-findall
fmpro?-db=Xtests.fp5&-lay=web&firstname=Joe&lastname=Brown&-find
fmpro?-db=Xtests.fp5&-lay=web&-findany
<!-- nothing found (ERROR= 401) result -->
<?xml version="1.0" encoding="UTF-8" ?>
<FMPDSORESULT xmlns="http://www.filemaker.com/fmpdsoresult">
<ERRORCODE>401</ERRORCODE>
<DATABASE>Xtests.fp5</DATABASE>
<LAYOUT>web</LAYOUT>
</FMPDSORESULT>
<!-- all records returned -->
<?xml version="1.0"?>
<FMPDSORESULT xmlns="http://www.filemaker.com/fmpdsoresult">
<ERRORCODE>0</ERRORCODE>
<DATABASE>people.fp5</DATABASE>
<LAYOUT>cgi</LAYOUT>
<ROW MODID="3" RECORDID="1">
<Name>Dave Samud</Name>
<Title>Web Administrator</Title>
<Phone>555 555-1212</Phone>
<Picture>FMPro?-DB=people.fp5&-RecID=1&
Picture=&-Img</Picture>
</ROW>
<ROW MODID="1" RECORDID="2">
<Name>Robert Siwel</Name>
<Title>Web Designer</Title>
<Phone>555 555-1212</Phone>
<Picture>FMPro?-DB=people.fp5&-RecID=2&
Picture=&-Img</Picture>
</ROW>
</FMPDSORESULT>
|
The following actions are for accessing other information about or controlling your database other than record and field contents. All data is returned in well-formed and valid XML and could be used with your stylesheets or as a report of the database information.
Layout Request
-view—This command is used by Web Companion and the -format parameter to return the layout information. An example request for layout information is shown in Listing 5.6. You can use this layout information to format your results. For example, if the database and layout has a field formatted as a check box, this is returned in the request using -view. -db, -lay, and -format are required with this action.
|
fmpro?-db=Xtests.fp5&-lay=web&-format=-fmp_xml&-view
<?xml version="1.0" encoding="UTF-8" ?>
<FMPXMLLAYOUT xmlns="http://www.filemaker.com/fmpxmllayout">
<ERRORCODE>0</ERRORCODE>
<PRODUCT BUILD="5/4/2002" NAME="FileMaker Pro Web Companion"
VERSION="6.0v1" />
<LAYOUT DATABASE="xtests.fp5" NAME="web">
<FIELD NAME="firstname">
<STYLE TYPE="EDITTEXT" VALUELIST="" />
</FIELD>
<FIELD NAME="lastname">
<STYLE TYPE="EDITTEXT" VALUELIST="" />
</FIELD>
<FIELD NAME="RecordID">
<STYLE TYPE="EDITTEXT" VALUELIST="" />
</FIELD>
</LAYOUT>
<VALUELISTS />
</FMPXMLLAYOUT>
|
Database Names Request
-dbnames—To return a list of all open databases with Web Companion enabled, use this command. Listing 5.7 shows the results of the request for the open databases. This is equivalent to the design function request DatabaseNames, but only databases shared by Web Companion are returned in this XML list. The parameter -format is required with this action. The XML data returned gives you a lot of information about the open databases.
|
fmpro?-format=-fmp_xml&-dbnames
<?xml version="1.0" encoding="UTF-8" ?>
<FMPXMLRESULT xmlns="http://www.filemaker.com/fmpxmlresult">
<ERRORCODE>0</ERRORCODE>
<PRODUCT BUILD="5/4/2002" NAME="FileMaker Pro Web Companion" VERSION=
"6.0v1" />
<DATABASE DATEFORMAT="" LAYOUT="" NAME="DBNAMES" RECORDS="1"
TIMEFORMAT="" />
<METADATA>
<FIELD EMPTYOK="NO" MAXREPEAT="1" NAME="DATABASE_NAME" TYPE="TEXT" />
</METADATA>
<RESULTSET FOUND="1">
<ROW MODID="0" RECORDID="0">
<COL><DATA>Xtests.FP5</DATA>
</COL>
</ROW>
</RESULTSET>
</FMPXMLRESULT>
|
Layout Names Request
-layoutnames—When you specify a particular database in this request, all the layouts for that database are returned. This is equivalent to the design function LayoutNames (dbname). The database name and -format needs to be specified with this action. Listing 5.8 shows the XML returned by a request for the layout name in the Xtests database.
|
fmpro?-db=Xtests.fp5&-format=-fmp_xml&-layoutnames
<?xml version="1.0" encoding="UTF-8" ?>
<FMPXMLRESULT xmlns="http://www.filemaker.com/fmpxmlresult">
<ERRORCODE>0</ERRORCODE>
<PRODUCT BUILD="5/4/2002" NAME="FileMaker Pro Web Companion" VERSION=
"6.0v1" />
<DATABASE DATEFORMAT="M/d/yyyy" LAYOUT="" NAME="xtests.fp5" RECORDS="23"
TIMEFORMAT="h:mm:ss a" />
<METADATA>
<FIELD EMPTYOK="NO" MAXREPEAT="1" NAME="LAYOUT_NAME" TYPE="TEXT" />
</METADATA>
<RESULTSET FOUND="23">
<ROW MODID="0" RECORDID="0">
<COL>
<DATA>About</DATA>
</COL>
</ROW>
<ROW MODID="0" RECORDID="0">
<COL>
<DATA>Form View</DATA>
</COL>
</ROW>
<ROW MODID="0" RECORDID="0">
<COL>
<DATA>web</DATA>
</COL>
</ROW>
<ROW MODID="0" RECORDID="0">
<COL>
<DATA>webForm</DATA>
</COL>
</ROW>
<ROW MODID="0" RECORDID="0">
<COL>
<DATA>webList</DATA>
</COL>
</ROW>
</RESULTSET>
</FMPXMLRESULT>
|
Script Names Request
-scriptnames—Equivalent to the design function ScriptNames (dbname), this command will return the list of all the scripts in the named database. Listing 5.9 shows that only the database name, result format, and the action need to be specified in this request.
|
fmpro?-db=Xtests.fp5&-format=-fmp_xml&-scriptnames
<?xml version="1.0" encoding="UTF-8" ?>
<FMPXMLRESULT xmlns="http://www.filemaker.com/fmpxmlresult">
<ERRORCODE>0</ERRORCODE>
<PRODUCT BUILD="5/4/2002" NAME="FileMaker Pro Web Companion" VERSION=
"6.0v1" />
<DATABASE DATEFORMAT="" LAYOUT="" NAME="SCRIPTNAMES" RECORDS="48"
TIMEFORMAT="" />
<METADATA>
<FIELD EMPTYOK="NO" MAXREPEAT="1" NAME="SCRIPT_NAME" TYPE="TEXT" />
</METADATA>
<RESULTSET FOUND="48">
<ROW MODID="0" RECORDID="0">
<COL>
<DATA>New Request</DATA>
</COL>
</ROW>
<ROW MODID="0" RECORDID="0">
<COL>
<DATA>openURL</DATA>
</COL>
</ROW>
<ROW MODID="0" RECORDID="0">
<COL>
<DATA>Edit Request</DATA>
</COL>
</ROW>
<ROW MODID="0" RECORDID="0">
<COL>
<DATA>Delete Request</DATA>
</COL>
</ROW>
<ROW MODID="0" RECORDID="0">
<COL>
<DATA>Find Request by ID</DATA>
</COL>
</ROW>
<ROW MODID="0" RECORDID="0">
<COL>
<DATA>Find Request by Field</DATA>
</COL>
</ROW>
</RESULTSET>
</FMPXMLRESULT>
|
Open or Close Databases Command
-dbopen and -dbclose—These two commands are used to control which databases are available to the web users. Any file opened or closed by these commands must reside in the Web folder of the FileMaker Pro folder and have the Web Companion enabled. Specify Remote Administration in the Web Companion Configuration dialog for FileMaker Pro. The parameter -password is optional but advisable for remote administration. These two commands are shown below:
fmpro?-db=Xtests.fp5&-format=-fmp_xml&-dbopen fmpro?-db=Xtests.fp5&-format=-dso_xml&password=master&-dbopen fmpro?-db=Xtests.fp5&-format=-fmp_xml&-dbclose
| Warning |
Placing any file in the Web folder may have security implications. If you must use this feature, provide a password for your database. Do not enable the Try default password option in the Edit, Preferences, Document Preferences dialog. |
Request for Image in a Container Field
-img—This command is used specifically with images placed in a container field in the database. FileMaker Pro will produce a link pattern to the image and provide the -img action for you. Images may be in a container field or stored with a field referencing the path to the images. The -img action is used only with stored images.
The XML created for the container field Picture is shown in the following code. Using this information and one of the stylesheet methods, you can web publish the container field to a web page. The text created has to be converted to HTML encoding, so that the "&" shows as "&", but the character is converted back if this field is used as a link to display the graphic.
<Picture>FMPro?-DB=people.fp5&-RecID=1&Picture=&-Img</Picture> <Picture>FMPro?-DB=people.fp5&-RecID=2&Picture=&-Img</Picture>
Actions are used singly and not together. One action at a time can be performed. Careful design may be needed to produce desired results from web-published FileMaker Pro and XML. Actions equate to simple steps on the databases themselves. Using scripts we can perform multiple steps, but these may not be appealing for the web-published data. Using these actions, you can manipulate the information in your database through a web page interface. The actions rarely perform alone and require different parameters to act upon.
5.23 Parameters
Parameters are similar to actions because they begin with the "-" sign. However, they use the name=value notation, requiring a value. These parameters could also be called variables. The value of the parameter depends on how it is used. The first two parameters, -db and -lay, have already been discussed.
Database Parameter
-db—This parameter is required by all actions except -dbnames. The full name of the database file (including extension) needs to be provided. Case may or may not matter, so use the exact name of the file. You can determine the current database name with the function Status(CurrentFileName). You can also use the Design functions to determine all open database names. If the -db is not set up for sharing with Web Companion, you will get results with the error number 973. See section 5.5, "Error Codes for XML", for more errors you may get with XML publishing.
Layout Parameter
-lay—The layout name is optional with -find, -findall, and -findany but required to return the list of fields when used with the -view action. -lay also is required for -edit and -new requests if you need to access related fields.
A default layout named "Layout 0" (zero) is similar to the Define Fields dialog. It contains all the fields in the current database and will be used if no layout is specified. To use related data, you must specify the layout where these related fields are displayed or create calculated fields based on the relationship. On the layout, you can place related fields in or out of a portal. Single related fields are treated as if they were the first record in the related file. For all the related records, a portal should be displayed on the layout with those fields required by the request.
XML Format Parameter
-format—When using Web Companion and CDML, -format is used to designate a particular HTML-formatted page used to display the results of the HTTP request. New in FileMaker Pro, this parameter is used to specify which well-formed and valid XML document to return. How it is used depends upon the results you want. There are four format types, and they are combined with the actions to return five different types of XML: FMPDSORESULT, FMPDSORESULT with DTD, FMPXMLRESULT, with DTD, FMPXMLRESULT, and FMPXMLLAYOUT. The DTD formats were discussed more fully in Chapter 4.
-dso_xml is used to return the field names as the tag names and is the easiest to work with for specific data reading and writing:
<fieldname>field contents</fieldname>. The root of the XML document is <FMPDSORESULT></FMPDSORESULT>. DSO is the acronym for Data Source Object. A sample request to FileMaker Pro is shown in Listing 5.10. -dso_xml differs from -fmp_xml by using the field names as the names of the element tags.
|
fmpro?-db=Xtests.FP5&-lay=web&-format=-dso_xml&-recid=36489&-find
<?xml version="1.0" encoding="UTF-8" ?>
<FMPDSORESULT xmlns="http://www.filemaker.com/fmpdsoresult">
<ERRORCODE>0</ERRORCODE>
<DATABASE>xtests.fp5</DATABASE>
<LAYOUT>web</LAYOUT>
<ROW MODID="0" RECORDID="36489">
<firstname>Sue</firstname>
<lastname>Smythe</lastname>
</ROW>
</FMPDSORESULT>
|
-fmp_xml is more generic and perhaps allows greater flexibility for formatting the results. The root element of the XML results returned is <FMPXMLRESULT></FMPXMLRESULT>. The field names are returned near the beginning of the document and found in the element <METADATA></METADATA>. By including the METADATA, some of the layout information for each field is also returned. Listing 5.11 shows a request for the data in Xtest.fp5 with fmp_xml results.
|
fmpro?-db=Xtests.FP5&-lay=web&-format=-fmp_xml&-recid=36489&-find
<?xml version="1.0" encoding="UTF-8" ?>
<FMPXMLRESULT xmlns="http://www.filemaker.com/fmpxmlresult">
<ERRORCODE>0</ERRORCODE>
<PRODUCT BUILD="5/4/2002" NAME="FileMaker Pro Web Companion" VERSION=
"6.0v1" />
<DATABASE DATEFORMAT="M/d/yyyy" LAYOUT="web" NAME="xtests.fp5" RECORDS="4"
TIMEFORMAT="h:mm:ss a" />
<METADATA>
<FIELD EMPTYOK="YES" MAXREPEAT="1" NAME="firstname" TYPE="TEXT" />
<FIELD EMPTYOK="YES" MAXREPEAT="1" NAME="lastname" TYPE="TEXT" />
<FIELD EMPTYOK="YES" MAXREPEAT="1" NAME="RecordID" TYPE="NUMBER" />
</METADATA>
<RESULTSET FOUND="1">
<ROW MODID="0" RECORDID="36489">
<COL>
<DATA>Sue</DATA>
</COL>
<COL>
<DATA>Smythe</DATA>
</COL>
<COL>
<DATA>36489</DATA>
</COL>
</ROW>
</RESULTSET>
</FMPXMLRESULT>
|
-dso_xml_dtd is used to return the DTD for this format. If you do not specify a layout or find any particular record, all the fields on the default layout will be returned. The same request as Listing 5.11 is issued but this time asking for the Document Type Definition to be returned.
Notice the new line added to the XML returned, "<!DOCTYPE FMPDSORESULT (View Source for full doctype…)>." Showing the browser source code reveals the full doctype for the request in Listing 5.12. The DTD in Listing 5.13 tells the document what elements and attributes it can contain and is why the document is valid XML. The element names are specific to the fields on the named layout.
|
fmpro?-db=Xtests.FP5&-lay=web&-format=-dso_xml_dtd&-recid=36489&-find
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE FMPDSORESULT (View Source for full doctype...)>
<FMPDSORESULT>
<ERRORCODE>0</ERRORCODE>
<DATABASE>xtests.fp5</DATABASE>
<LAYOUT>web</LAYOUT>
<ROW MODID="0" RECORDID="36489">
<firstname>Sue</firstname>
<lastname>Smythe</lastname>
<RecordID>36489</RecordID>
</ROW>
</FMPDSORESULT>
|
|
<!DOCTYPE FMPDSORESULT [
<!ELEMENT FMPDSORESULT (ERRORCODE, DATABASE, LAYOUT, ROW*)>
<!ELEMENT ERRORCODE (#PCDATA)>
<!ELEMENT DATABASE (#PCDATA)>
<!ELEMENT LAYOUT (#PCDATA)>
<!ELEMENT ROW (firstname,lastname,RecordID)>
<!ATTLIST ROW RECORDID CDATA #REQUIRED MODID CDATA #REQUIRED>
<!ELEMENT firstname (#PCDATA)>
<!ELEMENT lastname (#PCDATA)>
<!ELEMENT RecordID (#PCDATA)>
]>
|
-fmp_xml_dtd includes the DTD for the particular XML document returned when an action is performed. Similar to the DTD for FMPDSORESULT, Listing 5.14 shows the Document Type Definition for an FMPXMLRESULT request.
|
<!DOCTYPE FMPXMLRESULT [
<!ELEMENT FMPXMLRESULT (ERRORCODE,PRODUCT,DATABASE,METADATA,RESULTSET)>
<!ELEMENT ERRORCODE (#PCDATA)>
<!ELEMENT PRODUCT EMPTY>
<!ATTLIST PRODUCT NAME CDATA #REQUIRED VERSION CDATA #REQUIRED
BUILD CDATA #REQUIRED>
<!ELEMENT DATABASE EMPTY>
<!ATTLIST DATABASE NAME CDATA #REQUIRED RECORDS CDATA #REQUIRED
DATEFORMAT CDATA #REQUIRED TIMEFORMAT CDATA #REQUIRED LAYOUT
CDATA #REQUIRED>
<!ELEMENT METADATA (FIELD)*>
<!ELEMENT FIELD EMPTY>
<!ATTLIST FIELD NAME CDATA #REQUIRED TYPE (TEXT|NUMBER|DATE|
TIME|CONTAINER) #REQUIRED EMPTYOK (YES|NO) #REQUIRED
MAXREPEAT CDATA #REQUIRED>
<!ELEMENT RESULTSET (ROW)*>
<!ATTLIST RESULTSET FOUND CDATA #REQUIRED>
<!ELEMENT ROW (COL)*>
<!ATTLIST ROW RECORDID CDATA #REQUIRED MODID CDATA
#REQUIRED>
<!ELEMENT COL (DATA)*>
<!ELEMENT DATA (#PCDATA)>
]>
|
-fmp_xml when used with the action -view will produce another kind of document containing the layout information. The database name, layout name -format=-fmp_xml is needed to return the document type. The root of this document is <FMPXMLLAYOUT></FMPXMLLAYOUT>. Listing 5.15 shows the request and results for the layout information of the "web" layout in the Xtests.fp5 database. Just changing the action to -view results in the FMPXMLLAYOUT.
|
fmpro?-db=Xtests.fp5&-lay=web&-format=-fmp_xml&-view
<?xml version="1.0" encoding="UTF-8" ?>
<FMPXMLLAYOUT xmlns="http://www.filemaker.com/fmpxmllayout">
<ERRORCODE>0
</ERRORCODE>
<PRODUCT BUILD="5/4/2002" NAME="FileMaker Pro Web Companion"
VERSION="6.0v1" />
<LAYOUT DATABASE="xtests.fp5" NAME="web">
<FIELD NAME="firstname">
<STYLE TYPE="EDITTEXT" VALUELIST="" />
</FIELD>
<FIELD NAME="lastname">
<STYLE TYPE="EDITTEXT" VALUELIST="" />
</FIELD>
<FIELD NAME="RecordID">
<STYLE TYPE="EDITTEXT" VALUELIST="" />
</FIELD>
</LAYOUT>
<VALUELISTS />
</FMPXMLLAYOUT>
|
RecordID Parameter
-recid—This parameter is required with -edit and -delete actions to act upon a specific record. When used with the -find action, it will return a specific record if it exists in the named database. FileMaker Pro automatically assigns this ID to each record as it is created. It is always unique in any given database. The number assigned is not sequential, so it is rarely used for an invoice number or relationship key. In the database this can be determined by creating an unstored calculation: RecordID=Status(CurrentRecordID). The value of this parameter is returned in the XML results in the record element: <ROW RECORDID= "'MODID='">. Here are some sample requests using -recid:
fmpro?-db=Xtests.FP5&-lay=web&-format=-dso_xml&firstname= Jane&lastname=Doe&-recid=36488&-edit fmpro?-db=Xtests.fp5&-format=-dso_xml&-lay=web&-recid=36488&-delete fmpro?-db=Xtests.fp5&-lay=web&-recid=36488&-find
Record Modification Count Parameter
-modid—Introduced in FileMaker Pro 5, the count status of a particular record is updated every time the record is modified. This function in the database is Status (CurrentRecordModificationCount). When a record is returned to the browser, the value of the parameter is in the record element: <ROW RECORDID= "MODID=">. -modid is used by the -edit action, optionally, to determine if the information is to be edited or not.
This function is most important when using the web for record editing. When using peer-to-peer or client-server networking, the database only allows one user in a record with edit privileges. This is called record locking. Other users can view the record but cannot modify it until the "owner" exits that record. In contrast, the stateless HTTP protocol used by Web Companion for editing the database sends the request for a record and disconnects from the database. By noting the MODID when a record is returned to the browser, you can determine if another user has modified it and decide whether to continue or notify the web user of the new state.
Parameters for Using Stylesheets
-styletype and -stylehref—These two parameters are used together to point to the type and name (or location) of the stylesheet used to format the results of the XML request. FileMaker Pro uses XSL and CSS stylesheets with this parameter. While other means can be used to format your XML results, these files placed in the Web folder are read by the parameter. Depending on your browser capabilities, the stylesheet will display the data with formatting, such as font and location on the browser window. XSL stylesheets and Cascading Style Sheets (CSS+) are discussed in Chapter 7. The two parameters for a stylesheet are as follows:
-styletype=text/xsl&stylehref=Xtests.xsl -styletype=text/css&stylehref=Xtests.css
Password Parameter for -dbopen Request
-password—This optional parameter is used with the -dbopen action. If the database has a password, you can use the parameter to specify which password to use when opening the database.
fmpro?-db=Xtests.fp5&-password=a1b2c3&-dbopen
Find Request Parameters
The following parameters work with the -find action to alter the found set with operators, number of records, sorting, and scripts to perform.
Logical Operator for Multiple Find Requests
-lop—This logical operator is used when making multiple find requests. The choices are AND (find this and that) and OR (find this or that), with the default value of AND if you do not specify this parameter. AND finds will combine the name=value pairs to match all of the values in their associated fields. OR will search for the values in any record and return any of the matches, much like using multiple find requests. The following examples show the requests for XML and equivalent scripted finds in the database.
In the examples, Listing 5.16 shows an AND request to two different fields. Listing 5.17 shows an equivalent scripted AND request to the database. The logical operator (-lop) is used in Listing 5.18 to find two values in the same field. The scripted equivalent is shown in Listing 5.19. And finally, the OR request is shown in Listing 5.20, with a scripted version in Listing 5.21.
|
fmpro?-db=Xtests.fp5&-lay=web&firstname=Joe&lastname=Brown&-find
<?xml version="1.0" encoding="UTF-8" ?>
<FMPDSORESULT xmlns="http://www.filemaker.com/fmpdsoresult">
<ERRORCODE>0</ERRORCODE>
<DATABASE>xtests.fp5</DATABASE>
<LAYOUT>web</LAYOUT>
<ROW MODID="0" RECORDID="36490">
<firstname>Joe</firstname>
<lastname>Brown</lastname>
<RecordID>36490</RecordID>
</ROW>
</FMPDSORESULT>
|
|
Enter Find Mode [] Set Field [ firstname, "Joe" ] Set Field [ lastname, "Brown" ] Perform Find []
|
|
fmpro?-db=Xtests.fp5&-lay=web&customer=Joe&-lop=and&customer=Brown&-find
<?xml version="1.0" encoding="UTF-8" ?>
<FMPDSORESULT xmlns="http://www.filemaker.com/fmpdsoresult">
<ERRORCODE>0</ERRORCODE>
<DATABASE>xtests.fp5</DATABASE>
<LAYOUT>web</LAYOUT>
<ROW MODID="0" RECORDID="36490">
<customer>Joe Brown</customer>
</ROW>
<ROW MODID="0" RECORDID="36490">
<customer>Brownly, Joel</customer>
</ROW>
</FMPDSORESULT>
|
|
Enter Find Mode [] Set Field [ customer, "Joe Brown" ] Perform Find []
|
|
fmpro?-db=Xtests.fp5&-lay=web&firstname=Joe&-lop=or&lastname=Brown&-find
<?xml version="1.0" encoding="UTF-8" ?>
<FMPDSORESULT xmlns="http://www.filemaker.com/fmpdsoresult">
<ERRORCODE>0</ERRORCODE>
<DATABASE>xtests.fp5</DATABASE>
<LAYOUT>web</LAYOUT>
<ROW MODID="0" RECORDID="36490">
<firstname>Joe</firstname>
<lastname>Jones</lastname>
<RecordID>36490</RecordID>
</ROW>
<ROW MODID="0" RECORDID="36490">
<firstname>Elmer</firstname>
<lastname>Brown</lastname>
<RecordID>36532</RecordID>
</ROW>
</FMPDSORESULT>
|
|
Enter Find Mode [] Set Field [ firstname, "Joe" ] New Record/Request Set Field [ lastname, "Brown" ] Perform Find []
|
Comparison Operator for Each Find Request
-op—The comparison operator is similar to the symbols used by FileMaker Pro when making a find request. The default search operator is "begins with." FileMaker will select words that begin with the pattern of the search criteria. For the multiple words in the search criteria, the -op parameter is applied to the beginning of the search phrase, but all words are used in the search. The default operator for the remaining words is "begins with." This parameter is appended to the first word of the search string (before, after, or both).
