InputfieldMatrix.module

<?php

/**
* InputfieldMatrix for ProcessWire.
*
* This Inputfield is a GUI for FieldtypeMatrix.
*
* @author Francis Otieno (Kongondo) <kongondo@gmail.com> kongondo.com
* 
* Lincensed under GNU/GPL v2.
*
* https://github.com/kongondo/FieldtypeMatrix
* Created December 2014
* 
* ProcessWire 2.x
* Copyright (C) 2011 by Ryan Cramer
* Licensed under GNU/GPL v2, see LICENSE.TXT
*
* http://www.processwire.com
*
*/

class InputfieldMatrix extends Inputfield {

	public static function getModuleInfo() {
		return array(
			'title' => 'Matrix',
			'author' => 'Francis Otieno (Kongondo)',
			'version' => 104,
			'href' => 'https://processwire.com/talk/topic/8581-module-matrix-fieldtype-inputfield/',
			'summary' => 'Matrix: Inputfield for a 2D-matrix.',
			'requires' => 'FieldtypeMatrix', 
			);
	}

	protected $page;
	protected $field;
	protected $tableID;
	protected $inputPrefix;
	protected $csvImportMode;
	protected $lastBlankRowID;
	protected $csvIgnoreFirstRow;
	protected $csvIgnoreFirstColumn;

	public function setPage(Page $page) {
		
		$this->page = $page; 
	}

	public function setField(Field $field) {

		$this->field = $field;
	}

	/** 
	* Find row pages using a specified page field.
	*
	* The children of the respective pages in the page field will be returned as row+column labels/headers.
	* The first page in the page field = rows headers.
	* The second page in the page field = columns headers.
	* 
	* @access private
	* @param String $rowsParent Name of a page field that will contain pages whose children will be returned as row+column labels/headers.
	* @return PageArray $rows Child pages of the specified parent page that will make up the row headers.
	*
	*/
	private function matrixRows($rowsParent) {

		//if for some reason specified $rowsParent does not exist set error message
		if(!$rowsParent) return $this->_('The specified matrix row parent page was not found. Confirm it exists or specify another.');
		
		//if $rowsParent does not have children set error message
		if(!$rowsParent->numChildren) return $this->_('The specified matrix rows parent does not have children. You need to first create its child pages.');

		//find all matrix-row pages
		$rows = $rowsParent->children;

		return $rows;

	}

	/** 
	* Find column pages using a specified page field.
	*
	* The children of the respective pages in the page field will be returned as row+column labels/headers.
	* The first page in the page field = rows headers.
	* The second page in the page field = columns headers.
	* 
	* @access private
	* @param String $columnsParent Name of a page field that will contain pages whose children will be returned as row+column labels/headers.
	* @return PageArray $columns Child pages of the specified parent page that will make up the column headers.
	*
	*/
	private function matrixColumns($columnsParent) {

		//if for some reason specified $columnsParent does not exist set error message
		if(!$columnsParent) return $this->_('The specified matrix columns parent page was not found. Confirm it exists or specify another.');
		
		//if $columnsParent does not have children set error message
		if(!$columnsParent->numChildren) return $this->_('The specified matrix column parent does not have children. You need to first create its child pages.');
		
		//find all matrix-column pages
		$columns = $columnsParent->children;

		return $columns;

	}

	/**
	* Find row and column pages using a specified page field.
	*
	* The children of the respective pages in the page field will be returned as row+column labels/headers.
	* The first page in the page field = rows headers.
	* The second page in the page field = columns headers.
	* 
	* @access private
	* @param String $axis Name of a page field that will contain pages whose children will be returned as row+column labels/headers.
	* @return eval() of type Page or PageArray or null.
	*
	*/
	private function findPagesCode($axis) {

		$page = $this->page;
		//so that $page and $pages are locally scoped to the eval
		$process = $this->wire('process'); 
		if($process && $process->className() == 'ProcessPageEdit') $page = $process->getPage();

		$pages = $this->wire('pages');

		if($axis == 'row') $findPages = eval($this->rowFindPagesCode);
		elseif($axis == 'column') $findPages = eval($this->columnFindPagesCode);

		//if eval() returns anything other than a Page or PageArray, return null (error will be returned later in mergeMatrix())
		if($findPages instanceof Page ) return $findPages->children;//@@note: will check if children found in mergeMatrix()
		elseif($findPages instanceof PageArray ) return $findPages;
		else return null;

	}

