Attention!
In version 2.0 has been added feature to create SmartSelect lists even easier
No more XML, just one function (JavaScript or PHP). Details at
the end of this article.
In version 2.5 has been added feature of creation the list for a case, when page in which it is loads dynamically. Description is
here.
Copy file
/templates/example.xml to your folder and open it in the text editor.
You should see this:
<?xml version="1.0" encoding="utf-8"?>
<fwc:select id="ss_example" xmlns:fwc="http://alx.vingrad.ru/fwc">
<fwc:option>Zero</fwc:option>
<fwc:option value="1">One</fwc:option>
<fwc:option value="2">Two</fwc:option>
<fwc:option value="3">Three</fwc:option>
</fwc:select>
It is a simpliest SmartSelect-list code. You can see it in action in
examples.
As you can see, it consists from 3 tags:
the mandatory for each XML-file construction
<?xml ... ?> (you can set the encoding here, if it is necessary),
main tag
fwc:select and
fwc:option tags inside of it.
Tag
fwc:select can be present at the XML-document only in the single copy.
The document shouldn't contain any other elements (except
<?xml ... ?>-construction) outside this tag.
Tag has two mandatory attributes:
id and
xmlns:fwc.
The first specifies the unique identifier of SmartSelect-object.
On one page cannot be placed more than one list with the same
id-attribute.
The second is URI of
fwc-namespace, using in the library. Without this attribute the library will not work properly.
Besides tag
fwc:select has set of additional attributes for adjustment of various functions of library. The full description of them is
here.
Tag
fwc:option describes concrete
item. It has not necessary attribute
value, setting item's value (by default equal to its contents).
You can also use any usual HTML-attributes, which will be applied at the XSL-transformation.
Following XML-specification, each not empty XML-tag should consist from opening and closing tags. Therefore, in difference from HTML, you cannot write:
This is the right way:
<fwc:option>Zero</fwc:option>
Also the
fwc:select-tag, can contain XHTML-tags for formatting the list of items. About this on the
next page.
To insert the SmartSelect-list on HTML page, you must include two JavaScript-libraries.
1)
Prototype,
http://prototypejs.org/: JavaScript framework to work with DOM and AJAX;
2)
FWC:SmartSelect: JS-component of library for work with SmartSelect-lists;
It is possible to
download all libraries in one archive.
To include JavaScript libraries in HTML, use
SCRIPT-tag, which should be located inside of
HEAD-tag.
Important: if the folder FWComponents in which there is a library FWC:SmartSelect is located not in the same directory, as a HTML-file,
it is necessary to specify the path to this directory before including of library by window-variable fwcpath.
Example:
<html>
<head>
<script src="js/prototype.js"></script>
<script>window.fwcpath = 'js/';</script>
<script src="js/FWC/js/sselect.js"></script>
</head>
<body>
...
</body>
</html>
If your HTML-file is in the
/js directory, the second
SCRIPT-tag can be omitted.
And the last - connection of a XML-file to HTML to page.
Is is can be made in two ways - JavaScript and PHP5.
In the first case XML+XSL processing goes on the client side, the XHTML-code, comes back with
FWC.newSmartSelect() method and can be placed in the document by
document.write() function.
<html>
<head>
<script src="prototype.js"></script>
<script src="FWC/js/sselect.js"></script>
</head>
<body>
<h2>FWC:SmartSelect</h2>
<script>document.write(FWC.newSmartSelect('example.xml'));</script>
</body>
</html>
In the other processing goes at the server, therefore it is necessary to connect PHP libraries. The
$FWC->newSmartSelect also return XHTML-code.
<?php require_once 'FWC/php/SmartSelect.class.php'; $FWC=SmartSelect::getInstance(); ?>
<html>
<head>
<script src="prototype.js"></script>
<script src="FWC/js/sselect.js"></script>
</head>
<body>
<h2>FWC:SmartSelect</h2>
<?php echo $FWC->newSmartSelect('example.xml'); ?>
</body>
</html>
And this is all.
Good luck! :)
Since 2.0 version, the
newSmartSelect() method's function has been considerably extended.
First of all the second parameter was added. Now you can set attributes of
fwc:select-tag in the
JSON-Object format directly on list loading!
It is not necessary to create two XML-files if you want to place two equal SmartSelect-lists. It is enough to pass to methods-loaders different
id values:
<script>document.write(FWC.newSmartSelect('myselect.xml','{"id":"myselect1"}'));</script>
<script>document.write(FWC.newSmartSelect('myselect.xml','{"id":"myselect2"}'));</script>Added wonderful feature to pass as the first parameter not only reference to the XML-file, but an array of items in JSON-Array format!
This array should contain also arrays, on one on each list-item. This arrays may contain three elements: item content, its
value and list of attributes in JSON-Object format:
<!-- simple listbox with three items -->
<script>document.write(FWC.newSmartSelect('[["One"],["Two"],["Three"]]'));</script>
<!-- listbox with Opera style, contains one list item, bold font highlighted -->
<script>document.write(FWC.newSmartSelect('[["Опция 1","opt1",{"style":"font-weight:bold;"}]]','{"skin":"ss_opera"}'));</script>
<!-- the empty listbox with id="empty" and the length is 22 -->
<script>document.write(FWC.newSmartSelect('[]','{"id":"empty","size":22}'));</script>
This way is extremely simple and doesn't demand on any additional actions, i.e. creation of XML-files. However it lacks sometimes, for example, you cannot use HTML-formatting inside of the list. Learn
JSON :)
And, at last, one new feature has been added in version 2.5. Now you can use SmartSelect-lists in dynamically-loaded pages.
If the page you want to place SmartSelect-list generates dynamically via AJAX (XMLHttpRequest), you cannot use
document.write()-method or PHP-method.
For such cases just put tag
<div class="smartselect" source='XML-file or JSON-string' attr='attributes in JSON format'/> at the place you need;
after the page will be loaded, simply call
FWC.evalSmartSelectTags(el) method, which will search these tags inside of element referenced in
el parameter or inside
BODY-tag and will load your lists.
This method is used on this site on pages with examples and documentation.
