documenting /src/gcapi
agent marmorkuchen
another day, another set of questions, this time around /src/gcapi:
- agent.js:
- the functions free and assignable seem unused, not so sure
about the function status. there is a reference to an attribute
item.status in /src/foundation/resource.js (which i haven't seen
assigned anywhere, but i can imagine that it is somewhat evaluated)
from some JSON return value.
- in function free, there is a line
if (!CurrentUser.logged_in) return Viewer.join_please();
is this the right place for it?
- event.js:
- function improve has an argument called 'a' which supposedly is a
variable name for an event. is it ok to name it 'ev' then? or what
does 'a' stand for?
- the same for function color.
- item.js:
- i find it confusing that there is a function item() that does
things with items and a class Item which does things with items.
- what does atag_trans stand for? agent tag transition?
- the arguments are called 'a' in the calculated_fields functions.
should that be renamed to 'item'?
- model.js:
- what is the reasoning behind in_city and with_atag defined here and
and not in foundation/resource.js?
so long,
marmorkuchen
--
_ ascii ribbon campaign .oOo. GCSd-s:+aC++ULB+++W++M+PS+++Y+
( )
X Bildet Olsen Banden!
/ \
Joe Edelman
Created commit d663ddb: a little cleanup of some obsolete stuff
re: event.js -- you're right it would be better if the function argument
was called 'ev'. and the ones in item.js could be 'item'.
re: item.js --
* atag_trans stands for translate. to understand this, you need to
understand the difference between 'atags' and 'upfors'. There are two
separate tagging systems for letting a person indicate what kinds of
activities they might like to join in or be part of. I know this is
weird, but I think it sort of has to be this way, because people
themselves are complex in terms of what they are up for. I tried
several times to make it simpler, but always ended up making it more
complex again.
So when a user signs up, they indicate some very specific kinds of
things they are into. As specific as "knitting" or "streetcorner
oddities and fun" and "pick-up soccer games". These become atags (for
"action tags"). They are abbreviated, for example to "knitting",
"cornerfun", and "soccer".
But when a user gets in touch from their phone, they say something more
vague. Something like "i want adventure" or "connection" or
"volunteering". These more vague words are called "upfor" tags. These
are the things that appear on the badges. There is no hierarchical
relationship between atags and upfors. It is many to many. A bipartite
graph. And the current upfors of an agent select a subset of their
atags which are currently in effect.
The atag_trans hash maps atags to upfors. This map is tentative and
will evolve as the tag systems evolve. atags_to_upfors might be a
better name for it.
> - i find it confusing that there is a function item() that does
> things with items and a class Item which does things with items.
The global Item namespace is just a bundle of useful functionality
related to items. The item() function is specifically for processing
javascript communication from the server.
Why don't you sit with it for a bit, and if you think we should change
the name of the namespace, we could.
>- model.js:
> - what is the reasoning behind in_city and with_atag defined here and
> and not in foundation/resource.js?
I think the files are not so clearly named, but the idea is that
foundation/resource.js defines a general purpose in-memory database
mechanism that could be (theoretically) used in other people's
javascript projects. gcapi/models.js provides additional functionality
that's specific to the viewer.
--Joe
agent marmorkuchen
* Joe Edelman <joe.e...@gmail.com> [2009-03-20 12:22 -0400]:
>
> re: event.js -- you're right it would be better if the function argument
> was called 'ev'. and the ones in item.js could be 'item'.
>
> re: item.js --
> * atag_trans stands for translate. to understand this, you need to
[..]
> The atag_trans hash maps atags to upfors. This map is tentative and
> will evolve as the tag systems evolve. atags_to_upfors might be a
> better name for it.
ok, some renaming in this commit:
http://github.com/marmorkuchen/groundcrew-viewer/commit/4fe3485d1f2369ff9d353ed2125f7a80ef2574c6
until recently, without thinking much about 'atag', i would have thought
it stands for agent tag. but if you look at it closely, it clearly can't be.
it would be easier for a groundcrew rookie if it was named, for
instance, action_tag, an idea you do not seem to be opposed in
principal, see item_tag, city_id or thumb_url.
but then i see atags_to_upfors should become action_tags_to_upfors which
already looks bloated. since you don't use upfor_tags, would it be okay
to use action(s) instead of action_tag(s)?
> > - i find it confusing that there is a function item() that does
> > things with items and a class Item which does things with items.
>
> The global Item namespace is just a bundle of useful functionality
> related to items. The item() function is specifically for processing
> javascript communication from the server.
>
> Why don't you sit with it for a bit, and if you think we should change
> the name of the namespace, we could.
well, i would like the Item namespace to stay as it is, but do something to
these all these functions in src/gcacpi/gcserver.js - like putting them into the
namespace GCServer.
unfortunately, if i see this correctly, it would lead to more data being
transferred from server to client if this10.js has to have calls like
GCServer.item() instead of item() for each line. but maybe we can change
the format a little? we could have a wrapper function GCServer.items()
that takes an array as argument and iterates over the array to call GCServer.item().
this10.js would not have lines like:
item(223,"Person__1425","shimon","\/system\/0000\/0032\/shimon.png",42.4086,-71.1276,"conn bene food adv art scavhunts charity cornerfun mgames cycling hoodwork vol bigtheater pubworks parties localhelp critmobs artsuggest pubstunts stretchme stealth pchal pgrowth convo beauty raok","unlatched","unreachable unverified 1234900840",null,{"comm":"unreachable unverified 1234900840","qualities":"courage boldness brains helpfulness stealth strength kindness"});
item(224,"Person__1423","shimon23","\/system\/0000\/0032\/shimon.png",42.4086,-71.1276,"conn bene food adv art scavhunts charity cornerfun mgames cycling hoodwork vol bigtheater pubworks parties localhelp critmobs artsuggest pubstunts stretchme stealth pchal pgrowth convo beauty raok","unlatched","unreachable unverified 1234900840",null,{"comm":"unreachable unverified 1234900840","qualities":"courage boldness brains helpfulness stealth strength kindness"});
but instead like:
GCServer.items([
(223,"Person__1425","shimon","\/system\/0000\/0032\/shimon.png",42.4086,-71.1276,"conn bene food adv art scavhunts charity cornerfun mgames cycling hoodwork vol bigtheater pubworks parties localhelp critmobs artsuggest pubstunts stretchme stealth pchal pgrowth convo beauty raok","unlatched","unreachable unverified 1234900840",null,{"comm":"unreachable unverified 1234900840","qualities":"courage boldness brains helpfulness stealth strength kindness"}),
(224,"Person__1423","shimon23","\/system\/0000\/0032\/shimon.png",42.4086,-71.1276,"conn bene food adv art scavhunts charity cornerfun mgames cycling hoodwork vol bigtheater pubworks parties localhelp critmobs artsuggest pubstunts stretchme stealth pchal pgrowth convo beauty raok","unlatched","unreachable unverified 1234900840",null,{"comm":"unreachable unverified 1234900840","qualities":"courage boldness brains helpfulness stealth strength kindness"}),
])
so we would have the wrapper GCServer.items() for bulk updates while retaining GCServer.item() for single updates.
> >- model.js:
> > - what is the reasoning behind in_city and with_atag defined here and
> > and not in foundation/resource.js?
>
> I think the files are not so clearly named, but the idea is that
> foundation/resource.js defines a general purpose in-memory database
> mechanism that could be (theoretically) used in other people's
> javascript projects. gcapi/models.js provides additional functionality
> that's specific to the viewer.
oh, i see, makes sense now.
cheers,
marmorkuchen
--
_ ascii ribbon campaign .oOo. GCSd-s:+aC++ULB+++W++M+PS+++Y+
( )
X Merge made by octopus.
/ \
Joe Edelman
>http://github.com/marmorkuchen/groundcrew-viewer/commit/4fe3485d1f2369ff9d353ed2125f7a80ef2574c6
>until recently, without thinking much about 'atag', i would have thought
>it stands for agent tag. but if you look at it closely, it clearly can't be.
>it would be easier for a groundcrew rookie if it was named, for
>instance, action_tag, an idea you do not seem to be opposed in
>principal, see item_tag, city_id or thumb_url.
>but then i see atags_to_upfors should become action_tags_to_upfors which
>already looks bloated. since you don't use upfor_tags, would it be okay
>to use action(s) instead of action_tag(s)?
think maybe upfor should be called utags or something! Let's just leave
this stuff as is for now. I think both atags and upfor are things
people will need to be educated about to understand anyways, so it's not
like we can really pick a self-documenting name.
>well, i would like the Item namespace to stay as it is, but do something to
>these all these functions in src/gcacpi/gcserver.js - like putting them into the
>namespace GCServer.
server comes, and I'm pretty attached to the current format. I think it
is non-techie and super easy to read. One of my goals is for people to
write API libraries in other languages that parse this idea() item()
event() format. Even just making it slightly more complex, with arrays
or with a namespace prefix, will make it a little less likely that
people will do stuff like that.