	/** 
	* Build Inputfields for importing matrix values.
	*
	* @access private
	* @return Inputfields $inputfields Inputfields for importing/copy pasting csv values.
	*
	*/
	private function buildImportExportForm() {

		$n = $this->inputPrefix;

		//import CSV data options
		$inputfields = new InputfieldWrapper();

		$tableID = $this->tableID;
		
		//radio buttons
		$importMode = $this->defaultImportMode ? $this->defaultImportMode : 1;
		$ignoreFirstRow = $this->ignoreFirstRow ? $this->ignoreFirstRow : 1;
		$ignoreFirstColumn = $this->ignoreFirstColumn ? $this->ignoreFirstColumn : 1;
		
		$class = 'MatrixRadio ';
		
		$importModeRadio  = "<span class='{$class}'><span>Import Mode: </span>";
		$name = $n . '_importmode';		
		$radios = array('Append' => 1, 'Overwrite' => 2);
		foreach ($radios as $label => $value) {
			$checked = $value == $importMode ? 'checked' : '';
			$importModeRadio .= "
								<label class='{$class}' for='{$label}_{$tableID}'>{$label}</label>
								<input type='radio' id='{$label}_{$tableID}' name='{$name}' class='{$class} MatrixImportMode' data-table='{$tableID}' value='{$value}' {$checked}>";
		}

		$importModeRadio .= '</span>';

		$ignoreFirstRowRadio  = "<span class='{$class}'><span>Ignore First Row: </span>";
		$name = $n . '_ignore_first_row';		
		$radios = array('Yes' => 1, 'No' => 2);
		foreach ($radios as $label => $value) {
			$checked = $value == $ignoreFirstRow ? 'checked' : '';
			$ignoreFirstRowRadio .= "
								<label class='{$class}' for='row_{$label}_{$tableID}'>{$label}</label>
								<input type='radio' id='row_{$label}_{$tableID}' name='{$name}' class='{$class}' value='{$value}' {$checked}>";
		}

		$ignoreFirstRowRadio .= '</span>';

		$ignoreFirstColumnRadio  = "<span class='{$class}'><span>Ignore First Column: </span>";
		$name = $n . '_ignore_first_column';
		$radios = array('Yes' => 1, 'No' => 2);
		foreach ($radios as $label => $value) {
			$checked = $value == $ignoreFirstColumn ? 'checked' : '';
			$ignoreFirstColumnRadio .= "
								<label class='{$class}' for='col_{$label}_{$tableID}'>{$label}</label>
								<input type='radio' id='col_{$label}_{$tableID}' name='{$name}' class='{$class}' value='{$value}' {$checked}>";
		}

		$ignoreFirstColumnRadio .= '</span>';

		$fieldset = $this->modules->get('InputfieldFieldset');
		$fieldset->attr('id', $n . 'csv_import_export'); 
		$fieldset->label = $this->_('Import/Export CSV Data');
		$fieldset->description = $this->_('If you prefer, you may import a CSV file or copy-paste CSV data here rather than manually entering values in your matrix table above. You can also export saved matrix values to a CSV file.');
		$fieldset->value = $importModeRadio . $ignoreFirstRowRadio . $ignoreFirstColumnRadio;
		$fieldset->collapsed = Inputfield::collapsedYes;

		//import csv/txt file
		$f = $this->modules->get("InputfieldMarkup");
		$f->label = $this->_('Import from CSV File');
		$f->value = "<input name='" . $n . "_csvfile' type='file' />";
		$f->description = 
			 $this->_("UTF-8 compatible encoding is assumed. The file must have the extension '.csv' or '.txt'. You can also copy-paste in CSV data in the 'Import by copying and pasting CSV data' section below. You may do one or the other, but not both simultaneously. If you did both, copy-pasted values would be disregarded. If your CSV data is not comma-delimeted, specify your delimiter below before proceeding.");
		$f->notes = $this->_("1. If you wish to import values for your whole matrix table, be sure that the number of rows and columns in your CSV data exactly match the matrix table above.") . "\n". 
			$this->_("2. Any extra rows/columns will be discarded.") . "\n". 
			$this->_("3. However, your CSV data can also have less rows/columns or some missing values.") . "\n". 
			$this->_("4. After saving, you will be able to manually input missing values and/or correct mistakes.") . "\n". 
			$this->_("5. Make sure to specify whether the import should ignore the first row and the first column of the CSV. These typically contain column and row headers/labels respectively.") . "\n". 
			$this->_("6. Click the 'Save' Button once you have uploaded your file to start the import process.");

		$fieldset->add($f);

		//csv paste
		$f = $this->modules->get('InputfieldTextarea');
		$f->name = $n . '_csvpasted';
		$f->label = $this->_('Import by copying and pasting CSV data');
		$f->description = $this->_('Values entered here overwrite those in the matrix table!');
		$f->notes = $this->_("The notes outlined above in 'Import from CSV File' also apply here.");
		$f->collapsed = Inputfield::collapsedYes;

		$fieldset->add($f);

		//csv delimeter
		$f = $this->modules->get('InputfieldText');
		$f->name =  $n . '_csv_column_separator';
		$f->label = $this->_('Columns delimited by');
		$f->notes = $this->_('For tab-separated, enter: tab.');
		$f->value = ',';
		
		$fieldset->add($f);

		//csv enclosure
		$f = $this->modules->get('InputfieldText');
		$f->name = $n . '_csv_column_enclosure';
		$f->label = $this->_('Column enclosure');
		$f->notes = $this->_('When a value contains a delimeter, it must be enclosed by a character (typically a double quote character). If you are not sure what should go here, it is recommended you leave it at the default (").');
		$f->value = '"';
		if($f->value == '"') $f->collapsed = Inputfield::collapsedYes;
		$f->attr('maxlength', 1);
		$f->attr('size', 1);

		$fieldset->add($f);

		########## - EXPORT INFO - ############

		//export to csv
		$f = $this->modules->get("InputfieldMarkup");
		$f->label = $this->_('Export to CSV File');
		$f->description = 
			 $this->_("You can export saved matrix values to a CSV file that you can edit on your computer and optionally re-import into this matrix.");
		$f->notes = $this->_("1. If you will re-import the CSV file into this matrix, the above rules of importation apply.") . "\n". 
			$this->_("2. The columns delimiter and enclosure set above will be used in generating the CSV file.") . "\n". 
			$this->_("3. For convenience, row and column headers/labels will be included (as the first column and row respectively) in the exported CSV file.") . "\n" .
			$this->_("4. The exported CSV file will be named using the format 'pagename_matrixname_currenttime.csv'.") . "\n". 
			$this->_("5. Using the checkboxes, select at least one row that you want to export.") . "\n". 
			$this->_("6. Click an 'Export Data' Button to start the export process.");

		$fieldset->add($f);

		$inputfields->add($fieldset);

		return $inputfields;

	}

