Dataface URL Protocols

1. Dataface URL Protocols Steve Hannah Web Lite Solutions Corp. Steve@weblite.ca

2. Anatomy of a URL • URLs allow you to pass parameters to PHP scripts via GET variableseg: http://yourdomain.com/index.php?name=fooThe above would pass the parameter “name” with value “foo” to the index.php script. • The question mark (‘?’) in a URL indicates that everything that follows are parameters. • Multiple parameters can be separated by an ampersand (‘&’):http://yourdomain.com/index.php?name=foo&size=10

3. Dataface URL Instructions • Parameters beginning with ‘-’ are instructions for Dataface:e.g. -action=list or -table=peopleTo tell dataface to perform the ‘list’ action or to show the ‘people’ table. • Instructions are maintained between multiple requests. E.g. If you are in the ‘people’ table, all links in Dataface will include ‘-table=people’ so that the user will still be in the ‘people’ table when he clicks on one of the links.

4. Dataface URL Metadata • GET parameters beginning with ‘--’ are metadata for the current request.E.g. --msg=Records%20Successfully%20DeletedPasses a message parameter to display in the Info dialog. • Metadata is not passed between requests. They are for one request only. • This convention is useful for custom actions when you want to pass special information to your action that shouldn’t persist across requests. • Why not just pass your parameters normally (without the prepended ‘--’? Answer: Next slide

5. Query Parameters • GET parameters not beginning with ‘-’ are considered to be search parameters. • LastName=Smith will filter the results to only show records where the LastName field contains the phrase ‘Smith’. This would match such names as ‘Smith’, ‘Smithy’, ‘Brownsmith’, etc… • If you need to pass parameters to your script that are NOT query parameters, you should prepend ‘-’ or ‘--’ to the parameter name so Dataface doesn’t confuse them for query parameters.

6. Query Parameter Fun I • FirstName=BobMatches ‘Bob’, ‘bob’, ‘Bobby’, ‘cabob’, … • FirstName==BobMatches ‘Bob’, ‘bob’, but not ‘Bobby’ or ‘cabob’ • FirstName=>BobMatches ‘Bobby’, ‘Carl’, ‘Doug’, but not ‘Adam’, ‘Ark’, ‘Bill’, or ‘Bob’. (I.e. matches any name coming after ‘Bob’ in the lexicographic alphabetical ordering).

7. Combining Parameters: AND • Putting multiple search parameters together is equivalent to performing an ‘AND’ on the parameters. • E.g. FirstName=Bob&LastName=Smithwould match records with FirstName ‘Bob’ and LastName ‘Smith’. But ‘Bob McKenzie’ would NOT be matched.

8. Exercise I

9. Bringing it together • Index.php?-action=list&-table=People&FirstName=BobWill show the list view for the People table. Showing only results where FirstName contains ‘Bob’ (case insensitive). • Index.php?-action=edit&-table=People&UserID=10Will show the edit form to edit the record from the People table with UserID=10. • Index.php?-action=view&-table=People&UserID=10&--msg=Welcome+to+my+siteWill show the view tab for the record from the People table with UserID=10. Will display an info message saying “Welcome to my site” along to top.

10. Full-text Searching • Use the -search instruction to perform full-text search on all columns • -search=Bob+SmithMatches records containing both ‘Bob’ and ‘Smith’. Matches can occur on any text or varchar column in the record.

11. Combining Parameters: OR • FirstName=Bob+OR+CarlMatches ‘Bob’, ‘Bobby’, ‘cabob’, ‘Carl’, ‘Carly’, ‘my carly’. • Currently no way to perform OR query over multiple columns. E.g. Cannot match records with FirstName Bob OR LastName Smith.

12. Query Parameter Fun II • FirstName=<BobMatches ‘Adam’, ‘Bill’ but not ‘Bob’, ‘Carl’, ‘Derek’, etc… (I.e. matches names before ‘Bob’ in lexicographic alphabetical ordering). • FirstName=Bob..CarlMatches ‘Bob’, ‘Carl’, ‘Buster’, ‘Cam’, but not ‘Adam’ or ‘Carly’ (I.e. Matches names between ‘Bob’ and ‘Carl’ inclusive).

13. Actions: the -action parameter • The -action parameter used to specify the action to perform. • Common Dataface actions:new : New record formedit : Edit an existing recordview : View tablist : The list viewfind: The find tabdelete: Deletes the current recordrelated_records_list : Show the related records (requires -relationship parameter to be the name of the relationship to show).

14. Exercise I • Form URLs to perform the following queries: • Create a new record in the ‘People’ table. • Edit record with UserID 10 in the ‘People’ table. • Show enrolled courses for the Person with FirstName ‘Grant’ and LastName ‘Drummond’ in the People table. Enrolled courses are represented by the relationship ‘courses’. • Show the edit form for the 12th record in the result set formed when searching for Country=Canada on the People table.

15. Accessing URL Parameters from PHP Steve Hannah Web Lite Solutions Corp. Steve@weblite.ca

16. Accessing Parameters Directly • Index.php?FirstName=Bob&-table=People$_GET[‘FirstName’] // ‘Bob’$_GET[‘-table’] // ‘People’ • This method is OK, but doesn’t take into account default parameters. (e.g. If user requests index.php with no parameters, then Dataface implies default values for -table, -action, etc… that won’t be accessible via $_GET array).

17. Accessing Parameters from Application Object $app =& Dataface_Application::getInstance(); $query =& $app->getQuery(); // Returns associative array of query parameters with default values filled in. e.g. $query[‘-table’], $query[‘-action’], $query[‘-limit’], $query[‘-cursor’].