Permalink
Browse files

extension support + contrib info

and renamed 'filters' to 'extensions'
  • Loading branch information...
m3nt0r committed Jun 10, 2012
1 parent 722d902 commit f67225d017ba4f7583fdf7f3fefb30580e7a6372
Showing with 531 additions and 42 deletions.
  1. +57 −0 README.md
  2. +77 −0 extensions/i18n.php
  3. +80 −0 extensions/number.php
  4. +107 −0 extensions/text.php
  5. +136 −0 extensions/time.php
  6. +74 −42 views/twig.php
View
@@ -125,6 +125,63 @@ A more complex example, FormHelper inputs:
})
}}
+## CakePHP-powered Filters
+
+The View class adds some sugar to templates by exposing some Helper methods through filters. It features the most common and useful ones. If you think i've left out an important method, geel free to extend the filter (see ```./extensions``` folder) and send me a pull request.
+
+By default all filter sets (helpers) are enabled. Currently available are:
+
+- time
+- number
+- text
+- i18n
+
+You can disable any of them by setting ```Configure::write('TwigView.extensions')``` with an list of extensions
+you want (lowercase, like above). If you want to disabled them all just set an empty array or change each
+name to something like 'time_disabled' as the load condition is simply using in_array.
+
+### Examples
+
+You can find usage examples for all custom filters inside the ```examples``` directory.
+
+- translation.tpl
+- filters.tpl
+
## Caching
The interal Twig caching engine has been disabled in favor of CakePHPs own view caching mechanism.
+
+## Contributing
+
+I've added some utitlity methods so i can bring in any Helper and associated Extensions/Filters as quickly as possible.
+
+If you want to contribute some filters i suggest to look inside the ```extensions``` directory and copy one of the
+existing files and simply rename methods and class names to your needs.
+
+You are not limited to filters, by the way. Read the Twig Documentation [about extending](http://twig.sensiolabs.org/doc/advanced.html#creating-an-extension). The way i extend can also
+be used to add TokenParsers, Functions, Operators, Globals and more.
+
+### Basic Workflow
+
+Extend ```TwigView_Extension``` for your method collection. There is not much code in it, but we are at an early
+stage and inheriting is always a good idea when extending a package.
+
+Helpers can used like so:
+
+ self::helperObject('YourHelper')->something()
+
+The first time you do this the ```YourHelper``` object is stored in the [ClassRegistry](http://api.cakephp.org/class/class-registry "CakePHP API")
+so we don't spam-create a new Helper instance each and every filter call (inside a foreach table loop, for example).
+
+Once you are done coding you need to add a call to ```TwigView::registerExtension()``` to your extension file:
+
+ TwigView::registerExtension(__FILE__, 'Your_Helper_Twig_Extension'); // extending Twig_Extension
+
+Replace ```Your_Helper_Twig_Extension``` with your extension class name. This will simply tell ```TwigView``` what class
+to use when calling ```TwigEnvironment::addExtension()``` inside the construct
+
+That's all! And please use tabs, not spaces :)
+
+
+
+
View
@@ -0,0 +1,77 @@
+<?php
+/**
+ * TwigView Filters for CakePHP
+ *
+ * - I18n Filter -
+ *
+ * @version 0.7.rock-lobster
+ * @package app.views
+ * @subpackage app.views.twig-filters
+ * @author Kjell Bublitz <m3nt0r.de@gmail.com>
+ * @license MIT License
+ */
+
+/**
+ * I18n - Extension for Filterset
+ *
+ * @package app.views.twig-extensions
+ * @author Kjell Bublitz
+ */
+class Twig_Extension_I18n extends Twig_Extension {
+ public function getName() {
+ return 'I18n';
+ }
+ public function getFilters() {
+ return array(
+ 'trans' => new Twig_Filter_Function('TwigView_Filter_I18n::trans'),
+ );
+ }
+}
+TwigView::registerExtension(__FILE__, 'Twig_Extension_I18n');
+
+/**
+ * NumberHelper - Filter Set
+ *
+ * @package app.views.twig-filters
+ * @author Kjell Bublitz
+ */
+class TwigView_Filter_I18n extends TwigView_Extension {
+
+ /**
+ * Combines __, __n, __d, __dn
+ *
+ * Function is selected by the number of arguments given.
+ *
+ * - {{ 'Word'|trans }}
+ * - {{ 'Word'|trans('users') }}
+ * - {{ 'Word'|trans('Words', 5) }}
+ * - {{ 'Word'|trans('Words', 'users', 5) }}
+ *
+ * @param string $text
+ * @param string $param1 (plural, domain or empty(default))
+ * @param mixed $param2
+ * @param mixed $param3
+ * @return string
+ * @author Kjell Bublitz
+ */
+ static function trans($text, $param1=null, $param2=null, $param3=null) {
+
+ // 'Word'|trans('Words', 'users', 5)
+ if (is_numeric($param3)) {
+ return __dn($domain=$param2, $singular=$text, $plural=$param1, $count=$param3, true);
+ }
+
+ // 'Word'|trans('Words', 5)
+ if (is_numeric($param2)) {
+ return __n($singular=$text, $plural=$param1, $count=$param2, true);
+ }
+
+ // 'Word'|trans('users')
+ if (!empty($param1) && !is_numeric($param1)) {
+ return __d($domain=$param1, $text, true);
+ }
+
+ return __($text, true);
+ }
+
+}
View
@@ -0,0 +1,80 @@
+<?php
+/**
+ * TwigView Filters for CakePHP
+ *
+ * - NumberHelper -
+ *
+ * @version 0.7.rock-lobster
+ * @package app.views
+ * @subpackage app.views.twig-filters
+ * @author Kjell Bublitz <m3nt0r.de@gmail.com>
+ * @license MIT License
+ */
+App::import('Helper', 'Number');
+
+/**
+ * NumberHelper - Extension for Filterset
+ *
+ * @package app.views.twig-extensions
+ * @author Kjell Bublitz
+ */
+class Twig_Extension_Number extends Twig_Extension {
+ public function getName() {
+ return 'NumberHelper';
+ }
+ public function getFilters() {
+ return array(
+ 'size' => new Twig_Filter_Function('TwigView_Filter_Number::size'),
+ 'pct' => new Twig_Filter_Function('TwigView_Filter_Number::percentage'),
+ 'curr' => new Twig_Filter_Function('TwigView_Filter_Number::currency'),
+ 'p' => new Twig_Filter_Function('TwigView_Filter_Number::precision'),
+ );
+ }
+}
+TwigView::registerExtension(__FILE__, 'Twig_Extension_Number');
+
+/**
+ * NumberHelper - Filter Set
+ *
+ * @package app.views.twig-filters
+ * @author Kjell Bublitz
+ */
+class TwigView_Filter_Number extends TwigView_Extension {
+
+ /**
+ * Wrapper to Number->toReadableSize()
+ *
+ * @param integer $length Size in bytes
+ */
+ static function size($var) {
+ return self::helperObject('NumberHelper')->toReadableSize($var);
+ }
+ /**
+ * Wrapper to Number->toPercentage()
+ *
+ * @param float $number A floating point number
+ * @param integer $precision The precision of the returned number
+ */
+ static function percentage($var, $p=2) {
+ return self::helperObject('NumberHelper')->toPercentage($var, $p);
+ }
+ /**
+ * Wrapper to Number->currency()
+ *
+ * @param float $number
+ * @param string $currency Valid values are 'USD', 'EUR', 'GBP'
+ * @param array $options f.e. 'before' and 'after' options.
+ */
+ static function currency($var, $curr='USD', $opts=array()) {
+ return self::helperObject('NumberHelper')->currency($var, $curr, $opts);
+ }
+ /**
+ * Wrapper to Number->precision()
+ *
+ * @param float $number A floating point number
+ * @param integer $precision The precision of the returned number
+ */
+ static function precision($var, $p=2) {
+ return self::helperObject('NumberHelper')->precision($var, $p);
+ }
+}
View
@@ -0,0 +1,107 @@
+<?php
+/**
+ * TwigView Filters for CakePHP
+ *
+ * - TextHelper -
+ *
+ * @version 0.7.rock-lobster
+ * @package app.views
+ * @subpackage app.views.twig-filters
+ * @author Kjell Bublitz <m3nt0r.de@gmail.com>
+ * @license MIT License
+ */
+App::import('Helper', 'Text');
+
+/**
+ * TextHelper - Extension for Filterset
+ *
+ * @package app.views.twig-extensions
+ * @author Kjell Bublitz
+ */
+class Twig_Extension_Text extends Twig_Extension {
+ public function getName() {
+ return 'TextHelper';
+ }
+ public function getFilters() {
+ return array(
+ 'stripLinks' => new Twig_Filter_Function('TwigView_Filter_Text::stripLinks'),
+ 'autoLink' => new Twig_Filter_Function('TwigView_Filter_Text::autoLink'),
+ 'truncate' => new Twig_Filter_Function('TwigView_Filter_Text::truncate'),
+ 'excerpt' => new Twig_Filter_Function('TwigView_Filter_Text::excerpt'),
+ 'highlight' => new Twig_Filter_Function('TwigView_Filter_Text::highlight'),
+ );
+ }
+}
+TwigView::registerExtension(__FILE__, 'Twig_Extension_Text');
+
+/**
+ * TextHelper - Filter Set
+ *
+ * @package app.views.twig-filters
+ * @author Kjell Bublitz
+ */
+class TwigView_Filter_Text extends TwigView_Extension {
+
+ /**
+ * TextHelper::stripLinks
+ *
+ * @param string $var
+ * @return void
+ * @author Kjell Bublitz
+ */
+ static function stripLinks($var) {
+ return self::helperObject('TextHelper')->stripLinks($var);
+ }
+
+ /**
+ * TextHelper::autoLink
+ *
+ * @param string $var
+ * @return void
+ * @author Kjell Bublitz
+ */
+ static function autoLink($var) {
+ return self::helperObject('TextHelper')->autoLink($var);
+ }
+
+ /**
+ * TextHelper::truncate
+ *
+ * @param string $var
+ * @param integer $length Length of returned string, including ellipsis.
+ * @param array $options An array of html attributes and options.
+ * @return void
+ * @author Kjell Bublitz
+ */
+ static function truncate($var, $length = 100, $options = array()) {
+ return self::helperObject('TextHelper')->truncate($var, $length, $options);
+ }
+
+ /**
+ * TextHelper::excerpt
+ *
+ * @param string $var
+ * @param string $phrase Phrase that will be searched for
+ * @param integer $radius The amount of characters that will be returned on each side of the founded phrase
+ * @param string $ending Ending that will be appended (default: '...')
+ * @return void
+ * @author Kjell Bublitz
+ */
+ static function excerpt($var, $phrase, $radius = 100, $ending = '...') {
+ return self::helperObject('TextHelper')->excerpt($var, $phrase, $radius, $ending);
+ }
+
+ /**
+ * TextHelper::highlight
+ *
+ * @param string $var
+ * @param string $phrase The phrase that will be searched
+ * @param array $options An array of html attributes and options.
+ * @return void
+ * @author Kjell Bublitz
+ */
+ static function highlight($var, $phrase, $options = array()) {
+ return self::helperObject('TextHelper')->highlight($var, $phrase, $options);
+ }
+}
+
Oops, something went wrong.

0 comments on commit f67225d

Please sign in to comment.