	/**
	* Find the pages to build the rows and columns labels for the Matrix Table/Grid.
	*
	* @return Array $rc Array with Row and Column PageArrays as values.
	*
	*/
	private function findRowsColumns() {

		$rc = array();
		$error = '';

		$pages = $this->wire('pages');
		$page = $this->page;
		$rowsParent = '';
		$columnsParent = '';
		
		$parentRowColumnPageField = $this->parentRowColumnFieldName;//this property was set in FieldtypeMatrix getInputfield()
		$rowFindPagesCode = $this->rowFindPagesCode;//ditto
		$columnFindPagesCode = $this->columnFindPagesCode;//ditto
		$rowSelector = $this->rowSelector;//ditto
		$columnSelector = $this->columnSelector;//ditto

		$editURL = $this->wire('config')->urls->admin . 'setup/field/edit?id=' . $this->field->id;
		
		### first we deal with errors. We'll return these as strings to output in $this->error() in render() ###

		//in neither a Page Field nor selectors for finding pages to build matrix rows/columns specified set error message
		if((!$parentRowColumnPageField) && (!$rowFindPagesCode || !$columnFindPagesCode) && (!$rowSelector || !$columnSelector))
				$error = '<a href="' . $editURL .'">' . 	$this->_('Check the Details Tab of the field') . '</a> ' . $this->field->name . 
														$this->_('. You need to either use selectors or a Page Field to find pages to show in your matrix table.');

		//if Page Field specified, we use that to find the children pages of the specified row and column parent pages respectively
		if($parentRowColumnPageField) {

				//if the page field does not return a PageArray, set error message	
				if(!$page->$parentRowColumnPageField instanceof PageArray) 
					$error = '<a href="' . $editURL .'">' . 	$this->_('Check the Details Tab of the field') . '</a> ' . $this->field->name . 
															$this->_('. Only a Multiple Page Field can be used to specify the rows and columns parent pages for building your matrix! Confirm that you specified a Multiple Page Field.');

				//if less than 2 matrix parent pages selected (we need one for rows and the other for columns) set error message
				elseif(count($page->$parentRowColumnPageField) < 2) $error = $this->_('You need to select 1 matrix rows parent and 1 matrix columns parent.');

				//parents
				elseif(count($page->$parentRowColumnPageField)) {
						$rowsParent = $page->$parentRowColumnPageField->first();//the first selected page is treated as the row pages parent
						$columnsParent = $page->$parentRowColumnPageField->getNext($rowsParent);//the second selected page is treated as the column pages parent
						
						//find all matrix-row pages						
						if(is_string($this->matrixRows($rowsParent))) $error = $this->matrixRows($rowsParent);
						##### -if we made it here, we are good to go with rows ####
						elseif($this->matrixRows($rowsParent) instanceof PageArray) $rows = $this->matrixRows($rowsParent);

						//find all matrix-column pages
						if(is_string($this->matrixColumns($columnsParent))) $error = $this->matrixColumns($columnsParent);
						##### -if we made it here, we are good to go with columns ####
						elseif($this->matrixColumns($columnsParent) instanceof PageArray) $columns = $this->matrixRows($columnsParent);
				}

	
		}//end if a Page Field was specified

		//if Page Field NOT specified, we use specified row/column custom PHP code OR selectors instead
		else {

				//find all matrix-row pages
				if($rowFindPagesCode) {
					$rows = $this->findPagesCode('row');
					if (!count($rows)) 
						$error = $this->_('Only Page or PageArray should be returned by your custom code!') . 
						' <a href="' . $editURL .'">' . 	$this->_(' Check that your \'Matrix Row code\' is valid') . '</a>.';
				}
				elseif($rowSelector) {
					$rows = $pages->find($rowSelector);//ProcessWire will throw an exception here if the selector is not valid
					//if row/column selectors return empty set error message
					if(!count($rows)) 
						$error =	$this->_('No row pages found with the selector set in \'Matrix Row pages\' for the field ') . $this->field->name . 
							'. <a href="' . $editURL .'">' . 	$this->_('Amend your selector') . '</a>.';
				}

				//find all matrix-column pages
				if($columnFindPagesCode) {
					$columns = $this->findPagesCode('column');
					if (!count($columns)) 
						$error = $this->_('Only Page or PageArray should be returned by your custom code!') . 
						' <a href="' . $editURL .'">' . 	$this->_(' Check that your \'Matrix Column code\' is valid') . '</a>.';
				}
				elseif($columnSelector) {
					$columns = $pages->find($columnSelector);//ProcessWire will throw an exception here if the selector is not valid
					if(!count($columns)) 
						$error = 	$this->_('No column pages found with the selector set in \'Matrix Column pages\' for the field ') . $this->field->name . 
							'. <a href="' . $editURL .'">' . 	$this->_('Amend your selector') . '</a>.';
				}

		}//end else we use row/column selectors

		//if we $error is populated, it means errors were found. We return the 'error' strings for later feedback to user
		if(strlen($error)) return $error;

		$rc['rows'] = $rows;//PageArray
		$rc['columns'] = $columns;//PageArray
		$rc['rows_parent'] = $rowsParent;//Page|Empty string
		$rc['columns_parent'] = $columnsParent;//Page|Empty string

		return $rc;

	}

	/**
	* Build the default matrix with blank values (blank matrix->value).
	*
	* We later merge this with saved values from the db.
	* This will help us detect if new row/column pages have been added.
	*
	* @access private
	* @param PageArray $rows Pages to return as matrix rows.
	* @param PageArray $columns Pages to return as matrix columns.
	* @param String $type Page property to save to the returned array.
	* @return Array $defaultMatrix Array with Row and Column matrix/grid with blank values.
	*
	*/
	private function buildDefaultMatrix($rows, $columns, $type = 'id') {
		
		$defaultMatrix = array();
		//create our rows - top level array
		foreach($rows as $row) {
			//create our columns - 2nd level array WITH empty values
			foreach($columns as $column) $defaultMatrix[$row->$type][$column->$type] = '';//value = blank
		}

		return $defaultMatrix;

	}

	/**
	* Build a matrix of saved (db) values.
	*
	* We later merge this with default row/columns expected of this matrix.
	*
	* @access private
	* @param Page $rowsParent To check if matrix row parent has changed.
	* @param Page $columnsParent To check if matrix row parent has changed.
	* @return Array $dbMatrix Array with Row and Column matrix/grid with saved values.
	*
	*/
	private function buildSavedMatrix($rowsParent, $columnsParent) {

		//prepare some variables
		$values = $this->attr('value');
		$pages = $this->wire('pages');

		//get saved db matrix values
		$dbMatrix = array();//for storing row/column values already saved in db

		//loop through saved db values
		foreach($values as $m) {

			//get the row page
			$rp = $pages->get($m->row);
			
			//in case the matrix rows parent was changed and is different from the rows parent of the saved db values...
			//we skip such rows in readiness for deletion
			//we only do this if a Page Field was used to select matrix rows (difficult if a selector/PHP code was used - no problem since assuming only supersuser can edit selector in Page Field)
			if($rowsParent && $rp->parent != $rowsParent) continue;

			//remove matrix-rows that are no longer needed i.e. 'unpublished', 'hidden', 'deleted' or 'trashed'
			if(!$rp || $rp->is(Page::statusUnpublished) || $rp->isHidden() || $rp->isTrash()) continue;
			//if(!$rp || $rp->is('unpublished') || $rp->is('hidden')) continue;//syntax will only work in PW 2.5+ ?

			//build the saved values array
			$dbMatrix[$m->row][$m->column] = $this->sanitizer->entities($m->value);

			//get the column page
			$cp = $pages->get($m->column);

			//remove matrix-columns that are no longer needed i.e. 'unpublished', 'hidden', 'deleted' or 'trashed'
			if(!$cp || $cp->is(Page::statusUnpublished) || $cp->isHidden() || $cp->isTrash()) unset($dbMatrix[$m->row][$m->column]);
			
			//in case the matrix columns parent was changed and is different from the columns parent of the saved db values...
			//we remove such columns in readiness for deletion
			//we only do this if a Page Field was used to select matrix columns (ditto above)
			if($columnsParent && $cp->parent != $columnsParent) unset($dbMatrix[$m->row][$m->column]);
		}

		return $dbMatrix;

	}

