And, bam! New SVN commit in the trunk, we are now at Revision 14 (external v1.4).
This is a rather major commit due to the rewrite of Navi.js and NaviLibrary::NaviData.
Anyways, here is the update to the change log:
Code: Select all
API Changes since v1.3:
- In NaviManager:
-- NaviManager::bindNaviData & unbindNaviData have now been renamed bind & unbind, respectively.
-- NaviManager::bind has a new optional parameter, a string vector containing keys to validate via NaviData::ensure.
-- NaviManager::getDerivedUV has been added.
-- NaviManager::injectNaviMaterialMouseWheel has been renamed injectNaviMouseWheel because it may now be used on both regular Navis and NaviMaterials.
-- NaviManager::setNaviBackgroundColor has a new overload (takes a hex color string).
- In NaviData:
-- Completely rewritten with an std::map as a base with heavy use of a generic type, 'NaviDataValue'.
-- Primary mode of interface is via the subscript operator (naviData["myKey"]) for assignment/value retrieval.
-- NaviData::ensure may be used for validation purposes.
- In NaviUtilities:
-- Is now wrapped in a new nested namespace, NaviUtilities
-- New functions: split, splitToMap, join, joinFromMap, isPrefixed, isNumeric, numberToString, toNumber
-- New utility class, InlineVector<T> and specialization, Strings
-- NaviUtilities::replaceAll has lost a parameter, 'avoidCyclic' (no longer required due to new implementation)
- In Navi.js:
-- Completely rewritten from the ground up. Mootools v1.11 is embedded in the first section, scroll to the bottom section for the actual meat of Navi.js.
-- New combobox implementation has been included as a workaround for the current problems with native comboboxes.
-- Element.setHTMLBuffered has been included as a workaround for the flicker problem with frequently-updated elements.
Bugfixes since v1.3:
- NaviUtilities::decodeURIComponent previously failed to properly decode certain sequences, this has been resolved.
Ah, I also forgot to mention that all callbacks now require a signature of "void function(NaviData naviData)" instead of "void function(const NaviData &naviData)".
The NaviDemo has been thoroughly updated to make good use of the new API changes, so you can look to it for reference.
For those itching to update to the latest SVN, I'll go over a few basics of the new NaviData system:
Essentially NaviData now acts like a big std::map<std::string, NaviDataValue>. The new class, 'NaviDataValue' is really a generic container for the following explicit types: wide string, string, boolean, integer, float, double. So you can do something like this:
Code: Select all
NaviDataValue myValue = 79.14;
std::string numberString = myValue.str();
We can then extend this thinking to the NaviData object:
Code: Select all
NaviData myData("TestData");
myData["isHappy"] = "true";
// Some time else
bool happy = myData["isHappy"].toBool(); // "true" & "false" are interpreted as their numeric equivalent
Data validation (does the key exist?) can now be performed via:
Code: Select all
bool ensure(const std::string &key, bool throwOnFailure = true);
&
bool ensure(const std::vector<std::string> &keys, bool throwOnFailure = true);
To additionally validate that the value of the key is numeric (can be converted to a Number), simply prefix the name of the key with "#".
Code: Select all
void myCallback(NaviData naviData)
{
vector<string> myKeys;
myKeys.push_back("name");
myKeys.push_back("#age");
naviData.ensure(myKeys);
int age = naviData["age"].toInt();
cout << "Hello " << naviData["name"].str() << std::endl;
cout << "You are " << age << " years old!" << std::endl;
}
Obviously that "push_back" business is really ugly, oh if only there was an easy way to declare string vectors inline. Oh wait, I'm a programmer, duh:
Code: Select all
naviData.ensure(Strings("name")("#age"));
NaviUtilities::Strings is a typedef for NaviUtilities::InlineVector<std::string>, look at NaviUtilities.h for more info.
Having to execute 'naviData.ensure' inside the callback is sometimes too annoying. Thus, you may optionally specify a string vector of keys to validate as the last parameter of NaviManager::bind. (previously named NaviManager::bindNaviData)
Okay, onwards to Navi.js!
MooTools v1.11 is now embedded inside Navi.js (for ease of inclusion as the new implementation depends upon it).
Old syntax of sending NaviData:
Code: Select all
new NaviData("chatMessage").add("nick", "Bob").add("msg", "Hello world!").send();
New syntax:
Code: Select all
new NaviData("chatMessage", {nick: "Bob", msg: "Hello world!"}).send();
OR
$ND("chatMessage", {nick: "Bob", msg: "Hello world!"}).send();
If you want to be really lazy, I like to use this new feature:
Code: Select all
<form id="myForm">
<input name="nick" type="text"></input>
<input name="msg" type="text"></input>
</form>
<div id="myButton" onclick="$ND('chatMessage', $('myForm')).send()">Send Message</div>
Old syntax of retrieving values from Page NaviData:
Code: Select all
if(pageNaviData.doesExist("msg"))
document.write("We got a message: " + pageNaviData.get("msg"));
New syntax:
Code: Select all
if($defined($PND.get("msg")))
document.write("We got a message: " + $PND.get("msg"));
When the page's DOM is ready (so you can start executing Javascript from the application), a NaviData object named 'ready' is sent. You can bind a callback to this for data initialization purposes.
There is a ComboBox implementation (as a workaround for our problems with native comboboxes) and also Element.setHTMLBuffered (as a workaround for flicker with frequently-updated elements).
A ton of work has gone into these changes, I hope you'll find some of them pleasing. Yes, the API has been broken, but for a good cause.
If you have any questions, comments, or concerns, I'll be happy to reply.
Enjoy.