Getting Started: Most Common Mistakes

This article is dedicated to future new users of Xataface who have difficulty getting their first app up and running.  I have created a number of "getting started" tutorials for Xataface, and have posted a couple of getting started videos.  Some of these include:

• Creating Your First Application (from the Getting Started tutorial) - Shows use of the "makesite" script as well as manual installation steps.
• How to build a PHP/MySQL Application with 4 Lines of Code (Shows the "manual" approach).
• About Xataface > Your First App - Also shows the "manual" approach.
• Building Data-Centric Websites with Dataface - (Very old powerpoint presentation)
• Build a Blog in 4 Minutes (Video) - Shows use of Web-based install tool.
• Introduction to Xataface (Video) - Also shows use of Web-based install tool.

These tutorials demonstrate how to create your first Xataface application using one of three methods:

1. Using the makesite shell script.
2. Using the web-based install tool.
3. Creating the application manually.

All three of these approaches *should* work, but I personally favour the manual approach for the following reasons:

1. It is really easy.  2 lines of PHP,  5 or 6 lines in the conf.ini file, and copy the .htaccess file. and you're done.
2. It helps you to understand the application structure from the beginning.  You're going to have to start customizing your app by hand sooner or later, so why now make it sooner.

Common Mistakes

The Web-based Installer Cannot Connect to the Database

If the web-based installer can't connect to the database, it is likely that your database is located on a different domain than localhost.  The Xataface installer script has the database host hard-coded into the script as "localhost".   If your database is located on a different server, as it may be on some shared hosting environments, you may need to modify the "installer.php" file and change the DB_HOST constant to the correct value for your server.

The Web-based Installer Keeps Prompting for Username and Password

The web installer uses the password that you provide to connect to the database.  It must be a valid mysql username and password that will have access to at least the database on which you want to create your app.  You may also enter your MySQL root password here - as it will only be used to create the app - you will have another opportunity to specify the user account that the app will use for connecting to the database.  If it keeps prompting you for the password that means that you are entering incorrect credentials.  If you're sure that you're entering the correct information here, I wouldn't spend too much time trying to solve it here.  Just skip straight to a manual installation.

Xataface Says "Installed Correctly" but I can't access my app

Likely you are following the Getting Started Tutorial, and you have just reached the end of the "Xataface Installation" section.  Installing Xataface is actually easy, it just involves copying it to your web server.  However, xataface being installed is different than your app being installed.  You still need to proceed to the next section of the getting started tutorial on creating your first app.  Better yet, just follow the manual installation instructions so you don't have to futz with any app creation scripts.

Blank White Screen

The single most common "help" request I get on the forum is the blank white screen issue.  If you get a blank white screen when you try to access your app, it means that there is an error that caused PHP execution to fail.  Likely it is an issue with a require statement pointing to the wrong path, but, technically it could be *anything*.  You need to check your PHP error log to see what the actual error is.  This is a good opportunity to get acquainted with your PHP error log because it will be your best friend going forward.  If you post to the forum without knowing where your error log is or where errors are being written, you'll likely just be sent on a mission to find it.  Some tips on solving the "blank white screen issue".

No Such File or Directory "xataface"

The following error is common for first time users:

Warning: require_once(../xataface-git/public-api.php): failed to open stream: No such file or directory in /Applications/XAMPP/xamppfiles/htdocs/index.php on line 5

Fatal error: require_once(): Failed opening required '../xataface-git/public-api.php' (include_path='.:/Applications/XAMPP/xamppfiles/lib/php') in/Applications/XAMPP/xamppfiles/htdocs/index.php on line 5

This error will occur if the require_once statement at the beginning of your index.php file is pointing to the wrong place, or if the place it is pointing is not readable by the web server process.  The first line of your index.php file is likely something like:

<?php
require_once 'xataface/public-api.php';

This should point to your xataface/public-api.php file.  Make sure that it points to the correct place, and that the permissions on the file allow reading from the web server process.

Application Loads But All images and styles are missing

If your application loads but it looks weird (e.g. missing images, no style, broken page formatting, etc...), it means that the 2nd parameter of your df_init() function (inside your index.php file) is pointing to the wrong place.

In your index.php file, you'll have a line like:

df_init(__FILE__, 'xataface')->display();

The 2nd parameter (in this case 'xataface') should be the web-accessible URL to the xataface directory.  It may be an absolute URL (e.g. http://example.com/path/to/xataface), or a relative URL (e.g. 'xataface').  This parameter is used as a base for loading all images and CSS stylesheets in the Xataface directory.  If it is wrong, you'll get no style.  After you fix this, you should see the page formatting correctly.