	/**
	* Build an array for outputting a Matrix Table/Grid.
	*
	* @return Array $mergedMatrix Array of matrix row/column/values.
	*
	*/
	public function mergeMatrix() {

		//prepare some variables
		$this->inputPrefix = 'matrix_' . $this->field->name;

		$rowsParent = '';
		$columnsParent = '';		
	
		//rows and columns for this matrix
		$rc = $this->findRowsColumns();

		//if we didn't get an array back from findRowsColumns() it means errors were found. We output the returned 'error' strings
		if(!is_array($rc)) {
			$this->error($rc, Notice::allowMarkup);
			return;
		}

		//if we got here, it means no errors found and good to go
		else {
			$rows = $rc['rows'];
			$columns = $rc['columns'];
			$rowsParent = $rc['rows_parent'];//only if Page Field used to build matrix rows
			$columnsParent = $rc['columns_parent'];//only if Page Field used to build matrix columns

		}

		//get saved db matrix values
		$dbMatrix = $this->buildSavedMatrix($rowsParent, $columnsParent);

		//build default matrix grid with empty-values for later merging with any saved db values
		$defaultMatrix = $this->buildDefaultMatrix($rows, $columns);

		//prepare our final matrix to output to page (edit) InputfieldMatrix
		//we recursively replace defaultMatrix blank values with dbMatrix values where applicable (matched array keys)
		//'new' (i.e. not in $dbMatrix) default row/column combinations are preserved and added to final matrix
		//note: values previously saved using a different selector will still be present!...
		//as long as their respective pages have not been deleted/trashed/hid/unpublished
		$mergedMatrix = array_replace_recursive($defaultMatrix, $dbMatrix);

		return $mergedMatrix;//matrix array

	}

	/**
	 * Render the entire input area for a Matrix
	 *
	 */
	public function ___render() {

		//#########	CREATE MATRIX TABLE #########
				
		//send js configurations to the browser
		$this->jsConfigs();

		$mergedMatrix = $this->mergeMatrix();

		//if we didn't get an array back from $mergeMatrix() it means errors were found. We output the returned 'error' strings
		if(!is_array($mergedMatrix)) {
			$this->error($mergedMatrix, Notice::allowMarkup);
			return;

		}

		//get the matrix table's thcols and tbody
		$tableMarkup = $this->buildMatrixTable($mergedMatrix);

		$thcols = $tableMarkup['thcols'];
		$tbody = $tableMarkup['tbody'];
		$rowNumber = $tableMarkup['showRowNumber'];//showing row number?

		//render matrix table/grid
		$out = $this->renderMatrixTable($thcols, $tbody, $rowNumber);

		//import CSV data options
		$importMatrixValues = $this->buildImportExportForm()->render();

		return $out . $importMatrixValues;
	}

	/**
	* Build the matrix table/grid from an array of matrix rows, columns and values.
	*
	* @access private
	* @param Array $mergedMatrix Array with matrix rows, columns and values.
	* @return Array $matrixTableMarkup Array with Table Headers and Columns Markup for the matrix table + if to show row numbering.
	*
	*/
	private function buildMatrixTable($mergedMatrix) {

		$n = $this->inputPrefix;
				
		$matrixTableMarkup = array();

		$pages = $this->wire('pages');
		$showRowsNumbering = $this->showRowsNumbering;//this property was set in FieldtypeMatrix getInputfield()

		$tbody ='';//for matrix rows
		$thcols = '';//for matrix table column headers
		$rowHeaderLabel = $this->rowLabelFieldName;//this property was set in FieldtypeMatrix getInputfield()
		$columnHeaderLabel = $this->columnLabelFieldName;//this property was set in FieldtypeMatrix getInputfield()

		$i = 0;//set counter not to output extraneous column label headers
		$j = 1;//counter for rows numbering
		$count = '';//initialise variable for counting number of columns
		
		foreach($mergedMatrix as $row => $cols) {

				//matrix table row headers (first column)
				$rh = $pages->get($row);//getting by page->id
				#$tbody .= "<tr><td><strong>" . $pages->get($row)->title . "</strong></td>";

				//if we have a row label from selected field show it otherwise show title
				$rowLabel = $rh->$rowHeaderLabel ? $rh->$rowHeaderLabel : $rh->title;
				/*$tbody .= "<tr>
								<td class=MatrixRowCount>" . $j. "</td>
	            				<td>" . $rowLabel. "</td>";
	            				@@left here in case will switch to row counters in the future
	            */

	            //if rows numbering allowed
	            $rowNumber = $showRowsNumbering == 1 ? "<th scope='row' class='MatrixRowNumber'>" . $j . "</th>" : '';
				
				$tbody .= "<tr id='{$this->field->name}_{$rh->id}'>"
							 . $rowNumber .  
							"<td class='MatrixRowHeader'>" . $rowLabel . "</td>";

				//we count this once only rather than on each 'row' loop!
				if($i == 0) $count = count($cols);//help to stop output of extra/duplicate column headers

				foreach($cols as $col => $value) {

							//matrix table column headers
							$ch = $pages->get($col);//getting by page->id

							//if we have a column label from selected field show it otherwise show title
							$columnLabel = $ch->$columnHeaderLabel ? $ch->$columnHeaderLabel : $ch->title;

							//avoid outputting extra duplicate columns. 
							if($i < $count) {
									$thcols .= "<th class='MatrixColumnHeader'>" . $columnLabel  . "</th>";
									$i++;//no need to keep incrementing after number of desired columns reached
							}

							//input name will be in the format 'R5282_C5289' to match row and column page IDs respectively
							$tbody .= "<td><input type='text' name='" . $n . "[R" . $rh->id . "_C" . $ch->id . "]' value='" . $value . "'></td>";

				}

				$tbody .= "<td><input type='checkbox' name='" . $n . "_row_action[]' value='{$rh->id}' data-row='{$this->field->name}_{$rh->id}' class='MatrixCheckbox'></td></tr>";

				$j++;
		}

		$matrixTableMarkup['thcols'] = $thcols;
		$matrixTableMarkup['tbody'] = $tbody;
		$matrixTableMarkup['showRowNumber'] = $showRowsNumbering == 1 ? true : false;

		return $matrixTableMarkup;

	}
	

