alb / fselectmenu
Fast and non-intrusive HTML select menu
Installs: 2 440
Dependents: 0
Suggesters: 0
Security: 0
Stars: 7
Watchers: 3
Forks: 5
Open Issues: 2
Language:JavaScript
Requires
- php: >=5.3.0
Requires (Dev)
- symfony/process: 2.1.*
- symfony/yaml: 2.1.*
README
FSelectMenu is a Fast and non-intrusive HTML select menu.
Features:
-
Fast: rendering is done on the server side: no DOM manipulation on the client side
-
Non intrusive: Once FSelectMenu is initialized you can forget it: every select menu will work, whether they were present during initialization or added later. (FSelectMenu uses event delegation. The HTML code is generated on the server; all that is left to FSelectMenu is to listen for events bubbling to the document element.).
-
Non intrusive: Works out of the box with existing scripts
- Scripts don't have to know anything about FSelectMenu for simple things like listening for events, getting and changing the value, etc.
- Scripts interact with the native select element directly
Usage
Load and init the FSelectMenu javascript module:
require(['fselectmenu/fselectmenu'], function(FSelectMenu) { FSelectMenu.init(); });
That's all.
If you add new select menus on the document after that, you don't have to call .init()
again.
Just trigger the change
event on the native select element when programmatically changing its value.
Install
$ git submodule add git://github.com/arnaud-lb/fselectmenu.git vendor/fselectmenu
Plain PHP
You can render a FSelectMenu with the FSelectMenu\Renderer class:
<?php $renderer = new FSelectMenu\Renderer; echo $renderer->render($value, $choices, $options);
- $value is the value of the selected choice
- $choices is an array of value => label choices (with nested arrays, for optgroups)
- $options is an array with the following keys:
- attrs: fselectmenu element attributes (e.g. id, class, ...)
- nativeAttrs: native select element attributes (e.g. id, name)
- optionAttrs: choice elements attributes (array of value => attributes)
- optionWrapperAttrs: choice elements wrapper attributes
- rawLabels: whether to escape labels
- fixedLabel: a label that will always be displayed instead of the selected label
Example:
<?php echo $renderer->render('x', array('x' => 'Foo', 'y' => 'Bar'), array('nativeAttrs' => array('name' => 'foo')));
Twig
Register the extension:
<?php $extension = new FSelectMenu\Twig\Extension; $twigEnvironment->addExtension($extension);
The extension exposes the fselectmenu
method:
fselectmenu(value, choices, options)
See Plain PHP above for a description of the parameters.
Example:
{{ fselectmenu('x', {'x': 'Foo', 'y': 'Bar'}, {'nativeAttrs':{'name': 'foo'}}) }}
Javascript
Menus can also be rendered in Javascript (e.g. on the client side or in nodejs) with the renderer
module:
require(['fselectmenu/renderer'], function(renderer) { var html = renderer.render(value, choices, options); });
Symfony2
Add the FSelectMenu namespace to your autoloader
<?php // app/autoload.php $loader->registerNamespaces(array( 'FSelectMenu' => __DIR__.'/../vendor/fselectmenu/lib', // your other namespaces );
Add FSelectMenuBundle to your application kernel
<?php // app/AppKernel.php public function registerBundles() { return array( // ... new FSelectMenu\Bundle\FSelectMenuBundle(), ); }
Overload the choice_widget
block in your form theme:
{% use "FSelectMenuBundle::fselectmenu.html.twig" %} {% block choice_widget %} {% spaceless %} {% if expanded %} {% for child in form %} {{ form_widget(child) }} {% endfor %} {% else %} {% if multiple %} {{ parent() }} {% else %} {# Symfony >= 2.1 #} {{ block('fselectmenu_choice_widget_2_1') }} {# Symfony 2.0 #} {# {{ block('fselectmenu_choice_widget') }} #} {% endif %} {% endif %} {% endspaceless %} {% endblock choice_widget %}
ZendFramework
Register view helper path:
# application.ini resources.view.helperPath.FSelectMenu_Zend_View_Helper = APPLICATION_PATH "/../vendor/fselectmenu/lib/FSelectMenu/Zend/View/Helper"
Subclass Zend_Form_Element_Select:
<?php
class App_Form_Element_FSelectMenu extends Zend_Form_Element_Select
{
public $helper = 'formFSelectMenu';
}
Styling
FSelectMenu comes with a minimal (behavior only) stylesheet at lib/FSelectMenu/Bundle/Resources/sass/_fselectmenu.sass
.
Graceful degradation
Support for clients without javascript enabled can be achieved by hidding the fake select menu and displaying the native one:
<noscript> <style> .fselectmenu-label-wrapper { display: none; } .fselectmenu-native { display: inline; } </style> </noscript>