[aida] Aida comprehensive documentation: a newbie experience
Offray Vladimir Luna Cárdenas
offray at riseup.net
Mon Jul 25 18:33:41 CEST 2011
El 24/07/11 14:31, Janko Mivšek escribió:
> Hi Offray,
> Welcome to the list and thanks a lot for your thoughts, that's what we
> need and this is what give us encouragement to be better and better!
> About documentation: yes, that is major Aida weakness and I don't know
> exactly how to solve it. I'm simply better in thinking and coding, not
> in writing, so any help here is really appreciated. We will soon have a
> ToDo example, which shows all that bleeding edge Aida features for
> building so called Single page (SP) applications, as an addition to
> traditional web apps shown in current tutorial.
> Support for a combination of traditional and SP apps will put Aida on
> the web frontiers, just that without documentation no-one will know
> that. Yes, you are very right, lack of docs is also a reason for a lack
> of visibility of what all Aida is capable.
Agree. This situation remembers a local joke about the seeing the woman
of your dreams and saying to your friends "she is my girlfriend, but she
don't know" and the joke is not about confidence that she _will_ be your
girlfriend, but about _being_ now and not knowing. Aida can be pushing
the envelope and exploring the frontier of the web, but without proper
documentation, is like if the woman of your dreams doesn't know about
being your girlfriend. Today I tried the tutorial again, using it in
pair with the Spanish translation. I found some errors in my previous
implementation, but still I have not joy and I have found just a
different error. The way I found the errors was seeing the subtle
differences between Spanish and English tutorial. In the first one you
have a typographical convention for method names, so you understand that
addresses := OrderedCollection new
addresses isNil ifTrue: [self initAddresses].
is really two separate methods: initAddresses and addresses (yes, silly
me that would have to notice at first, but with the typographical
convention was really easy to find, even without a deeper understanding
of Smalltalk). Also while the English tutorial say things like:
"add a class method for fast ADemoAddress creation:"
The Spanish say:
Añade un método de clase para creación rápida de ADemoAddress (recuerda
que debe ser de clase no de instancia. Debes presionar antes Class en el
panel de la clase, antes de crear el método)
Add a class method for fast ADemoAddress creation (remember that it
should be a class method, not an instance one. You should press Class in
the panel of the class before creating the method).
That part in the parenthesis can be a real difference for a newbie, but
even in that case, I still have to decipher:
"create an initialize method, accessors for the ADemoAddressBook instvar
addresses and addition method, which will also set a back reference from
address to its parent, the address book. This back reference will come
handy later for navigation from address page back to address book:
And I just populated the browser with the following code after that
paragraph, but when I get the Error:
I start to wonder if I have deciphered the paragraph well.
With the Seaside tutorial the terms are explained at length, for example:
But first let us discover what is necessary:
Every newly-created component is inherited from WAComponent.
Every component needs a method called #renderContentOn: accepting a
Components that shall be root components need a class method called
So what does that mean?
WAComponent is the basic component provided by Seaside. That means every
visible component inherits from WAComponent. There are many more
components you can use, like WATask, but more on that later. For now,
just keep WAComponent in mind.
While inheritance is one requirement, the rendering part is another. To
generate HTML code from within your Smalltalk code, you need a renderer.
WAComponent ensures that the method #renderContentOn: is called. By
giving the method a renderer you have access to all WACanvas methods
provided by Seaside. So let us keep that theoretical stuff in mind and
create the first component of our ToDo Application
So you're creating a mental model of how Seaside works at the same time
that you're going to the tutorial (that's why is a 12 chapters, 212
> About Smalltalk knowledge for newbie: is Seaside HPI tutorial good even
> for a complete non-Smalltalker? How they achieved that, AFAIK they don't
> learn Smalltalk basics in this tutorial?
No, the HPI tutorial is it not good for a complete non-Smalltalker, but
they point to really good sources of documentation for newbies as
complementary/parallel readings (is what I'm doing) at the same time
thay provide this mental model while they advance in the tutorial. You
can find things like this in the introductory chapters (I would like to
point the specif part, instead of pasting large chunks here, but may be
the ugly urls of Seaside don't work for that, so there it comes, without
the embedded links):
The Seaside Tutorial has mainly been made for people with basic
knowledge of object-oriented programming especially with Smalltalk, but
it is suitable for others as well. We try to reduce the fundamental
knowledge on the elements demanded here. If you have suggestions for
better descriptions of any part, please send us your feedback.
Object-oriented programming should be known well enough that words like
class, object, inheritance or reuse do not put question marks in your
eyes. Here, no links are given, just because there is a wealth of
standard literature and we do not want to prefer any of it.
Smalltalk (as a programming language) has to be known well, because
Seaside itself only exists in this language. Should you have any
problems with it, have a look at the following link:
Smalltalk Free Books
Squeak is used as the Smalltalk environment of choice in this tutorial,
but Seaside has also been implemented on other common Smalltalk
platforms (see the corresponding documentation). For more help with the
treatment of Squeak, the following links are quite helpful. However, we
try to use particularities of the Squeak Smalltalk dialect as seldom as
Squeak by Example (ebook)
Squeak Web site
They have chosen also a default environment for explaining Seaside, the
one that is most while available and without hidden cost: Squeak (Pharo
would work also). So, I think that this kind of default experience in a
widely used environment should be part of the tutorial. I suggest to use
Pharo One Click Experience as the environment for the construction of
such comprehensive documentation, with mentions, short references and
explanations about other environments (for example installing on
different Smalltalk flavors).
> About our web frameworks to form a strong front and compete with others,
> yes, this is a very stated goal and specially with Jtalk work by Nicolas
> Petton for client-side web apps we can actually "penetrate" to outside
> designed for programming at large, while Smalltalk is. We have therefore
> a chance here and both Aida and Iliad have plans/working intensively on
> that area.
Jtalk is really awesome and I hope this integration going deeper and
showing the potential of Smalltalk in the web (by the way, ¿why the
split of people between Iliad and Aida?). One of the things that is most
impacting after installing and running Seaside is the integration with
JQuery and JQueryUI, showing parallel demos of them and the Seaside code
for getting that working. Knowing that you don't have to learn another
language to get that dynamic behavior on web pages with modern and
away in that sense, and could learn from the way that Seaside makes the
integration with JQuery available (seems that this kind of integration
of JQuery and Aida is not available yet)
> About persistence: you probably already noticed that Smalltalkers tend
> to avoid RDBses as much as possible. One reason is that image itself is
> kind of a database and image based pesistence works surprisingly well
> for small to middle sized projects. And for larger we have a Gemstone
> with which we can scale up to the sky :) It is true that it is not open
> source, but this actually don't count much in otherwise small Smalltalk
> community. And free GS version is more than enough for a quite large
Yes. Image based persistence is, for me, another selling point of
Smalltalk. Carrying your One Click Experience in a thumb drive and
knowing that you can run it everywhere with all your data saved there is
key for my intended project. More in a another mail.
> So, ok, let me finish too for now and rather publish a ToDo example
> ASAP, so that we will have a foundation for some more docs .. :)
Ok. But as I teach teenagers and adults about informatics, I wonder, as
they do, about the use in "the real world" of this kind of apps. I mean:
there is any people using the ToDo app for something besides explaining
how the framework works, and, if this is the case, why we don't know of
public sites like "remember the milk" powered by them. I think that we
need another kind of examples in the tutorial, more in concordance with
what social web has to offer and the problems we can solve there, but
this will be topic of the mentioned "other mail"
> Thanks again and keep posting more!
Thanks to you Janko and to this helpful community. The more I can learn
about Seaside, the more I will try to give feedback to Aida and
hopefully help with documentation, not only in constructive criticism
but also in some writing.
More information about the Aida