	/**
	* Render the matrix table/grid with populated values.
	*
	* @access private
	* @param String $thcols Table Headers (thcols) Markup for the matrix table/grid.
	* @param String $tbody Table Body (tbody) Markup for the matrix table/grid.
	* @param Bool $rowNumber Whether to render extra table header needed if showing row numbers.
	* @return String $matrixTable Table Markup of matrix table/grid with populated values.
	*
	*/
	private function renderMatrixTable($thcols, $tbody, $rowNumber = false) {

		$n = $this->inputPrefix;
		
		//for special CSS class if user using AdminThemeReno
		$extraCSSClass = $this->adminTheme == 'AdminThemeReno' ? 'Reno' : '';

		$this->tableID = $tableID = 'Inputfield_' . $this->field->name;

		//export button
		$btn = $this->modules->get('InputfieldSubmit');
		$btn->attr('name', $n . '_export');
		$btn->attr('data-table', $tableID);//in case there's more than one matrix table on this page we only want to export data from the 'one' table
		$btn->class .= ' MatrixExport' . $extraCSSClass;
		$btn->attr('value', $this->_('Export Data'));
		$exportDataButton = $btn->render();

		//button to reset/clear all matrix values before save
		$btn = $this->modules->get('InputfieldButton');
		$btn->attr('data-table', $tableID);//in case there's more than one matrix table on this page we only want to clear data from the 'one' table
		$btn->class .= ' MatrixReset' . $extraCSSClass;
		$btn->attr('value', $this->_('Clear Data'));
		$clearAllButton = $btn->render();

		//hidden input to store id of 'last blank row' to use if import is in 'append mode'
		$lastBlankRow = '<input type="hidden" name="' . $n . '_rowid" value="" class="MatrixLastBlankRow" data-table="' . $tableID . '">';

		//extra column table header if row numbering enabled
		$extraTH = $rowNumber ? '<th></th>' : '';

		//to check if saving blank values allowed (yes=1; no=2)		
		$saveBlankValuesNote = $this->allowBlankValues == 1 ? $this->_('Empty values will be saved;') : $this->_('Empty values will not be saved;');//only superuser will see this
		$importMode = $this->defaultImportMode == 1 || $this->defaultImportMode == '' ? 
					$this->_('In the current default setting, imported CSV data will be appended beginning at the first blank row (highlighted in the table if \'append\' is selected in the import settings below). Any values below that row will be overwritten. Select \'overwrite\' to change this behaviour.') :
					$this->_('In the current default setting, imported CSV data will overwrite all existing values. Select \'append\' to change this behaviour.');
		$tableNotes = '<p class="notes"> ' . ($this->user->isSuperuser() ? $saveBlankValuesNote : '') .  ' '  . $importMode . '</p>';

		//final matrix table for output
		$matrixTable =   "
					$lastBlankRow
					$tableNotes
					$exportDataButton
					$clearAllButton
		 			<table id='$tableID' class='Matrix'>
						<thead>
							<tr class=''>
								$extraTH
								<th></th>
								$thcols
								<th><input type='checkbox' class='MatrixToggleAll' data-table='$tableID'></th>
							</tr>
						</thead>
						<tbody>
							$tbody
						</tbody>
					</table>					
					$exportDataButton
					$clearAllButton
		";

		return $matrixTable;

	}

	/**
	* Outputs javascript configuration for this module.
	*
	* @access protected
	* @return String $scripts String to send to browser.
	*
	*/
	protected function jsConfigs() {

		//options for js 
		#$options = array('config' => array("cdAlertMsg_$this->field->name" => $this->cdAlertMsg, 'matrixName' => ));
		$options = array("config" => array(
							"cdAlertMsg" => $this->cdAlertMsg, 
							#"matrixName" => $this->field->name,

						)
		);
		#$scripts = $this->config->js($this->className(), $options);
		$scripts = $this->config->js($this->id, $options);

		return $scripts;

	}	
	
