Subversion Repositories smartshort

[/] [docs/] [readme.txt] - Blame information for rev 1

Details | Compare with Previous | View Log

Line No. Rev Author Line
1 1 steven.bailey
Explanation
2
-------------------------------
3
The smartshort template operator shortens input strings like the shorten
4
template operator but with a few important differences - most of the time
5
it will break at the end of a sentence and it will not break html tags.
6
 
7
The problem with the default shorten template operator is that it's a substring
8
of the input, so it will break wherever it will land... including in the middle
9
of a word.  Another problem is that if the input is an xml block with tags those
10
could end in the middle of a html tag and mess up the layout of the rest of
11
the page.  Or, with a long tag - which wouldn't be visible but would count in
12
the total for the sub string - would make the visible string too short.
13
 
14
Since practically all of our customers want minimal html tags in their line
15
views (see the strip_except template operator) - and want their line views
16
to all be shortened - it has always been problematic and up until now we've
17
only been able to allow self-closing tags or the content editors had to edit
18
the line view text block attribute carefully so that no html tags would be
19
stranded.  That didn't always happen.  Especially with user-generated content.
20
 
21
What smartshort will do is take the string and find the nearest end of
22
sentence punctuation and, if the length of the string (not including html tags)
23
at that point is less than the user-defined percentage of deviation,  break
24
the text block there.
25
 
26
If the length of the string at that point is more than the percentage of
27
deviation, then the string will be shortened to the white space nearest the
28
length set in the template.  if the length of the string at this point is
29
still bigger than the user-defined percentage of deviation, (which could happen
30
with a long run-on word and a short length) then it will break at the character
31
like the existing shorten.
32
 
33
The tags will be inserted but will not count toward the string length - since
34
they are hidden.  While calculating the length of the string, the
35
non-self-closing html tags are kept in an array, and if there are still open
36
tags when the string is to be displayed, those tags will be closed.  That list
37
of tags is user-defined.
38
 
39
Installation
40
-------------------------------
41
 
42
1) Put this extension's folder in the "extension" directory under the root of
43
   the ezp site.
44
 
45
2) Open the appropriate site.ini and add ActiveExtensions[]=smartshort (in the
46
   case of the override site.ini) or ActiveAccessExtension[]=smartshort to the
47
   [ExtensionSettings] block.
48
 
49
3) Usage in templates:
50
   {$attribute.content.output.output_text|smartshort([<int>],[<string>])}
51
 
52
   1st parameter: length to cut text block (default 80)
53
   2nd parameter: sequence to display at the end of the text block.
54
 
55
   More settings can be found in module.ini
56
 
57
   Specifically, a list of the tags that it will close if they are hanging and
58
   the percentage of the length of the input string at which it will go to the
59
   next level down of where it will split.
60
 
61
 
62
Version history:
63
-------------------------------
64
* Release 1.1: Initialized variables to remove PHP Notice. Rebranded copyright.  Added extension.xml. Fixed typos.  Removed vestigial trim_type.
65
* Release 1: initial release
66
 
67
 
68
Disclaimer & Copyright:
69
-------------------------------
70
/*
71
    smartshort extension for eZ publish 4.x
72
    Copyright (C) 2011 Leiden Tech
73
 
74
    This program is free software; you can redistribute it and/or modify
75
    it under the terms of the GNU General Public License as published by
76
    the Free Software Foundation; either version 2 of the License, or
77
    (at your option) any later version.
78
 
79
    This program is distributed in the hope that it will be useful,
80
    but WITHOUT ANY WARRANTY; without even the implied warranty of
81
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
82
    GNU General Public License for more details.
83
*/