TextFit class v1.1.3 2012-12-05
===============================================================================
http://tweezy.net.au/TextFit.html
TextFit is a simple PHP5 class that does a couple of things:
1. Shorten a text string
------------------------
Strings can be shortened to fit within a specific number of characters.
Two methods are available for this - shortenText() trims excess characters
from the end of the string, and shortenFilename() trims excess characters from
the middle, keeping the file extension.
2. Display text in columns
--------------------------
Text values can be displayed in columns, somewhat like a table (for use with
fixed-width fonts, eg in a plain-text email). The principal methods for this
are fitTextRow() which produces a row of strings from an array in fixed-width
columns, and fitTextLine() which produces a horizontal line spanning all columns.
Example output:
Name | Age | Country | Amount
===================================================
Nguyen Thi Anh | 40 | Vietnam | 2,108.50
S. Baldrick | 36 | England | 14.75
Michael Bruce | 28 | Australia | 648.15
Buck Gregson | 48 | USA | 4,444.44
---------------------------------------------------
(note that a fixed-width font must be used to line up the columns properly)
===============================================================================
The remainder of this document is a complete reference for the TextFit class.
FOR A QUICK START, see examples.php
===============================================================================
I N S T A N T I A T I O N
-------------------------
The TextFit class can be instantiated with one or more of the parameters
listed below. If any of these is missing or null, a default value will be used.
The values for these can also be changed individually after instantiation, by
calling the appropriate set-- method.
$Columns ....... for info see setColumns() method
$WrapText ...... (default=false) for info see setWrap() method
$AddExtraRow ... (default=false) for info see setAddRow() method
C L A S S M E T H O D S
-------------------------
_____________________________________________________________________________________________
For simple text or filename shortening, use shortenText or shortenFilename.
These methods do not required class instantiation - that is, they may be called
statically. For example:
$s = TextFit::shortenText('Here is some quite long string', 15);
_____________________________________________________________________________________________
shortenText($text, $chars, $ForceCutoff, $UseEllipsis)
------------------------------------------------------
Trims excess characters from the end of a string.
$text ......... the string to be shortened if necessary (no default - must be supplied)
$chars ........ (default=40) The maximum number of characters desired. If $text is longer
than this it will be shortened to fit into $chars characters
$ForceCutoff .. (default=false) If true, $text will be shortened to exactly $chars characters
without regard for word boundaries. If false, the text will try to keep whole
words intact, and as a result will often shorten the text to slightly
less that $chars characters.
$UseEllipsis .. (default=false) If true, shortened text will be appended with an ellipsis
character. If false, three dots are used.
shortenFilename($text, $chars, $UseEllipsis)
--------------------------------------------
Trims excess characters from the middle of a filename, keeping the file extension.
$text ......... Text containing the filename to be shortened if necessary, which must
end with a file extension (eg .doc)
$chars ........ (default=40) Maximum number of characters desired. If $text is longer
than this, excess characters will be removed from the middle of the
string, keeping the file extension
$UseEllipsis .. (default=false) If true, omitted text will be replaced by an ellipsis
character. If false, three dots are used.
_____________________________________________________________________________________________
The other methods are concerned with displaying fixed-width text in columns, and can only be
called after instantiating the class.
_____________________________________________________________________________________________
fitTextRow($RowValues, $PadChar)
--------------------------------
Produces a row of strings in fixed-width columns
$RowValues .. an array of strings, one for each column
$PadChar .... the character use to expand short strings to the correct width
(default=space, or the character previously set by setPadChar)
See also: setRowChar()
fitTextLine($Char, $ColSpan)
----------------------------
Produces a line that spans all columns, using the $Char character (default '-').
If $ColSpan is specified, only spans that number of columns - this is
NOT recommended if you are using setLineChar() or setRowChar().
See also: setLineChar()
fitTextBlank($PadChar)
----------------------
Essentially the same as fitTextRow, but with empty strings to create a blank line.
$PadChar is the character use to expand each column to the correct width
(default=space, or the character previously set by setPadChar)
fitTextRows($RowValues, $AddHeading, $LineChar)
-----------------------------------------------
Produces multiple rows of strings from a multi-row array, with an optional heading row.
$RowValues .... multi-row array (see examples.php)
$AddHeading ... (default=false) If true, a heading row is generated from the subarray indexes
$LineChar ..... (default=true) If AddHeading is true, $LineChar can set a line above and/or
below the heading. $LineChar can be boolean, or a 1 or 2 character string
1 char: adds lines above and below using that char
2 char: adds line above with 1st char, line below with 2nd char
- use N for no line; so 'N=' means no line above, line of '=' below
true: adds lines of '=' above and below (same as '=' or '==')
false: no lines (same as 'N' or 'NN')
fitTextList($List, $FillDown, $AutoWidth)
-----------------------------------------
Produces multiple rows from a simple array of strings
$List ......... A simple array of strings (see examples.php)
$FillDown ..... (default=true) If true, values are listed down the first column, then
the second, etc. If false, values are listed row by row.
$AutoWidth .... (default=false) If true, the widths set with setColumns() are ignored,
and all columns will be the size of the longest string in $List (no word
wrapping!). Any column 'align' and/or 'case' settings will still be used.
$AutoWidth can also be an integer specifying the number of columns
to use; in this case you don't need to call setColumns() at all
(and if you do, it will be ignored).
_____________________________________________________________________________________________
The methods starting with "set" are used to change various preferences (some of which
can be set at instantiation). The "set" methods are listed here in alphabetical order.
_____________________________________________________________________________________________
setAddRow($AddExtraRow)
-----------------------
If $AddExtraRow is boolean true, a blank line will be added after each text row.
If $AddExtraRow is a string, fitTextLine will be added using that character.
This method is especially useful for spacing rows when $WrapText is true - see
setWrap() method.
setColumns($Columns)
--------------------
Defines the width, and optionally alignment and letter case of each column.
In its simplest form $Columns can be a positive integer, which will set the
default width for all columns. The caveat with this is that all columns will
be left-aligned, and you must call fitTextRow (which confirms the number of
columns) before calling fitTextLine.
EXAMPLE 1: setColumns(30);
For more control, $Columns can be an array of column attributes; one array element
per column. Each element in the array may be an integer (width of the column), or
a subarray with one or more of these indexes:
width ... width in characters (int)
align ... left|right|centre|center (string)
case .... upper|lower|proper|keep (string)
EXAMPLE 2: setColumns( array(20, 5, 30) )
EXAMPLE 3: setColumns( array(10, array( 'width'=>10, 'align'=>'right' )) )
Example 3 will set two columns of width 10 characters, the second being right aligned
setDefaultWidth($DefaultWidth)
------------------------------
Sets the width of any columns that don't have a width specified (default=20)
setEchoOn($EchoOn)
------------------
If $EchoOn is true the fitText__ methods will echo their result. If false, they
will return it as a string, and the calling script is responsible for any output.
The default value for the $EchoOn parameter is true, however if you don't call
setEchoOn at all, the default value for $EchoOn is false.
setEOL($EOL)
------------
Sets the character/s to append to the end of each line (default \r\n)
setIndent($Indent)
------------------
Indents the "table" by prepending $Indent spaces to each row.
setLineChar($Separator, $LeftChar, $RightChar)
----------------------------------------------
Sets an optional column separator character, and/or left and right border of lines.
For more information see setRowChar().
This method does NOT specify the character used for drawing lines - see fitTextLine()
setPadChar($PadChar)
--------------------
Sets the character used to pad each column to make it a fixed width.
The default is space, which very rarely needs to be changed.
If you're not calling fitTextLine(), $PadChar can be more than one
character (eg multiple spaces); this is useful to add extra padding
when using fitTextList() with AutoWidth.
setRowChar($Separator, $LeftChar, $RightChar)
---------------------------------------------
Sets an optional column separator character, and/or left and right border
for text rows. See also: setLineChar().
$Separator .. if not specified or empty, a single space is used
$LeftChar ... if not specified or empty, no character is used
$RightChar .. if not specified, same as $LeftChar
Example: To generate a table like below, you would call
setRowChar('|', '|');
setLineChar('+', '+');
+----------+----------------+
| Column 1 | Column 2 |
+----------+----------------+
| Text | More text |
+----------+----------------+
| Text | More text |
+----------+----------------+
| Text | More text |
+----------+----------------+
setWrap($WrapText, $MaxLines)
-----------------------------
If $WrapText is true, long text is wrapped within each column. If false (default),
long text is shortened to fit on one line in each column. If you call setWrap(true),
you should also consider calling setAddRow(true).
|
Download