	/**
	 * Process input for the values sent from the Matrix table for this page
	 *
	 */
	public function ___processInput(WireInputData $input) {


		if(!$this->page || !$this->field) {
			throw new WireException("This inputfield requires that you set valid 'page' and 'field' properties to it."); 
		}

		$name = 'matrix_' . $this->attr('name');

		$csvFilename = $_FILES["{$name}_csvfile"]["name"];
		$csvPasted = $input->{"{$name}_csvpasted"};
		$csvDelimiter = $input->{"{$name}_csv_column_separator"};
		$csvEnclosure = $input->{"{$name}_csv_column_enclosure"};
		$csvExportBtn = $input->{"{$name}_export"};
		$rowsChecked = $input->{"{$name}_row_action"};
		$this->csvImportMode = $input->{"{$name}_importmode"};
		$this->lastBlankRowID = $input->{"{$name}_rowid"};
		$this->csvIgnoreFirstRow = $input->{"{$name}_ignore_first_row"};
		$this->csvIgnoreFirstColumn = $input->{"{$name}_ignore_first_column"};


		######### - EXPORTING - #########
		if($csvExportBtn && is_array($rowsChecked)) {

			//get default rows and columns. Need this to ensure to export blank values as well to CSV, otherwise file will be skewed.
			$rc = $this->findRowsColumns();

			$rows = $rc['rows'];//PageArray
			$columns = $rc['columns'];//PageArray	

			$values = $this->attr('value');

			$exportMatrix = array();

			//prepare export values
			foreach($rows as $row) {

				//only export selected rows
				if(!in_array($row->id, $rowsChecked)) continue;

				foreach($columns as $column) {
					//get each matrix value at given coordinates (WireArray)
					$v = $values->get("rowLabel=$row->title, columnLabel=$column->title");
					$value = $v ? $v->value : '';//force blank values export
					$exportMatrix[$row->id][$this->_('Row Label')] = $row->title;
					$exportMatrix[$row->id][$column->title] = $value;
				}
			}

 			//execute export
 			$this->exportMatrixCSV($exportMatrix, $csvDelimiter, $csvEnclosure);

		}

		######### - IMPORTING/SAVING - #########

		//if dealing with imported csv/txt file
		elseif($csvFilename !='') {

				//WireUpload stuff
				$validExts = array('txt', 'csv');//allow only .csv and .txt files

				$csvFileProcess = new WireUpload("{$name}_csvfile");//name of csv file upload <input>
				$csvFileProcess->setOverwrite(true);//overwrite files
				$csvFileProcess->setMaxFiles(1);//only allow one file!
				$csvFileProcess->setDestinationPath($this->page->filesManager()->path());//temporarily upload to current page's /assets/files/
				$csvFileProcess->setValidExtensions($validExts);//check for valid file extensions

				//upload the csv/txt file
				$file = $csvFileProcess->execute();
				
				//if no valid file found, show error message and abort
				if(!count($file)) {
					$this->error($this->_('You need to upload a file with a valid extension!'));
					return false;
				}
				
				$csvTempFileName = 'matrix-temp-data.csv';
				$csvFilePath = $this->page->filesManager()->path;
				
				//rename the file including its extension
				$csvRenameFile = rename($csvFilePath . $csvFilename, $csvFilePath . $csvTempFileName);//returns true on success
				
				//if file successfully renamed
				if($csvRenameFile) $csvRawData = $this->page->filesManager()->path . $csvTempFileName;//full path to our temp csv file

				//first just double checking we got the renamed file. we pass this to prepareCSV()
				if(is_file($csvRawData)) {
						$matrices = $this->prepareCSV($csvRawData, $csvDelimiter, $csvEnclosure);
				}

				else {
						$this->error($this->_('We did not find a valid file! Please retry.'));
						return false;
				}

		}

		//dealing with copy-pasted csv values
		elseif($csvPasted !='') {

					$csvRawData = $csvPasted;
					$matrices = $this->prepareCSV($csvRawData, $csvDelimiter, $csvEnclosure);

		}

		//if no file or no copy-pasted values, we are dealing with manually entered matrix values (i.e. none-CSV data)
		else {

				$matrices = $this->field->type->getBlankValue($this->page, $this->field);

				$count = 0;//counter for values saved

				//to check if saving blank values allowed (yes=1; no=2)
				$saveBlankValues = $this->allowBlankValues;
				
				foreach($input->{"{$name}"} as $key => $value) {
						
					//if value empty and saving blank values not allowed, we skip the record
					if($saveBlankValues == 2 && !strlen(str_replace(' ', '', $value))) continue;

					//$key is in the format R1234_C1234 reflecting row and column pages' IDs respectively
					$rowCol = explode('_', $key);//[0]=>R1234, [1]=>C1234

					$row = str_replace('R', NULL, $rowCol[0]);//clean row page ID
					$column = str_replace('C', NULL, $rowCol[1]);//clean column page ID

					//create a new matrix and add it to our matrices
					$m = new Matrix();

					$m->row = (int) $row;//@@note - don't really need to sanitize here as well since done in Matrix::set() 
					$m->column = (int) $column;//@@note - ditto
					$m->value = $value;

					$matrices->add($m);//add matrix to MatrixArray

					$count++;

				}//end foreach

				//tell user how many values were saved
				$this->message($this->field->name . ': ' . sprintf(_n("Saved %d matrix value.", "Saved %d matrix values.", $count), $count));

		}
	
		//if the string values of the processed matrices are different from the previous,
		//or if any matrices have been deleted, then flag this Inputfield as changed
		//so that it will be automatically saved with the page
		
		//if things have changed, we take the new values
		if("$matrices" != "$this->value") {
			
				$this->attr('value', $matrices);
				$this->trackChange('value'); 
		}
		

	}

	/**
	 * Prepare copy-pasted or uploaded CSV matrix values for processing
	 * These will either be processed using MatrixArray/Matrix or MySQL LOAD DATA INFILE
	 *
	 */
	public function prepareCSV($csvRawData, $csvDelimiter, $csvEnclosure) {		
		
		$lastBlankRowID = (int) str_replace($this->field->name . '_', '', $this->lastBlankRowID);
		$csvImportMode = (int) $this->csvImportMode;

		//abort early if in 'apend mode' but there was no last blank/empty row. helps avoid overwriting saved values
		if($csvImportMode === 1 && !$lastBlankRowID) {
			$this->error($this->field->name . ': ' . $this->_('There are no rows to append to! Nothing saved.'));
			return;
		}

		$values = $this->attr('value');
		$rows = array();
		$columns = array();
		$rowsKeep = array();//if in append mode, we'll store ids of rows above 'last blank row' so as to avoid overwriting them
		$mergedRowsColsKeep = array();//merge rows 'to keep' to their corresponding columns
		$options = array();
		$data = array();//output to return

		//rows and columns for this matrix
		$rc = $this->findRowsColumns();

		//if we didn't get an array back from findRowsColumns() it means errors were found. We output the returned 'error' strings
		if(!is_array($rc)) {
			$this->error($rc, Notice::allowMarkup);
			return;
		}

		//if we got here, it means no errors found and good to go
		else {
			$rowPages = $rc['rows'];
			$columnPages = $rc['columns'];
		}

		$a = 0;
		foreach ($rowPages as $row) {			
			//if in append mode
			if($csvImportMode === 1 && $lastBlankRowID) {
				if($row->id === $lastBlankRowID) $a = 1;
				if(!$a) {
					$rowsKeep[] = $row->id;//if we got here, these are rows above 'last blank row'; we want to preserve their original values
					continue;
				}
			}

			$rows[] = $row->id;//in append mode, only contains rows starting from 'last blank row' and below, inclusive
		}

		$cntRows = count($rows);

		//if ignore first column (row labels) set, temporarily add a fake top col with col->id = 0 for filtering out later
		if($this->csvIgnoreFirstColumn == 1) $columns[] = 0;
		foreach ($columnPages as $col) $columns[] = $col->id;
		$cntCols = count($columns);//irrespective of import mode, we always have all columns
	
		//merged rows to keep with corresponding columns
		foreach ($rowsKeep as $r) {
			foreach ($columns as $c) {
				$v = $values->get("row=$r, column=$c");//preserve 'rows to preserve' values
				$value = $v ? $v->value : '';//blank if no value

				$mergedRowsColsKeep[] = array((int)$r, (int)$c , $this->sanitizer->text($value));
			}
		}
	
		//if no $csvDelimiter set, throw error, return! rather than assume default ',' [comma]
		if(!$csvDelimiter) {
				$this->error($this->_('A CSV delimiter has to be set!'));
				return;
		}

		
		$i = 0;//rows counter
		$j = 0;//columns counter		
		
		/*					
		#### creating an array mirroring our db structure ###
		save row->id, col->id, csv value as below:

			array (

						[0] =>	array (

										[0] => row->id
										[1] => col-id
										[2] => value
						)

			)

		*/
		
		/*
			++ if importing/copy-pasting csv data, we'll use this array in one of two ways: ++

			(1) if using LOAD DATA INFILE:				
				- we need this step since our $csvRawData is in a matrix table format
				- there'll be no way to flip the values using LOAD DATA INFILE to correctly insert the row,column,value data in the db
				- So, we have to do it this way
		
			(2) if saving csv values using 'normal' MatrixArray/Matrix method
				- we'll later use the array with new Matrix() to save values to db
		*/

		$options['data'] = $csvRawData;						
		$options['delimiter'] = $csvDelimiter;
		$options['enclosure'] = $csvEnclosure;
		$options['rows'] = $rows;
		$options['count_rows'] = $cntRows;
		$options['columns'] = $columns;		
		$options['count_columns'] = $cntCols;

		//@@note: split code to separate methods
		if(is_file($csvRawData)) $data = $this->prepareCSVFile($options);//if csv file uploaded [matrix-temp-data.csv]
		else $data = $this->prepareCSVCopyPaste($options);//if csv copy pasted

		//merge to be appended values to those to be preserved as well as their rows and columns
		$data = array_merge($data, $mergedRowsColsKeep);
		
		//if user chose to use LOAD DATA INFILE (this property was set in FieldtypeMatrix getInputfield())
		if ($this->loadDataInfile) {
				$this->processCSVLoadDataInfile($data, $csvDelimiter == "tab" ? chr(9) : $csvDelimiter, $csvEnclosure);
				return;//back to base after processing
		}

		else {
				return $this->processCSVMatrix($data);//this will return $matrices

		}
		

	}

