documenting /src/viewer/viewer.js

[agent marmorkuchen]

hello there...

looking at /src/viewer/viewer.js today. thanks for your previous reply about
namespaces and gcapi, Joe. i will work on your approved changes
tomorrow.

- with a renewed focus on namespaces, i looked at the variable
components and thought, since this is a global entity, it should start
with a capital letter? or be moved into the Viewer namespace?

- open returns Viewer.go() on two occasions, but Viewer.go() only
returns a value if the url starts with '#'. the value returned is the
result of LiveHTML.dispatch whose return value depends on the
dispatched function. as you can see, the chain is already fairly
complex. is this ambiguity intentional? Viewer.open seems primarily
used as an onclick-handler and should therefore always return false
(or true)?

- render_item: it looks to me as if it actually renders templates all
the time, rename it to render_template to avoid confusion with
functions that work on items like landmarks/agents?

- set_city/set_item: i see them parallels in these functions, but then
some inconsistencies (perhaps):
+ set_city sets Viewer.selected_city to city.resource_id(), but
set_item sets Viewer.item to item. would it make sense to change
things so that either Viewer.city = city.resource_id() and Viewer.item
= item.resource_id()? or just forget about resource_id() in this step?
+ is it really necessary to cache item.resource() in state.item_r? it
seems like something which could be retrieved easily from Viewer.item.
+ why are Viewer.item/selected_city not part of the state instead of
Viewer directly? is it, because state depends on the current app,
while item/selected_city do not? what about renaming state to
appstate, then?

- what is blank() for?

cheers,
marmorkuchen

--
_ ascii ribbon campaign .oOo. GCSd-s:+aC++ULB+++W++M+PS+++Y+
( )
X Jeden Tag eine Erisische Tat!
/ \

[Joe Edelman]

viewer.js is probably the most complex part of the whole codebase, and
there are some good reasons for these inconsistencies that are not easy
to explain. Maybe we could talk about them over IM? The most important
thing is to document how to USE Viewer.open() and Viewer.go(), which do
need to be used by app developers.

I will say that the returns in Viewer.open are just there to make it
clear that the execution of the function stops at that point. The
return values are always thrown out, and the click handlers that call
Viewer.open do not actually return the value returned by Viewer.open.

You're right about components, but I may want to move it into LiveHTML
instead of Viewer. I'll handle it.

blank is for fill="blank". So that certain form fields are cleared when
forms are re-revealed. I'll move it into LiveHTML, which will make
a little more sense.

--Joe

--
J.E. -- http://nxhx.org -- 413.250.8007