Friday, 6 June 2014

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:

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:

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., 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.


  1. Setting debug=1 in conf.ini allows more output to the error log, which can be invaluable for tracing down blank white screen issues.

    My own blank white screens have often come from issues in my actions.ini file where I have built a menu system. If there are conditional statements that check $record yet $record does not exist for some reason, then the $record->val('myfield') statement cannot be evaluated and php exits without output, except for an error in the log that only shows up with debug=1. [Doing "isset($record) and $record->val('myfield')" helps in most situations; I've also built a custom function to verify that myfield has a value stated in the url arguments.]

  2. Hi i get this error message in my error log after the blank screen
    [Wed Oct 22 20:31:41.069770 2014] [:error] [pid 1702] [client] PHP Notice: Use of undefined constant XF_DB_DRIVER - assumed 'XF_DB_DRIVER' in /var/www/html/xataface/installer.php on line 521
    [Wed Oct 22 20:31:41.069913 2014] [:error] [pid 1702] [client] PHP Warning: require_once(xf/db/drivers/XF_DB_DRIVER.php): failed to open stream: No such file or directory in /var/www/html/xataface/installer.php on line 521
    [Wed Oct 22 20:31:41.069933 2014] [:error] [pid 1702] [client] PHP Fatal error: require_once(): Failed opening required 'xf/db/drivers/XF_DB_DRIVER.php' (include_path='.:lib') in /var/www/html/xataface/installer.php on line 521
    i am on a laptop with linux mint 17
    apache, mysql and phpmyadmin are working correctly

  3. This comment has been removed by the author.

  4. The firs for the problem "Application Loads But All images and styles are missing" doesn't work. I edited the index.php file as like was suggested, the path to the xataface was incorrect. I re-applied read-write permissions to the entire xataface directory on my server, I re-applied read-write permissions to the entire application directory, I shutdown Apache and restarted it, it still shows the page missing all pictures and, obviously, not loading the CSS to display it neatly. Something is broken.

    1. Had the same issues. Tried almost all possible path variations. The permissions of my xataface directory have been set to '744'.

      Changing the permissions to '755' solved the problem.

  5. I don't get a white screen anymore, but this:
    display(); $app =& Dataface_Application::getInstance(); $app->display()

    I think I'm doing something basically dumb, but have no idea what.

    Help, please!

    1. Your code may not have come through here correctly. The display(); at the beginning is incorrect. All you need now after the require statement is

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

    2. Good night's sleep. Kept looking and found stuff that worked, seems I was missing a templates_c folder.

      I got to Xataface & my DB (Yay!), but SMARTY wants something I don't know where to look up even:

      Deprecated: mysql_connect(): The mysql extension is deprecated and will be removed in the future: use mysqli or PDO instead in C:\xampp\htdocs\XataTEST\xataface\Dataface\Application.php on line 576

      Deprecated: preg_replace(): The /e modifier is deprecated, use preg_replace_callback instead in C:\xampp\htdocs\XataTEST\xataface\lib\Smarty\Smarty_Compiler.class.php on line 270

    3. 1. These are deprecation warnings and can be disabled.

      2. MySQLi is supported in Xataface

      3. What version of Xataface are you using? I think the smarty deprecated error is fixed in the latest in git.

    4. I'm using 2.0.3, and thanks for the deprecation solution pointer, it worked and I learned.

      The window opens with TWO html "pages", and checking the source, the code is duplicated. Have I managed to build in recursion?

    5. Are you calling "display()" twice in your index.php file?

  6. Hi may I seek some help, I created the database already and also did the FacultyOfWidgetry file, I am using XAMPP. But i got this message

    "As of Xataface 1.3 all applications are now required to have its own templates_c directory to house its compiled templates. Please create the directory "/Applications/XAMPP/xamppfiles/htdocs/FacultyOfWidgetry/templates_c" and ensure that it is writable by the web server."

    I created the directory already but it is empty, so what do I include in there?

    1. You don't need to put anything in it. It just needs to be there and be writable by the web server. Xataface will save compiled smarty templates in it.

    2. Hi,

      Can I ask how do I create the directory? Is it just a folder?

    3. Thanks, it finally loaded, but I am missing the images, I have the xataface folder in my htdocs folder of XAMPP, and my directory is /Applications/XAMPP/xamppfiles/htdocs/xataface/, I am using mac btw. Why is it not working?

    4. Hi,

      It's me again, I tested everything on a windows laptop and I get the same problem, style and photos not loaded, may I know what have I done wrongly?

      The second line of my code is df_init(__FILE__, 'C:/xampp/htdocs/xataface')->display();

  7. This comment has been removed by the author.

  8. I get a vary basic interface that gives me access to my database. It is not very user friendly and looks nothing like the examples in the tutorial.
    The left menu says
    Show All
    Copy Set
    Delete Set
    Update Set

    Also, when I add new entries two fields do not update but remain blank.

    1. Some tutorials were written with the old look and feel. You can revert to the old look and feel by adding disable_g2=1 to the beginning of the conf.ini file.

      For the fields not updating, check that the field names don't have any special characters or spaces. Xataface doesn't like those. I need to add some better checking for this...

  9. No special characters. I had problems with the database not having a primary field. All fields were text. I change one to Varchars which fixed the primary field problem. Then I noticed data enter in this field would not end up in the database. I tried Tinyext and Mediumtext, no luck. Added a datestamp field as primary and back to all other fields being text but they still the 2 fields don't seem to receive data. I can insert data using phpmyadmin, Refreshed Xataface. No luck. it turns out that there is a 3rd field not often used that can't be filled in also. All tree fields were ones I had set to Varchars or Tinytext etc at some stage. The 2 fields that do accept data have been Text all the time.

    If data is entered via phpmyadmin it is visible in Xataface.

    Does Xataface have some configuration that it read from the earlier data base structure that I should edit now?

  10. FYI, all I want is ADD, EDIT, DELETE & SEARCH dialogue for the interface, It is a simple requirement.

  11. I put disable_g2=1 at the beginning of the conf.ini file. I got the same effective interface, but in text only form, Looks like something from the 90's :).

    1. 1. Check your php error log.
      2. Please post your tables schema. Eg show create table tablename

  12. I can't find any log file for php.
    I am running WAMP on Windows Server 2008, 64 bit
    Apache 2.4.4
    PHP 5.4.12
    mysql 5.0.10
    Xataface was downloaded on Saturday.

    When I try to run some other new php scripts php goes into a loop and I need to restart Apache. xataface scripts didn't do that.
    The database had one table
    Date (Timestamp)
    Part Number (text or Varchars 20)
    Description (Text)
    Drawing Number (Text or Varchars 10)
    Product Code (Text or Varchars 20)
    Comments (Text)

    Only Date, Description and Comments work properly.

    1. You have spaces in your column names. Replace those with underscores.

  13. I've tried to create a new app (I've had an old xataface app runnig 5 years+ on the same server so don't think it's server config) but am getting the following errors. This happens whether I use the built-in installer or using the manual process.

    It gives me a few troubleshooting tips but none have helped fix it.

    When run the app for the first time I get the following errors

    Fatal error: Uncaught exception 'Exception' with message 'Got error -1 from storage engine' in \xataface\Dataface\IO.php:2580 Stack trace:
    #0 \xataface\Dataface\Table.php(3247): Dataface_IO::touchTable('companies')
    #1 \xataface\Dataface\Table.php(541): Dataface_Table::getTableModificationTimes()
    #2 \xataface\Dataface\Table.php(492): Dataface_Table->Dataface_Table('companies', Resource id #13, false)
    #3 \xataface\Dataface\Application.php(2153): Dataface_Table::loadTable('companies')
    #4 \xataface\Dataface\Application.php(2564): Dataface_Application->handleRequest(false)
    #5 \xataface\Dataface\Application.php(2433): Dataface_Application->_display(false, false)
    #6 \index.php(6): Dataface_Application->display() #7 {main} thrown in \xataface\Dataface\IO.php on line 2580

    1. Does the dataface__mtimes table exist? If it does, try deleting it. If it doesn't, that is strange... it should be able to create it. Make sure that the Xataface app has permission to create tables.


  14. DreamHost is ultimately the best hosting provider with plans for all of your hosting requirments.

  15. Your blog has given me that thing which I never expect to get from all over the websites. Nice post guys!

    SEO Melbourne

  16. Can anyone help me set up xataface on my hosting? I've been trying for days now and no success...

    1. please write to

  17. Great blog created by you. I read your blog, its best and useful information. You have done a great work. Super blogging and keep it up.php jobs in hyderabad.

  18. If you want your ex-girlfriend or ex-boyfriend to come crawling back to you on their knees (no matter why you broke up) you have to watch this video
    right away...

    (VIDEO) Why your ex will NEVER come back...