	/**
	 * Prepare uploaded CSV matrix values for processing
	 * These will either be processed using MatrixArray/Matrix or MySQL LOAD DATA INFILE
	 *
	 */
	private function prepareCSVFile($options) {

		$data = array();
		$i = 0;//rows counter
		$j = 0;//columns counter
		$n = 0;//for skipping first row if specified

		$csvRawData = $options['data'];
		$csvDelimiter = $options['delimiter'];
		$csvEnclosure = $options['enclosure'];
		$rows = $options['rows'];
		$cntRows = $options['count_rows'];
		$columns = $options['columns'];		
		$cntCols = $options['count_columns'];

		$csvFilename = $csvRawData;

		//deal with Mac line endings
		ini_set('auto_detect_line_endings', true);
		
		//open our csv file as read-only
		$handle = fopen($csvFilename, "r");

		//convert csv string to array
		//we also check delimiter type here - chr(9) is ASCII standard character for TAB
		while(($csvData = fgetcsv($handle, 0, $csvDelimiter == "tab" ? chr(9) : $csvDelimiter, $csvEnclosure)) !== false) {
			//$cnt = count($data);

			$n++;
			if($this->csvIgnoreFirstRow == 1 && $n == 1) continue;//ignore first row if requested
			foreach ($columns as $col) {
					
				//first, attempt to auto-detect char encoding of 'troublesome' characters
				//then encode to UTF-8
				$value = $this->charEncode($csvData[$j], 'UTF-8');
				
				$data[] = array((int)$rows[$i], (int)$col , $this->sanitizer->text($value));
				#$data[] = array( (int)$rows[$i], (int)$col , $this->sanitizer->text($csvData[$j]));					
				$j++;
				if($j == $cntCols) break;//if csv data columns exceed columns in matrix table we abort
			
			}//end foreach $columns as $col

			$i++;
			$j=0;//reset the column counter for next loop
			if($i == $cntRows) break;//if csv data rows exceed rows in matrix table we abort

		}//end while $csvData...

		fclose($handle);//close the resource stream
		ini_set('auto_detect_line_endings', false);//close auto detect line endings		
		
		if(is_file($csvRawData)) unlink($csvRawData);//delete 'matrix-temp-data.csv'

		return $data;

	}


	/**
	 * Prepare copy-pasted  CSV matrix values for processing
	 * These will either be processed using MatrixArray/Matrix or MySQL LOAD DATA INFILE
	 *
	 */
	//private function prepareCSVCopyPaste ($csvRawData, $csvDelimiter, $csvEnclosure, $columns, $rows, $cntRows, $cntCols) {
	private function prepareCSVCopyPaste ($options) {

		$data = array();
		$i = 0;//rows counter
		$j = 0;//columns counter
		$n = 0;//for skipping first row if specified

		$csvRawData = $options['data'];
		$csvDelimiter = $options['delimiter'];
		$csvEnclosure = $options['enclosure'];
		$rows = $options['rows'];
		$cntRows = $options['count_rows'];
		$columns = $options['columns'];		
		$cntCols = $options['count_columns'];

		//loop through the raw csv values line by line prepping our CSV values for later processing
		foreach(explode("\n", $csvRawData) as $row) {

				$n++;
				if($this->csvIgnoreFirstRow == 1 && $n == 1) continue;//ignore first row if requested
				
				//convert csv string to array. Also check delimiter type - chr(9) is ASCII standard character for TAB
				$csvData = str_getcsv($row, $csvDelimiter == "tab" ? chr(9) : $csvDelimiter, $csvEnclosure);	        
		        
				foreach ($columns as $col) {						
						$data[] = array((int)$rows[$i], (int)$col , $this->sanitizer->text($csvData[$j]));
						$j++;
						if($j == $cntCols) break;//abort if csv data columns exceed columns in matrix table
				}

				$i++;
				$j=0;//reset column counter for next loop
				if($i == $cntRows) break;//abort if csv data rows exceed rows in matrix table
						
		}

		return $data;


	}

	/**
	 * Process copy-pasted and uploaded CSV matrix values using MatrixArray/Matrix method
	 *
	 */
	public function processCSVMatrix($data) {

		$matrices = $this->field->type->getBlankValue($this->page, $this->field);

		$count = 0;//counter for number of values saved

		//to check if saving blank values allowed (yes=1; no=2)
		$saveBlankValues = $this->allowBlankValues;

		//loop through the sanitized csv data. Empty values will be removed if in saveBlankValues mode
		foreach ($data as $d) {
				
				if($d[1] == 0) continue;//if ignoring first column
		  
				#our row $page->id is at index[0] in the inner array $d
				#our column $page->id is at index[1] in the inner array $d
				#our matrix intersection/cell is the $value and it is at index[2] in array $d

					//create a new matrix and add it to our matrices
					$m = new Matrix();

					//skip blank values if saving them not allowed
					if($saveBlankValues == 2 && !strlen(str_replace(' ', '', $d[2]))) continue;
					
					//these were already sanitized in prepareCSV() [and will be again in Matrix::set()]
					$m->row		= 	$d[0];//row page->id
					$m->column 	= 	$d[1];//column page->id
					$m->value 	= 	$d[2];//csv value

					$matrices->add($m);//add matrix to MatrixArray

					$count++;

		}//end foreach $data as $d

		$this->message($this->field->name . ': ' . sprintf(_n("Saved %d matrix value.", "Saved %d matrix values.", $count), $count));//tell user how many values were saved

		return $matrices;//return the matrices object

	}

