Re: documenting /components/organize_app/
Joe Edelman
documention for developers.
>- iirc, Joe said we could change
>
> marker_clicked: function(tag, state) {
> squad = state.squad || 'your_personal_squad';
> Viewer.go('/organize/'+ squad +'/:city/' + tag);
> },
>
>to
>
> marker_clicked: function(tag, state) {
> Viewer.go('/organize/:squad/:city/' + tag);
> },
>
>right?
>
>
No, the latter version is missing some functionality. You could say:
state.squad = state.squad || 'your_personal_squad';
Viewer.go('/organize/:squad/:city/' + tag);
>- in organize_app.js, i see the constant number 16 in
>
> if (state.item.startsWith('Person')) Viewer.render_item('organize_agent', 16);
>
>i can also see it in src/viewer/map.js
>
> if (zoom < 16) zoom = 16;
>
>would it make sense to have a 'constant' like
>
> Viewer.MIN_ZOOM = 16;
>
Yes, constants should be centralized, maybe. Those two aren't the
same, though. The latter is the minimum zoom for focusing on oneself,
and the former for other agents. I'm not sure how this kind of thing
should be organized in the source. I guess I propose waiting until we
have other similar values we may want to centralize or have tunable by
users.
> actually, it would be even nicer to have a mechanism which makes all
> templates of organize children of the div 'app_organize', so we can
> drop the prefixes.
Agreed. In fact, let's not do these renames, let's just come up with
that mechanism.
In some cases, we already don't need the div IDs anymore. I changed
Viewer.render() recently to pay attention to class names instead of ids.
It looks for DOM elements that have the class name of the app name and
the current app action both, and .onscreen()s them.
>- iirc, Joe mentioned that he likes the term map windows better than
> info windows (as introduced by GoogleMaps). me too. :) shall
> occurrences of info window/iw be replaced by map window/mw?
Yes, but again, let's just wait until we have the mechanism mentioned
above.
>- there are two forms that send data to the server. their ids are
> prefixed with 'send_'. is that (going to be) the rule for all form ids
> (and hence also callback functions in the app's controller) for stuff
> that is send from forms to the server? or could we actually drop the
> prefix, because it doesn't really serve a purpose? what would be
> gained from knowing by the function's name that it sends stuff to the
> server?
send_ can be dropped. I think you started that, didn't you?
>- some functions in the app have the argument order (state, another_arg)
> and some have (another_arg, state). imho, state is the most 'stable'
> part; an argument to nearly all functions. hence i reckon this should
> always be the first argument. as far as i can see, this would require
> a slight change in the call of Viewer.dispatch in
> /src/viewer/livehtml.js and /src/viewer/base_viewer.js.
Don't make this change. I understand your rationale, but I find it
handy to have the first argument be the one you're most likely to
actually use. These are event handlers, where this is true, and they
might not pay attention to all their arguments. So we stick "extra"
arguments at the end, there in case they're needed, but functions need
not even know they're there. This is a javascript convention.
>- build_pos_form: while i appreciate the button's text to encourage the
> user to build a positive experience, i'd rather set the form's id
> (callback function) to 'display_idea_catalog_form' to make it clearer
> to the code's reader what is going to happen.
Go for it.
>- i am a friend of having a naming structure that doesn't require a mix
> of prefix and suffix parsing/building to address things. for forms i
> would suggest a naming scheme of 'form_<what it does>' which is then
> the same for the form's id and the function name. no suffix
> '_submitted' necessary, although it implies there is only one action
> possible (is there something else than submit?). then, also taking
> previously mentioned issues into account,
> 'send_assignment_form/'send_assignment_form_submitted' would become
> 'form_assignment'.
Okay, I agree with your criticism but not with the suggested solution.
I want functions inside the apps that handle events to be named like
event handlers, not like nouns. Even handlers typically have names in
app code like "form_x_submitted" or "did_submit_form_x" or so on. The
name implies an action.
--Joe
--
J.E. -- http://nxhx.org -- 413.250.8007
>
agent marmorkuchen
* Joe Edelman <joe.e...@gmail.com> [2009-02-27 14:17 -0500]:
>
> This is a response to 1000 questions by sebastian, who is writing some
> documention for developers.
>
> >- iirc, Joe said we could change
> >
> > marker_clicked: function(tag, state) {
> > squad = state.squad || 'your_personal_squad';
> > Viewer.go('/organize/'+ squad +'/:city/' + tag);
> > },
> >
> >to
> >
> > marker_clicked: function(tag, state) {
> > Viewer.go('/organize/:squad/:city/' + tag);
> > },
> >
> >right?
> >
> >
> No, the latter version is missing some functionality. You could say:
>
> state.squad = state.squad || 'your_personal_squad';
> Viewer.go('/organize/:squad/:city/' + tag);
hm, since :squad is just a placeholder, couldn't we have that default
value defined where :squad is replaced? also, the constant string
'your_personal_squad' is used at two different places at the moment
which might be reduced to one place.
> >- in organize_app.js, i see the constant number 16 in
> >
> > if (state.item.startsWith('Person')) Viewer.render_item('organize_agent', 16);
> >
> >i can also see it in src/viewer/map.js
> >
> > if (zoom < 16) zoom = 16;
> >
> >would it make sense to have a 'constant' like
> >
> > Viewer.MIN_ZOOM = 16;
> >
>
> Yes, constants should be centralized, maybe. Those two aren't the
> same, though. The latter is the minimum zoom for focusing on oneself,
> and the former for other agents. I'm not sure how this kind of thing
> should be organized in the source. I guess I propose waiting until we
> have other similar values we may want to centralize or have tunable by
> users.
well then Viewer.MIN_ZOOM (or Viewer.MIN_ZOOM_OTHERS if it is really
used only for other agents) and Viewer.MIN_ZOOM_SELF.
and put that into /src/viewer/base_viewer.js?
> > actually, it would be even nicer to have a mechanism which makes all
> > templates of organize children of the div 'app_organize', so we can
> > drop the prefixes.
>
> Agreed. In fact, let's not do these renames, let's just come up with
> that mechanism.
>
> In some cases, we already don't need the div IDs anymore. I changed
> Viewer.render() recently to pay attention to class names instead of ids.
> It looks for DOM elements that have the class name of the app name and
> the current app action both, and .onscreen()s them.
>
> >- iirc, Joe mentioned that he likes the term map windows better than
> > info windows (as introduced by GoogleMaps). me too. :) shall
> > occurrences of info window/iw be replaced by map window/mw?
>
> Yes, but again, let's just wait until we have the mechanism mentioned
> above.
alright, will think about it, when i am done with the docu (and the
issues on the way towards it are fixed).
> >- there are two forms that send data to the server. their ids are
> > prefixed with 'send_'. is that (going to be) the rule for all form ids
> > (and hence also callback functions in the app's controller) for stuff
> > that is send from forms to the server? or could we actually drop the
> > prefix, because it doesn't really serve a purpose? what would be
> > gained from knowing by the function's name that it sends stuff to the
> > server?
>
> send_ can be dropped. I think you started that, didn't you?
hm, yeah, but might have been coincidentally. :)
> >- some functions in the app have the argument order (state, another_arg)
> > and some have (another_arg, state). imho, state is the most 'stable'
> > part; an argument to nearly all functions. hence i reckon this should
> > always be the first argument. as far as i can see, this would require
> > a slight change in the call of Viewer.dispatch in
> > /src/viewer/livehtml.js and /src/viewer/base_viewer.js.
>
> Don't make this change. I understand your rationale, but I find it
> handy to have the first argument be the one you're most likely to
> actually use. These are event handlers, where this is true, and they
> might not pay attention to all their arguments. So we stick "extra"
> arguments at the end, there in case they're needed, but functions need
> not even know they're there. This is a javascript convention.
ok, i can see its usefulness now.
> >- build_pos_form: while i appreciate the button's text to encourage the
> > user to build a positive experience, i'd rather set the form's id
> > (callback function) to 'display_idea_catalog_form' to make it clearer
> > to the code's reader what is going to happen.
>
> Go for it.
well, that has become obsolete now.
> >- i am a friend of having a naming structure that doesn't require a mix
> > of prefix and suffix parsing/building to address things. for forms i
> > would suggest a naming scheme of 'form_<what it does>' which is then
> > the same for the form's id and the function name. no suffix
> > '_submitted' necessary, although it implies there is only one action
> > possible (is there something else than submit?). then, also taking
> > previously mentioned issues into account,
> > 'send_assignment_form/'send_assignment_form_submitted' would become
> > 'form_assignment'.
>
> Okay, I agree with your criticism but not with the suggested solution.
> I want functions inside the apps that handle events to be named like
> event handlers, not like nouns. Even handlers typically have names in
> app code like "form_x_submitted" or "did_submit_form_x" or so on. The
> name implies an action.
ok, makes sense. x_submitted then? although i am not sure if that is
applicable anymore with the new form action handlers, so probably forget
about it. :)
one thing i had forgotten previously:
item_status: function(state) { return "This agent is available."; },
item_believesin: function(state) { return " "; },
item_celebrates: function(state) { return " "; },
item_helpwith: function(state) { return " "; },
item_didrecent: function(state) { return " "; },
this 'item' always seems to be an agent, never a landmark. call it
agent_* then?
bye,
marmorkuchen
--
_ ascii ribbon campaign .oOo. GCSd-s:+aC++ULB+++W++M+PS+++Y+
( )
X Betrachte einen Stock - ein Ende ist Yin, das andere Yang. Welches
/ \ ist wichtiger? Konfuzius: Der Stock selbst! Zen: Da ist Scheisse am Stock!
Joe Edelman
>>
>> state.squad = state.squad || 'your_personal_squad';
>> Viewer.go('/organize/:squad/:city/' + tag);
>
>hm, since :squad is just a placeholder, couldn't we have that default
>value defined where :squad is replaced? also, the constant string
>'your_personal_squad' is used at two different places at the moment
>which might be reduced to one place.
Okay, I'll do it. I thought of a clean way.
>> Yes, constants should be centralized, maybe. Those two aren't the
>> same, though. The latter is the minimum zoom for focusing on oneself,
>> and the former for other agents. I'm not sure how this kind of thing
>> should be organized in the source. I guess I propose waiting until we
>> have other similar values we may want to centralize or have tunable by
>> users.
>
>well then Viewer.MIN_ZOOM (or Viewer.MIN_ZOOM_OTHERS if it is really
>used only for other agents) and Viewer.MIN_ZOOM_SELF.
>and put that into /src/viewer/base_viewer.js?
Haha, just got rid of base_viewer.js. Let's do this, but wait until we
have a few more constants. I'm not sure if the Viewer namespace is a
good place for them. I think there will be a whole bunch of
user-specific settings, and they may be fetched and saved from the
server, etc.
Let's wait. If you're worried about forgetting, you can file a ticket
and attach it to a LATER milestone or something.
>> > actually, it would be even nicer to have a mechanism which makes all
>> > templates of organize children of the div 'app_organize', so we can
>> > drop the prefixes.
>>
>> Agreed. In fact, let's not do these renames, let's just come up with
>> that mechanism.
>
>alright, will think about it, when i am done with the docu (and the
>issues on the way towards it are fixed).
Cool.
>ok, makes sense. x_submitted then? although i am not sure if that is
>applicable anymore with the new form action handlers, so probably forget
>about it. :)
It's still applicable. The _submitted routines are run BEFORE the
form's action is followed to the URL it points to. The idea is to
separate data processing related to the form submit (which goes in
_submitted) from the navigational properties of the form. See
livehtml.js.
>item_status: function(state) { return "This agent is available."; },
>item_believesin: function(state) { return " "; },
>item_celebrates: function(state) { return " "; },
>item_helpwith: function(state) { return " "; },
>item_didrecent: function(state) { return " "; },
Just ignore these for now. They will be changed shortly.
Regards,
Joe