[xwiki-devs] [Proposal] Best practice: use References in JS code
Hi devs, In the past we use to pass the wiki, space and page as 3 variables to JS code. For example in dashboard.js we currently have: this.sourcePage = this.element.down('.metadata .sourcepage').innerHTML; this.sourceSpace = this.element.down('.metadata .sourcespace').innerHTML; this.sourceWiki = this.element.down('.metadata .sourcewiki').innerHTML; Now that we need to handle Nested Spaces, it’s more complex and I’m proposing to change our best practice and instead to pass a full reference, as in: this.sourceReference = XWiki.Model.resolve(this.element.down('.metadata .source').innerHTML, XWiki.EntityType.DOCUMENT); More generally the idea would be to do the same as we do in Java code, i.e. to start stopping passing several parameters to functions and instead to use XWiki.EntityReference (or XWiki.DocumentReference, etc). For example for dashboard.js this allows to replace: var link = new Element('a', {'href' : this.sourceURL}); link.update(this.sourceWiki + ':' + this.sourceSpace + '.' + this.sourcePage); With: var link = new Element('a', {'href' : this.sourceURL}); link.update(XWiki.Model.serialize(this.sourceReference)); WDYT? Thanks -Vincent
+1 Another option could be to pass a JSON serialization of the reference. Thomas has recently fixed some issues that were preventing JSON serialization of an entity reference. It should work fine now: $jsontool.serialize($documentReference) should produce something close to: { name: 'Page', type: 'DOCUMENT', parent: { name: 'Space2', type: 'SPACE', parent: { ... } } } It's more verbose obviously. For this we need to modify a bit entityReference.js though, because it expects the entity type to be an int. Thanks, Marius On Wed, Jul 29, 2015 at 4:34 PM, [email protected] <[email protected]> wrote:
Hi devs,
In the past we use to pass the wiki, space and page as 3 variables to JS code. For example in dashboard.js we currently have:
this.sourcePage = this.element.down('.metadata .sourcepage').innerHTML; this.sourceSpace = this.element.down('.metadata .sourcespace').innerHTML; this.sourceWiki = this.element.down('.metadata .sourcewiki').innerHTML;
Now that we need to handle Nested Spaces, it’s more complex and I’m proposing to change our best practice and instead to pass a full reference, as in:
this.sourceReference = XWiki.Model.resolve(this.element.down('.metadata .source').innerHTML, XWiki.EntityType.DOCUMENT);
More generally the idea would be to do the same as we do in Java code, i.e. to start stopping passing several parameters to functions and instead to use XWiki.EntityReference (or XWiki.DocumentReference, etc).
For example for dashboard.js this allows to replace:
var link = new Element('a', {'href' : this.sourceURL}); link.update(this.sourceWiki + ':' + this.sourceSpace + '.' + this.sourcePage);
With:
var link = new Element('a', {'href' : this.sourceURL}); link.update(XWiki.Model.serialize(this.sourceReference));
WDYT?
Thanks -Vincent
_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
Hi Marius/all, On 30 Jul 2015 at 10:26:49, Marius Dumitru Florea ([email protected](mailto:[email protected])) wrote:
+1
Another option could be to pass a JSON serialization of the reference. Thomas has recently fixed some issues that were preventing JSON serialization of an entity reference. It should work fine now:
$jsontool.serialize($documentReference)
should produce something close to:
{ name: 'Page', type: 'DOCUMENT', parent: { name: 'Space2', type: 'SPACE', parent: { ... } } }
It's more verbose obviously. For this we need to modify a bit entityReference.js though, because it expects the entity type to be an int.
Indeed there are only 2 global solutions: * Solution 1: Pass the seralized String reference and have the js perform the resolve. This also means that the java code may need to do a serialize. So this has the drawback of doing a serialize + resolve. It has the advantage of being a one-liner from JS. * Solution 2: Pass the individual elements of a reference so that the JS doesn’t have to call resolve. This can be done in several ways: option 1: <div class=“metadata”> <div class=“sourcewiki”>wiki</div> <div class=“sourcepage”>page</div> <div class=“sourcespaces”> <div>space1</div> <div>space2</div> </div> </div> option 2: The JSON you suggest above. However, how would the java code pass this into HTML? Inside a tag’s text, as in: <div class=“metadata”> … json here?... </div> Inside a <script> tag directly? Note that option2 has a big advantage over option 1: JS knows JSON natively and thus there’s no need to implement any parsing at the JS level. Compared to Solution 1, the advantage would to avoid a resolve() call on the JS side. On the java side we’ll still need the serialize() call (which will possibly take slightly longer than the string serialization). Overall Solution 2/option2 could be a better solution indeed. What do others think? Thanks -Vincent
Thanks, Marius
On Wed, Jul 29, 2015 at 4:34 PM, [email protected] wrote:
Hi devs,
In the past we use to pass the wiki, space and page as 3 variables to JS code. For example in dashboard.js we currently have:
this.sourcePage = this.element.down('.metadata .sourcepage').innerHTML; this.sourceSpace = this.element.down('.metadata .sourcespace').innerHTML; this.sourceWiki = this.element.down('.metadata .sourcewiki').innerHTML;
Now that we need to handle Nested Spaces, it’s more complex and I’m proposing to change our best practice and instead to pass a full reference, as in:
this.sourceReference = XWiki.Model.resolve(this.element.down('.metadata .source').innerHTML, XWiki.EntityType.DOCUMENT);
More generally the idea would be to do the same as we do in Java code, i.e. to start stopping passing several parameters to functions and instead to use XWiki.EntityReference (or XWiki.DocumentReference, etc).
For example for dashboard.js this allows to replace:
var link = new Element('a', {'href' : this.sourceURL}); link.update(this.sourceWiki + ':' + this.sourceSpace + '.' + this.sourcePage);
With:
var link = new Element('a', {'href' : this.sourceURL}); link.update(XWiki.Model.serialize(this.sourceReference));
WDYT?
Thanks -Vincent
Direct EntityReference -> JSON serialisation would provide a strong standard (we already have tool to make sure we never break EntityReference) and it would make JS and Java sides more consistent. Now In some cases we will still need to support parsing a String reference in JS I think. On Thu, Jul 30, 2015 at 10:38 AM, [email protected] <[email protected]> wrote:
Hi Marius/all,
On 30 Jul 2015 at 10:26:49, Marius Dumitru Florea ([email protected](mailto:[email protected])) wrote:
+1
Another option could be to pass a JSON serialization of the reference. Thomas has recently fixed some issues that were preventing JSON serialization of an entity reference. It should work fine now:
$jsontool.serialize($documentReference)
should produce something close to:
{ name: 'Page', type: 'DOCUMENT', parent: { name: 'Space2', type: 'SPACE', parent: { ... } } }
It's more verbose obviously. For this we need to modify a bit entityReference.js though, because it expects the entity type to be an int.
Indeed there are only 2 global solutions: * Solution 1: Pass the seralized String reference and have the js perform the resolve. This also means that the java code may need to do a serialize. So this has the drawback of doing a serialize + resolve. It has the advantage of being a one-liner from JS. * Solution 2: Pass the individual elements of a reference so that the JS doesn’t have to call resolve. This can be done in several ways:
option 1:
<div class=“metadata”> <div class=“sourcewiki”>wiki</div> <div class=“sourcepage”>page</div> <div class=“sourcespaces”> <div>space1</div> <div>space2</div> </div> </div>
option 2:
The JSON you suggest above. However, how would the java code pass this into HTML? Inside a tag’s text, as in:
<div class=“metadata”> … json here?... </div>
Inside a <script> tag directly?
Note that option2 has a big advantage over option 1: JS knows JSON natively and thus there’s no need to implement any parsing at the JS level.
Compared to Solution 1, the advantage would to avoid a resolve() call on the JS side. On the java side we’ll still need the serialize() call (which will possibly take slightly longer than the string serialization).
Overall Solution 2/option2 could be a better solution indeed.
What do others think?
Thanks -Vincent
Thanks, Marius
On Wed, Jul 29, 2015 at 4:34 PM, [email protected] wrote:
Hi devs,
In the past we use to pass the wiki, space and page as 3 variables to JS code. For example in dashboard.js we currently have:
this.sourcePage = this.element.down('.metadata .sourcepage').innerHTML; this.sourceSpace = this.element.down('.metadata .sourcespace').innerHTML; this.sourceWiki = this.element.down('.metadata .sourcewiki').innerHTML;
Now that we need to handle Nested Spaces, it’s more complex and I’m proposing to change our best practice and instead to pass a full reference, as in:
this.sourceReference = XWiki.Model.resolve(this.element.down('.metadata .source').innerHTML, XWiki.EntityType.DOCUMENT);
More generally the idea would be to do the same as we do in Java code, i.e. to start stopping passing several parameters to functions and instead to use XWiki.EntityReference (or XWiki.DocumentReference, etc).
For example for dashboard.js this allows to replace:
var link = new Element('a', {'href' : this.sourceURL}); link.update(this.sourceWiki + ':' + this.sourceSpace + '.' + this.sourcePage);
With:
var link = new Element('a', {'href' : this.sourceURL}); link.update(XWiki.Model.serialize(this.sourceReference));
WDYT?
Thanks -Vincent
devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Thomas Mortagne
I agree with Thomas that it would be best to use EntityReference -> JSON as much as possible (when passing the reference from velocity to javascript, server-side), however, man times when you need a reference you also end up building a new reference (on the client-side, i.e. javascript) so we can`t really avoid having a strong javascript EntityReference API + serializer/resolver. Also, making a HTTP request from JS to resolve a string reference on the server (and getting a JSON result) is not really an option IMO (specially if you do that a lot). So +1 to using reference in javascript code. Thanks, Eduard On Thu, Jul 30, 2015 at 11:50 AM, Thomas Mortagne <[email protected]
wrote:
Direct EntityReference -> JSON serialisation would provide a strong standard (we already have tool to make sure we never break EntityReference) and it would make JS and Java sides more consistent. Now In some cases we will still need to support parsing a String reference in JS I think.
On Thu, Jul 30, 2015 at 10:38 AM, [email protected] <[email protected]> wrote:
Hi Marius/all,
On 30 Jul 2015 at 10:26:49, Marius Dumitru Florea ( [email protected](mailto:[email protected])) wrote:
+1
Another option could be to pass a JSON serialization of the reference. Thomas has recently fixed some issues that were preventing JSON serialization of an entity reference. It should work fine now:
$jsontool.serialize($documentReference)
should produce something close to:
{ name: 'Page', type: 'DOCUMENT', parent: { name: 'Space2', type: 'SPACE', parent: { ... } } }
It's more verbose obviously. For this we need to modify a bit entityReference.js though, because it expects the entity type to be an int.
Indeed there are only 2 global solutions: * Solution 1: Pass the seralized String reference and have the js perform the resolve. This also means that the java code may need to do a serialize. So this has the drawback of doing a serialize + resolve. It has the advantage of being a one-liner from JS. * Solution 2: Pass the individual elements of a reference so that the JS doesn’t have to call resolve. This can be done in several ways:
option 1:
<div class=“metadata”> <div class=“sourcewiki”>wiki</div> <div class=“sourcepage”>page</div> <div class=“sourcespaces”> <div>space1</div> <div>space2</div> </div> </div>
option 2:
The JSON you suggest above. However, how would the java code pass this into HTML? Inside a tag’s text, as in:
<div class=“metadata”> … json here?... </div>
Inside a <script> tag directly?
Note that option2 has a big advantage over option 1: JS knows JSON natively and thus there’s no need to implement any parsing at the JS level.
Compared to Solution 1, the advantage would to avoid a resolve() call on the JS side. On the java side we’ll still need the serialize() call (which will possibly take slightly longer than the string serialization).
Overall Solution 2/option2 could be a better solution indeed.
What do others think?
Thanks -Vincent
Thanks, Marius
On Wed, Jul 29, 2015 at 4:34 PM, [email protected] wrote:
Hi devs,
In the past we use to pass the wiki, space and page as 3 variables to JS code. For example in dashboard.js we currently have:
this.sourcePage = this.element.down('.metadata .sourcepage').innerHTML; this.sourceSpace = this.element.down('.metadata .sourcespace').innerHTML; this.sourceWiki = this.element.down('.metadata .sourcewiki').innerHTML;
Now that we need to handle Nested Spaces, it’s more complex and I’m proposing to change our best practice and instead to pass a full reference, as in:
this.sourceReference = XWiki.Model.resolve(this.element.down('.metadata .source').innerHTML, XWiki.EntityType.DOCUMENT);
More generally the idea would be to do the same as we do in Java code, i.e. to start stopping passing several parameters to functions and instead to use XWiki.EntityReference (or XWiki.DocumentReference, etc).
For example for dashboard.js this allows to replace:
var link = new Element('a', {'href' : this.sourceURL}); link.update(this.sourceWiki + ':' + this.sourceSpace + '.' + this.sourcePage);
With:
var link = new Element('a', {'href' : this.sourceURL}); link.update(XWiki.Model.serialize(this.sourceReference));
WDYT?
Thanks -Vincent
devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Thomas Mortagne _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
I don't really understand the solution 2. We already have an EntityReference class in entityReference.js, with a string serializer and a string parser. If we use a JSON format to describe a reference, we will still have to parse it to create an EntityReference object, and this parser does not exist yet. So what is the benefit? I only see drawbacks: - A JSON reference is a lot more verbose. - From the java side, we need to serialize the reference to a JSON representation which is probably more costly than serializing to a string. - We use string representations in a lot of places, and suddenly we should use JSON but only when we do JavaScript... So +1 for the solution 1. In any case, it seems a good idea to use references in JS code. Thanks, Guillaume 2015-08-06 14:25 GMT+02:00 Eduard Moraru <[email protected]>:
I agree with Thomas that it would be best to use EntityReference -> JSON as much as possible (when passing the reference from velocity to javascript, server-side), however, man times when you need a reference you also end up building a new reference (on the client-side, i.e. javascript) so we can`t really avoid having a strong javascript EntityReference API + serializer/resolver.
Also, making a HTTP request from JS to resolve a string reference on the server (and getting a JSON result) is not really an option IMO (specially if you do that a lot).
So +1 to using reference in javascript code.
Thanks, Eduard
On Thu, Jul 30, 2015 at 11:50 AM, Thomas Mortagne < [email protected]
wrote:
Direct EntityReference -> JSON serialisation would provide a strong standard (we already have tool to make sure we never break EntityReference) and it would make JS and Java sides more consistent. Now In some cases we will still need to support parsing a String reference in JS I think.
On Thu, Jul 30, 2015 at 10:38 AM, [email protected] <[email protected]
wrote:
Hi Marius/all,
On 30 Jul 2015 at 10:26:49, Marius Dumitru Florea ( [email protected](mailto:[email protected])) wrote:
+1
Another option could be to pass a JSON serialization of the reference. Thomas has recently fixed some issues that were preventing JSON serialization of an entity reference. It should work fine now:
$jsontool.serialize($documentReference)
should produce something close to:
{ name: 'Page', type: 'DOCUMENT', parent: { name: 'Space2', type: 'SPACE', parent: { ... } } }
It's more verbose obviously. For this we need to modify a bit entityReference.js though, because it expects the entity type to be an int.
Indeed there are only 2 global solutions: * Solution 1: Pass the seralized String reference and have the js perform the resolve. This also means that the java code may need to do a serialize. So this has the drawback of doing a serialize + resolve. It has the advantage of being a one-liner from JS. * Solution 2: Pass the individual elements of a reference so that the JS doesn’t have to call resolve. This can be done in several ways:
option 1:
<div class=“metadata”> <div class=“sourcewiki”>wiki</div> <div class=“sourcepage”>page</div> <div class=“sourcespaces”> <div>space1</div> <div>space2</div> </div> </div>
option 2:
The JSON you suggest above. However, how would the java code pass this into HTML? Inside a tag’s text, as in:
<div class=“metadata”> … json here?... </div>
Inside a <script> tag directly?
Note that option2 has a big advantage over option 1: JS knows JSON natively and thus there’s no need to implement any parsing at the JS level.
Compared to Solution 1, the advantage would to avoid a resolve() call on the JS side. On the java side we’ll still need the serialize() call (which will possibly take slightly longer than the string serialization).
Overall Solution 2/option2 could be a better solution indeed.
What do others think?
Thanks -Vincent
Thanks, Marius
On Wed, Jul 29, 2015 at 4:34 PM, [email protected] wrote:
Hi devs,
In the past we use to pass the wiki, space and page as 3 variables to JS code. For example in dashboard.js we currently have:
this.sourcePage = this.element.down('.metadata .sourcepage').innerHTML; this.sourceSpace = this.element.down('.metadata .sourcespace').innerHTML; this.sourceWiki = this.element.down('.metadata .sourcewiki').innerHTML;
Now that we need to handle Nested Spaces, it’s more complex and I’m proposing to change our best practice and instead to pass a full reference, as in:
this.sourceReference = XWiki.Model.resolve(this.element.down('.metadata .source').innerHTML, XWiki.EntityType.DOCUMENT);
More generally the idea would be to do the same as we do in Java code, i.e. to start stopping passing several parameters to functions and instead to use XWiki.EntityReference (or XWiki.DocumentReference, etc).
For example for dashboard.js this allows to replace:
var link = new Element('a', {'href' : this.sourceURL}); link.update(this.sourceWiki + ':' + this.sourceSpace + '.' + this.sourcePage);
With:
var link = new Element('a', {'href' : this.sourceURL}); link.update(XWiki.Model.serialize(this.sourceReference));
WDYT?
Thanks -Vincent
devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Thomas Mortagne _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Guillaume Delhumeau ([email protected]) Research & Development Engineer at XWiki SAS Committer on the XWiki.org project
A bit late to the game but can't we pass a cannonicalized absolute string to the JS ? eg: wiki:space.sp\.ace.sp\\ace.page and then just warn the js devs that they should use functions to manipulate the string representation instead of hacking it manually ? That's what nodejs does for URLs and I will say without reservation that the user-friendlyness of their their URL parsing API is not even compatible to the disaster that was java.net.URL. On 26/08/15 17:36, Guillaume "Louis-Marie" Delhumeau wrote:
I don't really understand the solution 2.
We already have an EntityReference class in entityReference.js, with a string serializer and a string parser.
If we use a JSON format to describe a reference, we will still have to parse it to create an EntityReference object, and this parser does not exist yet.
So what is the benefit?
I only see drawbacks: - A JSON reference is a lot more verbose. - From the java side, we need to serialize the reference to a JSON representation which is probably more costly than serializing to a string. - We use string representations in a lot of places, and suddenly we should use JSON but only when we do JavaScript...
So +1 for the solution 1.
In any case, it seems a good idea to use references in JS code.
Thanks, Guillaume
2015-08-06 14:25 GMT+02:00 Eduard Moraru <[email protected]>:
I agree with Thomas that it would be best to use EntityReference -> JSON as much as possible (when passing the reference from velocity to javascript, server-side), however, man times when you need a reference you also end up building a new reference (on the client-side, i.e. javascript) so we can`t really avoid having a strong javascript EntityReference API + serializer/resolver.
Also, making a HTTP request from JS to resolve a string reference on the server (and getting a JSON result) is not really an option IMO (specially if you do that a lot).
So +1 to using reference in javascript code.
Thanks, Eduard
On Thu, Jul 30, 2015 at 11:50 AM, Thomas Mortagne < [email protected]
wrote:
Direct EntityReference -> JSON serialisation would provide a strong standard (we already have tool to make sure we never break EntityReference) and it would make JS and Java sides more consistent. Now In some cases we will still need to support parsing a String reference in JS I think.
On Thu, Jul 30, 2015 at 10:38 AM, [email protected] <[email protected]
wrote:
Hi Marius/all,
On 30 Jul 2015 at 10:26:49, Marius Dumitru Florea ( [email protected](mailto:[email protected])) wrote:
+1
Another option could be to pass a JSON serialization of the reference. Thomas has recently fixed some issues that were preventing JSON serialization of an entity reference. It should work fine now:
$jsontool.serialize($documentReference)
should produce something close to:
{ name: 'Page', type: 'DOCUMENT', parent: { name: 'Space2', type: 'SPACE', parent: { ... } } }
It's more verbose obviously. For this we need to modify a bit entityReference.js though, because it expects the entity type to be an int.
Indeed there are only 2 global solutions: * Solution 1: Pass the seralized String reference and have the js perform the resolve. This also means that the java code may need to do a serialize. So this has the drawback of doing a serialize + resolve. It has the advantage of being a one-liner from JS. * Solution 2: Pass the individual elements of a reference so that the JS doesn’t have to call resolve. This can be done in several ways:
option 1:
<div class=“metadata”> <div class=“sourcewiki”>wiki</div> <div class=“sourcepage”>page</div> <div class=“sourcespaces”> <div>space1</div> <div>space2</div> </div> </div>
option 2:
The JSON you suggest above. However, how would the java code pass this into HTML? Inside a tag’s text, as in:
<div class=“metadata”> … json here?... </div>
Inside a <script> tag directly?
Note that option2 has a big advantage over option 1: JS knows JSON natively and thus there’s no need to implement any parsing at the JS level.
Compared to Solution 1, the advantage would to avoid a resolve() call on the JS side. On the java side we’ll still need the serialize() call (which will possibly take slightly longer than the string serialization).
Overall Solution 2/option2 could be a better solution indeed.
What do others think?
Thanks -Vincent
Thanks, Marius
On Wed, Jul 29, 2015 at 4:34 PM, [email protected] wrote:
Hi devs,
In the past we use to pass the wiki, space and page as 3 variables to JS code. For example in dashboard.js we currently have:
this.sourcePage = this.element.down('.metadata .sourcepage').innerHTML; this.sourceSpace = this.element.down('.metadata .sourcespace').innerHTML; this.sourceWiki = this.element.down('.metadata .sourcewiki').innerHTML;
Now that we need to handle Nested Spaces, it’s more complex and I’m proposing to change our best practice and instead to pass a full reference, as in:
this.sourceReference = XWiki.Model.resolve(this.element.down('.metadata .source').innerHTML, XWiki.EntityType.DOCUMENT);
More generally the idea would be to do the same as we do in Java code, i.e. to start stopping passing several parameters to functions and instead to use XWiki.EntityReference (or XWiki.DocumentReference, etc).
For example for dashboard.js this allows to replace:
var link = new Element('a', {'href' : this.sourceURL}); link.update(this.sourceWiki + ':' + this.sourceSpace + '.' + this.sourcePage);
With:
var link = new Element('a', {'href' : this.sourceURL}); link.update(XWiki.Model.serialize(this.sourceReference));
WDYT?
Thanks -Vincent
devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Thomas Mortagne _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
On 26 Aug 2015 at 18:23:42, Caleb James DeLisle ([email protected](mailto:[email protected])) wrote:
A bit late to the game but can't we pass a cannonicalized absolute string to the JS ? eg: wiki:space.sp\.ace.sp\\ace.page and then just warn the js devs that they should use functions to manipulate the string representation instead of hacking it manually ?
This is indeed my original proposal in the first mail: “[…]I’m proposing to change our best practice and instead to pass a full reference, as in: this.sourceReference = XWiki.Model.resolve(this.element.down('.metadata .source').innerHTML, XWiki.EntityType.DOCUMENT); “ Thanks -Vincent
That's what nodejs does for URLs and I will say without reservation that the user-friendlyness of their their URL parsing API is not even compatible to the disaster that was java.net.URL.
On 26/08/15 17:36, Guillaume "Louis-Marie" Delhumeau wrote:
I don't really understand the solution 2.
We already have an EntityReference class in entityReference.js, with a string serializer and a string parser.
If we use a JSON format to describe a reference, we will still have to parse it to create an EntityReference object, and this parser does not exist yet.
So what is the benefit?
I only see drawbacks: - A JSON reference is a lot more verbose. - From the java side, we need to serialize the reference to a JSON representation which is probably more costly than serializing to a string. - We use string representations in a lot of places, and suddenly we should use JSON but only when we do JavaScript...
So +1 for the solution 1.
In any case, it seems a good idea to use references in JS code.
Thanks, Guillaume
2015-08-06 14:25 GMT+02:00 Eduard Moraru :
I agree with Thomas that it would be best to use EntityReference -> JSON as much as possible (when passing the reference from velocity to javascript, server-side), however, man times when you need a reference you also end up building a new reference (on the client-side, i.e. javascript) so we can`t really avoid having a strong javascript EntityReference API + serializer/resolver.
Also, making a HTTP request from JS to resolve a string reference on the server (and getting a JSON result) is not really an option IMO (specially if you do that a lot).
So +1 to using reference in javascript code.
Thanks, Eduard
On Thu, Jul 30, 2015 at 11:50 AM, Thomas Mortagne < [email protected]
wrote:
Direct EntityReference -> JSON serialisation would provide a strong standard (we already have tool to make sure we never break EntityReference) and it would make JS and Java sides more consistent. Now In some cases we will still need to support parsing a String reference in JS I think.
On Thu, Jul 30, 2015 at 10:38 AM, [email protected] > >>> wrote:
Hi Marius/all,
On 30 Jul 2015 at 10:26:49, Marius Dumitru Florea ( [email protected](mailto:[email protected])) wrote:
+1
Another option could be to pass a JSON serialization of the reference. Thomas has recently fixed some issues that were preventing JSON serialization of an entity reference. It should work fine now:
$jsontool.serialize($documentReference)
should produce something close to:
{ name: 'Page', type: 'DOCUMENT', parent: { name: 'Space2', type: 'SPACE', parent: { ... } } }
It's more verbose obviously. For this we need to modify a bit entityReference.js though, because it expects the entity type to be an int.
Indeed there are only 2 global solutions: * Solution 1: Pass the seralized String reference and have the js perform the resolve. This also means that the java code may need to do a serialize. So this has the drawback of doing a serialize + resolve. It has the advantage of being a one-liner from JS. * Solution 2: Pass the individual elements of a reference so that the JS doesn’t have to call resolve. This can be done in several ways:
option 1:
wiki
page
space1
space2
option 2:
The JSON you suggest above. However, how would the java code pass this
into HTML? Inside a tag’s text, as in:
… json here?...
Inside a
Ahh ok, +1 to explosing the absolute cannonical reference, however I will point out that use of "this" in javascript is dangerous and should be avoided. It looks like you're attaching it to the global namespace (aka window) but "this" has different meanings depending on where you are in the code. Better XWiki.doc.reference or similar IMO. Thanks, Caleb On 27/08/15 10:23, [email protected] wrote:
On 26 Aug 2015 at 18:23:42, Caleb James DeLisle ([email protected](mailto:[email protected])) wrote:
A bit late to the game but can't we pass a cannonicalized absolute string to the JS ? eg: wiki:space.sp\.ace.sp\\ace.page and then just warn the js devs that they should use functions to manipulate the string representation instead of hacking it manually ?
This is indeed my original proposal in the first mail:
“[…]I’m proposing to change our best practice and instead to pass a full reference, as in:
this.sourceReference = XWiki.Model.resolve(this.element.down('.metadata .source').innerHTML, XWiki.EntityType.DOCUMENT); “
Thanks -Vincent
That's what nodejs does for URLs and I will say without reservation that the user-friendlyness of their their URL parsing API is not even compatible to the disaster that was java.net.URL.
On 26/08/15 17:36, Guillaume "Louis-Marie" Delhumeau wrote:
I don't really understand the solution 2.
We already have an EntityReference class in entityReference.js, with a string serializer and a string parser.
If we use a JSON format to describe a reference, we will still have to parse it to create an EntityReference object, and this parser does not exist yet.
So what is the benefit?
I only see drawbacks: - A JSON reference is a lot more verbose. - From the java side, we need to serialize the reference to a JSON representation which is probably more costly than serializing to a string. - We use string representations in a lot of places, and suddenly we should use JSON but only when we do JavaScript...
So +1 for the solution 1.
In any case, it seems a good idea to use references in JS code.
Thanks, Guillaume
2015-08-06 14:25 GMT+02:00 Eduard Moraru :
I agree with Thomas that it would be best to use EntityReference -> JSON as much as possible (when passing the reference from velocity to javascript, server-side), however, man times when you need a reference you also end up building a new reference (on the client-side, i.e. javascript) so we can`t really avoid having a strong javascript EntityReference API + serializer/resolver.
Also, making a HTTP request from JS to resolve a string reference on the server (and getting a JSON result) is not really an option IMO (specially if you do that a lot).
So +1 to using reference in javascript code.
Thanks, Eduard
On Thu, Jul 30, 2015 at 11:50 AM, Thomas Mortagne < [email protected]
wrote:
Direct EntityReference -> JSON serialisation would provide a strong standard (we already have tool to make sure we never break EntityReference) and it would make JS and Java sides more consistent. Now In some cases we will still need to support parsing a String reference in JS I think.
On Thu, Jul 30, 2015 at 10:38 AM, [email protected] > >>> wrote:
Hi Marius/all,
On 30 Jul 2015 at 10:26:49, Marius Dumitru Florea ( [email protected](mailto:[email protected])) wrote:
> +1 > > Another option could be to pass a JSON serialization of the reference. > Thomas has recently fixed some issues that were preventing JSON > serialization of an entity reference. It should work fine now: > > $jsontool.serialize($documentReference) > > should produce something close to: > > { > name: 'Page', > type: 'DOCUMENT', > parent: { > name: 'Space2', > type: 'SPACE', > parent: { > ... > } > } > } > > It's more verbose obviously. For this we need to modify a bit > entityReference.js though, because it expects the entity type to be an > int.
Indeed there are only 2 global solutions: * Solution 1: Pass the seralized String reference and have the js perform the resolve. This also means that the java code may need to do a serialize. So this has the drawback of doing a serialize + resolve. It has the advantage of being a one-liner from JS. * Solution 2: Pass the individual elements of a reference so that the JS doesn’t have to call resolve. This can be done in several ways:
option 1:
wiki
page
space1
space2
option 2:
The JSON you suggest above. However, how would the java code pass this
into HTML? Inside a tag’s text, as in:
… json here?...
Inside a
devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
+1 for option 1. Guillaume makes a good point. Sounds more predictable and easier to work with, since a string is easily placed in pretty much any context compared to JSON, as Vincent also pointed out. I don`t really mind the extra resolve step in JS. I guess the JSON method could be used when actually returning JSON, like some LiveTable resutls or some other JSON result page. It would be convenient in that place to read the reference directly from its JSON value, though I`m not sure that, in terms of performance, the difference from resolving the string is very big. Plus, there is the difference in mapping the types (string vs int) that Marius mentioned which might need fixing. So overall, I still think option 1 is safer, and option 2 could be nice to have in some cases. Thanks, Eduard On Thu, Aug 27, 2015 at 11:34 AM, Caleb James DeLisle <[email protected]> wrote:
Ahh ok, +1 to explosing the absolute cannonical reference, however I will point out that use of "this" in javascript is dangerous and should be avoided. It looks like you're attaching it to the global namespace (aka window) but "this" has different meanings depending on where you are in the code. Better XWiki.doc.reference or similar IMO.
Thanks, Caleb
On 27/08/15 10:23, [email protected] wrote:
On 26 Aug 2015 at 18:23:42, Caleb James DeLisle ([email protected](mailto: [email protected])) wrote:
A bit late to the game but can't we pass a cannonicalized absolute string
to the JS ? eg: wiki:space.sp\.ace.sp\\ace.page and then just warn the js devs that they should use functions to manipulate the string representation instead of hacking it manually ?
This is indeed my original proposal in the first mail:
“[…]I’m proposing to change our best practice and instead to pass a full reference, as in:
this.sourceReference = XWiki.Model.resolve(this.element.down('.metadata .source').innerHTML, XWiki.EntityType.DOCUMENT); “
Thanks -Vincent
That's what nodejs does for URLs and I will say without reservation that
the user-friendlyness of their their URL parsing API is not even compatible to the disaster that was java.net.URL.
On 26/08/15 17:36, Guillaume "Louis-Marie" Delhumeau wrote:
I don't really understand the solution 2.
We already have an EntityReference class in entityReference.js, with a string serializer and a string parser.
If we use a JSON format to describe a reference, we will still have to parse it to create an EntityReference object, and this parser does not exist yet.
So what is the benefit?
I only see drawbacks: - A JSON reference is a lot more verbose. - From the java side, we need to serialize the reference to a JSON representation which is probably more costly than serializing to a string. - We use string representations in a lot of places, and suddenly we should use JSON but only when we do JavaScript...
So +1 for the solution 1.
In any case, it seems a good idea to use references in JS code.
Thanks, Guillaume
2015-08-06 14:25 GMT+02:00 Eduard Moraru :
I agree with Thomas that it would be best to use EntityReference ->
JSON as much as possible (when passing the reference from velocity to javascript, server-side), however, man times when you need a reference you also end up building a new reference (on the client-side, i.e. javascript) so we can`t really avoid having a strong javascript EntityReference API + serializer/resolver.
Also, making a HTTP request from JS to resolve a string reference on the server (and getting a JSON result) is not really an option IMO (specially if you do that a lot).
So +1 to using reference in javascript code.
Thanks, Eduard
On Thu, Jul 30, 2015 at 11:50 AM, Thomas Mortagne < [email protected]
wrote:
Direct EntityReference -> JSON serialisation would provide a strong
standard (we already have tool to make sure we never break EntityReference) and it would make JS and Java sides more consistent. Now In some cases we will still need to support parsing a String reference in JS I think.
On Thu, Jul 30, 2015 at 10:38 AM, [email protected] > >>> wrote:
> Hi Marius/all, > > On 30 Jul 2015 at 10:26:49, Marius Dumitru Florea ( > [email protected](mailto:[email protected] )) wrote:
> > +1 >> >> Another option could be to pass a JSON serialization of the >> reference. >> Thomas has recently fixed some issues that were preventing JSON >> serialization of an entity reference. It should work fine now: >> >> $jsontool.serialize($documentReference) >> >> should produce something close to: >> >> { >> name: 'Page', >> type: 'DOCUMENT', >> parent: { >> name: 'Space2', >> type: 'SPACE', >> parent: { >> ... >> } >> } >> } >> >> It's more verbose obviously. For this we need to modify a bit >> entityReference.js though, because it expects the entity type to be >> an >> int. >> > > Indeed there are only 2 global solutions: > * Solution 1: Pass the seralized String reference and have the js > perform the resolve. This also means that the java code may need to do a serialize. So this has the drawback of doing a serialize + resolve. It
has
the advantage of being a one-liner from JS.
> * Solution 2: Pass the individual elements of a reference so that the > JS
doesn’t have to call resolve. This can be done in several ways:
> > option 1: > > >
> wiki
> page
>
> space1
> space2
>
>
> option 2: > > The JSON you suggest above. However, how would the java code pass > this > into HTML? Inside a tag’s text, as in:
> > > … json here?... > >
> Inside a > _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
_______________________________________________
devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
On Wed, Aug 26, 2015 at 5:36 PM, Guillaume "Louis-Marie" Delhumeau <[email protected]> wrote:
I don't really understand the solution 2.
We already have an EntityReference class in entityReference.js, with a string serializer and a string parser.
If we use a JSON format to describe a reference, we will still have to parse it to create an EntityReference object, and this parser does not exist yet.
For the Javascript side there is a helper in entityReference.js to create an EntityReference from its parsed JSON representation.
So what is the benefit?
I only see drawbacks: - A JSON reference is a lot more verbose. - From the java side, we need to serialize the reference to a JSON representation which is probably more costly than serializing to a string. - We use string representations in a lot of places, and suddenly we should use JSON but only when we do JavaScript...
So +1 for the solution 1.
In any case, it seems a good idea to use references in JS code.
Thanks, Guillaume
IMO we don't need to enforce one of the other, in some use cases it's much more practical to send JSON representation and in we already have String reference and it would be a pain to have to convert them to JSON.
2015-08-06 14:25 GMT+02:00 Eduard Moraru <[email protected]>:
I agree with Thomas that it would be best to use EntityReference -> JSON as much as possible (when passing the reference from velocity to javascript, server-side), however, man times when you need a reference you also end up building a new reference (on the client-side, i.e. javascript) so we can`t really avoid having a strong javascript EntityReference API + serializer/resolver.
Also, making a HTTP request from JS to resolve a string reference on the server (and getting a JSON result) is not really an option IMO (specially if you do that a lot).
So +1 to using reference in javascript code.
Thanks, Eduard
On Thu, Jul 30, 2015 at 11:50 AM, Thomas Mortagne < [email protected]
wrote:
Direct EntityReference -> JSON serialisation would provide a strong standard (we already have tool to make sure we never break EntityReference) and it would make JS and Java sides more consistent. Now In some cases we will still need to support parsing a String reference in JS I think.
On Thu, Jul 30, 2015 at 10:38 AM, [email protected] <[email protected]
wrote:
Hi Marius/all,
On 30 Jul 2015 at 10:26:49, Marius Dumitru Florea ( [email protected](mailto:[email protected])) wrote:
+1
Another option could be to pass a JSON serialization of the reference. Thomas has recently fixed some issues that were preventing JSON serialization of an entity reference. It should work fine now:
$jsontool.serialize($documentReference)
should produce something close to:
{ name: 'Page', type: 'DOCUMENT', parent: { name: 'Space2', type: 'SPACE', parent: { ... } } }
It's more verbose obviously. For this we need to modify a bit entityReference.js though, because it expects the entity type to be an int.
Indeed there are only 2 global solutions: * Solution 1: Pass the seralized String reference and have the js perform the resolve. This also means that the java code may need to do a serialize. So this has the drawback of doing a serialize + resolve. It has the advantage of being a one-liner from JS. * Solution 2: Pass the individual elements of a reference so that the JS doesn’t have to call resolve. This can be done in several ways:
option 1:
<div class=“metadata”> <div class=“sourcewiki”>wiki</div> <div class=“sourcepage”>page</div> <div class=“sourcespaces”> <div>space1</div> <div>space2</div> </div> </div>
option 2:
The JSON you suggest above. However, how would the java code pass this into HTML? Inside a tag’s text, as in:
<div class=“metadata”> … json here?... </div>
Inside a <script> tag directly?
Note that option2 has a big advantage over option 1: JS knows JSON natively and thus there’s no need to implement any parsing at the JS level.
Compared to Solution 1, the advantage would to avoid a resolve() call on the JS side. On the java side we’ll still need the serialize() call (which will possibly take slightly longer than the string serialization).
Overall Solution 2/option2 could be a better solution indeed.
What do others think?
Thanks -Vincent
Thanks, Marius
On Wed, Jul 29, 2015 at 4:34 PM, [email protected] wrote:
Hi devs,
In the past we use to pass the wiki, space and page as 3 variables to JS code. For example in dashboard.js we currently have:
this.sourcePage = this.element.down('.metadata .sourcepage').innerHTML; this.sourceSpace = this.element.down('.metadata .sourcespace').innerHTML; this.sourceWiki = this.element.down('.metadata .sourcewiki').innerHTML;
Now that we need to handle Nested Spaces, it’s more complex and I’m proposing to change our best practice and instead to pass a full reference, as in:
this.sourceReference = XWiki.Model.resolve(this.element.down('.metadata .source').innerHTML, XWiki.EntityType.DOCUMENT);
More generally the idea would be to do the same as we do in Java code, i.e. to start stopping passing several parameters to functions and instead to use XWiki.EntityReference (or XWiki.DocumentReference, etc).
For example for dashboard.js this allows to replace:
var link = new Element('a', {'href' : this.sourceURL}); link.update(this.sourceWiki + ':' + this.sourceSpace + '.' + this.sourcePage);
With:
var link = new Element('a', {'href' : this.sourceURL}); link.update(XWiki.Model.serialize(this.sourceReference));
WDYT?
Thanks -Vincent
devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Thomas Mortagne _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Guillaume Delhumeau ([email protected]) Research & Development Engineer at XWiki SAS Committer on the XWiki.org project _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Thomas Mortagne
participants (6)
-
Caleb James DeLisle -
Eduard Moraru -
Guillaume "Louis-Marie" Delhumeau -
Marius Dumitru Florea -
Thomas Mortagne -
vincent＠massol.net