	/**
	 * Process copy-pasted CSV matrix values
	 *
	 */
	public function processCSVLoadDataInfile($data, $csvDelimiter, $csvEnclosure) {

		//prepare some variables
		$page = $this->page;

		//to check if saving blank values allowed (yes=1; no=2)
		$saveBlankValues = $this->allowBlankValues;

		$csvFilename = $page->filesManager()->path() . 'matrix-data.csv'; //this pages /assets/files/ folder

		//deal with Mac line endings
		ini_set('auto_detect_line_endings', true);

		//force create and write to a temp 'matrix-data.csv' file. we'll delete it later
		$handle = fopen($csvFilename, 'w+');

		foreach ($data as $line) {

			if($line[1] == 0) continue;//if ignoring first column, skip first columns

			//skip blank values if saving them not allowed
			if($saveBlankValues == 2 && !strlen(str_replace(' ', '', $line[2]))) continue;

			fputcsv($handle, $line, $csvDelimiter, $csvEnclosure);//write csv values to matrix-data.csv
		}

		fclose($handle);//close the resource stream
		ini_set('auto_detect_line_endings', false);//close auto detect line endings

		//$database is the ProcessWire PDO way.
		$database = $this->wire('database');
		$table = $database->escapeTable($this->field->table);//see /wire/core/Fieldtype.php. returns 'field_name_of_field' (i.e. as in the database)

		//we need to delete this page's older db values
		$sql = "DELETE FROM `$table` WHERE pages_id=:page_id";//need backticks around $table
		
		$query = $database->prepare($sql);//prepare delete statement
		$query->bindValue(":page_id", $page->id, PDO::PARAM_INT);//bind our named parameter
		$query->execute();//delete values

		//LOAD DATA INFILE statement
		//In Multipage-like fields, ProcessWire uses a Composite PRIMARY KEY made up of 'pages_id' and 'sort'
		//Since there can be multiple identical 'pages_id', 'sort' has to be unique always
		//We start sort from 0 and increment this for each db record
		$sql = "				
				SET @i:=-1;
				LOAD DATA INFILE :csvFilename
				INTO table `$table`
				FIELDS TERMINATED BY :csvDelimiter
				OPTIONALLY ENCLOSED BY :csvEnclosure
				LINES TERMINATED BY '\\n'
				(data, matrix_column, matrix_value)
				SET 
					pages_id =:page_id,
					sort = @i:=@i+1;
		
		";

		$query = $database->prepare($sql);//prepare LOAD DATA INFILE statement
		$query->bindValue(":csvFilename", $csvFilename);//bind our named parameters
		$query->bindValue(":csvDelimiter", $csvDelimiter);
		$query->bindValue(":csvEnclosure", $csvEnclosure);
		$query->bindValue(":page_id", $page->id, PDO::PARAM_INT);
		$query->execute();//let's write some data

		$sql = "SELECT COUNT(*) FROM `$table` WHERE pages_id=:page_id";

		$query = $database->prepare($sql);//prepare count number of newly written values
		$query->bindValue(":page_id", $page->id, PDO::PARAM_INT);//bind our named parameter
		$query->execute();//execute our count

		$count = $query->fetchColumn();//fetch the count

		if(is_file($csvFilename)) unlink($csvFilename);//delete the matrix-data.csv file we created earlier for LOAD DATA INFILE

		$this->message($this->field->name . ': ' . sprintf(_n("Saved %d matrix value.", "Saved %d matrix values.", $count), $count));//tell user how many values were saved

	}

	/**
	* Export saved/DB matrix to a CSV file for download.
	*
	* This is useful if user wants to user data for other purposes.
	* Also, in some cases,it is easier to edit data in a spreadsheet then re-import to the matrix.
	* 
	* @access private
	* @param Array $data Saved/DB matrix values to export to CSV.
	* @param String $csvDelimiter CSV data delimiter.
	* @param String $csvEnclosure CSV data enclosure.
	*
	*/
	private function exportMatrixCSV($data, $csvDelimiter, $csvEnclosure) {

		if (count($data) == 0) return null;

		date_default_timezone_set($this->config->timezone);//get current timezone
		#$dateFormat = $this->config->dateFormat;//get default date format (@note: not using since may contain illegal filename characters for different operating systems)
		$date = date('Y-m-d-H-i-s', time());

		//name csv files as pageName_matrixFieldName_currentTime.csv
		$csvFileName = $this->page->name . '_' . $this->attr('name') . '_' . $date . '.csv';

		//force download. disposition / encoding on response body
		header('Content-type: text/csv');
		header("Content-Disposition: attachment;filename={$csvFileName}");

		//disable caching
		header('Pragma: no-cache');
		header('Expires: 0');

		//open resource stream
		$f = fopen("php://output", 'w');

		//keys of associative array $data will be the column headers
		fputcsv($f, array_keys(reset($data)), $csvDelimiter, $csvEnclosure);

		//write to csv file
		foreach ($data as $row) fputcsv($f, $row, $csvDelimiter, $csvEnclosure);

		//close resource
		fclose($f);
		
		//stop any further output
		exit;		

	}

	/**
	 * Attempt to auto-encode unrecognised characters during fopen operations.
	 * If detection fails, at least values are parsed without ??
	 *
	 * @author aaron@aarongough.com - php.net
	 *
	 */
	public function charEncode ($source, $targetEncoding) {
		
		//detect the character encoding of the incoming file
		$encoding = mb_detect_encoding($source, "auto");

		//escape all of the question marks so we can remove artifacts from
		//the unicode conversion process
		$target = str_replace( "?", "[question_mark]", $source );

		//convert the string to the target encoding
		$target = mb_convert_encoding( $target, $targetEncoding, $encoding);

		//remove any question marks that have been introduced because of illegal characters
		$target = str_replace( "?", "", $target );

		//replace the token string "[question_mark]" with the symbol "?"
		$target = str_replace( "[question_mark]", "?", $target );

		return $target;

	}



}