PHP Classes

File: TextFit.doc.txt

Recommend this page to a friend!
  Classes of Tony  >  Text Fit  >  TextFit.doc.txt  >  Download  
File: TextFit.doc.txt
Role: Documentation
Content type: text/plain
Description: Usage information
Class: Text Fit
Shorten text to fit within a limited length
Author: By
Last change: version update
Date: 9 years ago
Size: 12,701 bytes


Class file image Download
TextFit class v1.1.3 2012-12-05 =============================================================================== 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).