ExcelExplorer Pro Manual

ExcelExplorer Manual
Getting Started
Prev
Introduction
Next
Definitions

Chapter 2. A simple tutorial

Basic Concepts

It is very important to understand how to work with ExcelExplorer's classes and methods in order to write clean and optimized code. Your code that uses ExcelExplorer must include the following three steps:

  1. Creating the object - an instance of ExcelExplorer class. This is the only object you must created by yourself. All other work will be done using methods provided by classes as described below.
  2. Pass the Excel file to the object for parsing using one of the following methods: ExploreFile or ExploreString. You can pass various options to these methods controlling how to extract data and what exactly must be readed from an Excel file.
  3. Read necessary data using methods provided by the package as described below (full list of classes and it's methods can be found here). Note that you not need to controlling objects creation or deletion - it will be done automatically.

1. Creating an object.

<?php

require 'ExcelExplorer.php';
$ee = new ExcelExplorer();

?>

2.1. Parse file using ExploreFile method.

<?php

$result 
$ee->ExploreFile('test.xls');

?>

2.2. Parse file using ExploreString method.

<?php

$file_contents 
file_get_contents('test.xls');
$result $ee->ExploreString($file_contents);

?>

Reading Data

The main idea is to provide easy-to-use API. To realize how it's simple check the following sample - it read some data from some cell, applying numeric format (percentage, date, etc.), convert it to the UTF-8 encoding if it is a text or leave unchanged for other data types and print the result. And it is done WITH ONLY ONE CALL!

<?php

// $sheet, $column and $row contains indexes to
// worksheet, column and row respectively
echo $ee->Cell($sheet,$column,$row)->Data()->UTF8();

?>

Let's see the techniques that can be used to read necessary data. The main class ExcelExplorer provides some functions to get needed worksheet, column, row or a cell. Each of this methods returns an object instance of appropriate class.

<?php

// get worksheet
$sheetobj $ee->Worksheet($sheet); // $sheetobj now is an instance of EEWorksheet class

// get column
// the following two lines are equivalent
$columnobj $ee->Column($sheet,$column); // $columnobj now is an instance of EEColumn class
$columnobj $sheetobj->Column($column); // $columnobj now is an instance of EEColumn class

// get row
// the following two lines are equivalent
$rowobj $ee->Row($sheet,$row); // $rowobj now is an instance of EERow class
$rowobj $sheetobj->Row($row); // $rowobj now is an instance of EERow class

// get cell
$cellobj $ee->Cell($sheet,$column,$row); // $cellobj now is an instance of EECell class
$cellobj $sheetobj->Cell($column,$row); // $cellobj now is an instance of EECell class
$cellobj $columnobj->Cell($row); // $cellobj now is an instance of EECell class
$cellobj $rowobj->Cell($column); // $cellobj now is an instance of EECell class

?>

Depending on what you need you use one of these functions. When the needed object obtained you can call it's own functions. For example, for worksheet you can obtain title, for column - width, for row - height, for cell - data stored in it. It's can be done using many functions provided in appropriate classes (full list of classes and it's functions see at "List of all available classes" section).

Let's assume that we need to obtain data from the cell. First, we get an EECell object, as show above. Second, we use one of two methods provided by EECell class - PlainData or Data. EECell->PlainData returns unformatted data, i.e. "as-is" - no numeric formats will be applied, error value will be returned as integer codes, not strings like "#DIV/0!", etc. This method returns you what Excel really stores in the cell, but not as it shows. Data, in contrast, applying formats and do other processing to return value that Excel shows. Assuming we need to get formatted data.

<?php

$dataobj 
$cellobj->Data();

?>

IMPORTANT!
The PHP5 presents dereferencing, so you can re-write the above example as follows:

<?php

$dataobj 
$ee->Cell($sheet,$column,$row)->Data();

?>

Now we have $dataobj variable - an instance of EEData class. The final step - convert it to the presentation we need.

Retrieve data and shows it as well-formatted HTML string.

<?php

$data 
$ee->Cell($sheet,$column,$row)->Data()->HTML();
echo 
$data;

?>

Retrieve data and shows it in UTF-8 encoding.

<?php

$data 
$ee->Cell($sheet,$column,$row)->Data()->UTF8();
echo 
$data;

?>

The first example will convert all non-ASCII characters in a HTML sequences like &#1234;. The second one will convert such characters to UTF-8 encoding which widely using in a different systems. In this encoding all ASCII characters leaves untouched, therefore if your string contains only such characters it will be unchanged and displaying correctly as it in ASCII encoding.

This tutorial gives you the basic understanding of how to work with ExcelExplorer. However it is not limited to just retrieve data from a cells. You can do much more using the many classes and it's functions. For example, get the fonts, styles, borders, info about merged cells areas, info about rows and columns like grouping level, visibility and many other useful things.


ExcelExplorer Manual
Getting Started
Prev
Introduction
Next
Definitions