amber/documentation.html

---
layout: default
title: Jtalk Smalltalk - documentation
---

<div class="box last doc" id="documentation">
  <h2>Documentation</h2>
  <div class="content">

    <h3>Disclaimer</h3>

    <p class="warning">This documentation is a work in progress. If you find an error in the documentation, please <a href="https://github.com/NicolasPetton/jtalk/issues">file an issue</a>.</p>
    
    <p>This documentation <strong>doesn't aim to teach Smalltalk</strong>. Knowledge of Smalltalk is needed to understand the topics covered in this documentation. If you want to learn the Smalltalk language, you can read the excellent <a target="_blank" href="http://pharobyexamle.org">Pharo By Example</a> book.</p>


    <h3>Introduction</h3>

    <p class="information">Jtalk is a young piece of code and evolves quickly. Some features are still incomplete and you may very well encounter bugs, in which case you can <a href="https://github.com/NicolasPetton/jtalk/issues">file an issue</a> or a pull request on the <a href="https://github.com/NicolasPetton/jtalk">repository</a>.</p>

    <p>Jtalk is an implementation of the Smalltalk-80 language. It allows developers to write client-side heavy web applications in Smalltalk. Jtalk includes an integrated development environment with a class browser, workspace and transcript.</p>

    <p>Jtalk includes the following features:</p>
    <ol>
      <li>It is semantically and syntaxically equivalent to <a href="http://www.pharo-project.org">Pharo Smalltalk</a> (the implementation considered as the reference)</li>
      <li>It is written in itself and compiles into efficient JavaScript</li>
      <li>A canvas API similar to <a href="http://www.seaside.st">Seaside</a> to generate HTML</li>
      <li>A <a href="http://www.jquery.com">jQuery</a> binding</li>
    </ol>

    <h3>Differences with other Smalltalk implementations</h3>

    Jtalk has some differences with other Smalltalk implementations. Because it maps Smalltalk constructs one-to-one with the JavaScript equivalent, including Smalltalk classes to JavaScript constructors, the core class library is simplified compared to the one in Pharo Smalltalk. The following list explains the main differences:
    <ul>
      <li>There is no identity in Jtalk. Especially, there is no <code>==</code> method, or <code>Symbol</code> class. For convenience and compatibility, the Jtalk parser will recognize symbol literals as strings.</li>
      <li>The collection class hierarchy is simpler compared to most Smalltalk implementations. There is no <code>OrderedCollection</code>, <code>Set</code> or <code>SortedCollection</code>. However, the size of arrays is dynamic, and they behave like an ordered collection. They can also be sorted with the <code>#sort*</code> methods.</li>
      <li>The <code>Date</code> class behaves like the <code>Date</code> <em>and</em> <code>TimeStamp</code> classes in Pharo Smalltalk. Therefore both <code>Date today</code> and <code>Date now</code> are valid in Jtalk.</li>
      <li>Jtalk use solely <code>=</code> to test object equality and not the <code>#hash</code> method.</li>
    </ul>

    <h3>Committing changes to disk with the web-based IDE</h3>
    
    <p>The class browser is able to commit changes to disk. The <code>commit category</code> button will send a PUT request with the compiled JavaScript code of all classes in the selected class category in a file named <code>js/CATEGORY.js</code>.</p>
    <p>The easiest way to enable committing is probably to setup a webdav with Apache.</p>
    <p class="information">The following steps explain how to setup a webdav for Jtalk with Debian, but the setup on OSX and other Linux distros should be similar.</p>
    <h4>Installing Apache and enabling the dav module</h4>
    <p>Evaluate the following as root:</p>
    <pre><span class="prompt">~#</span> <span class="kbd">apt-get install</span> <span class="kbd var">apache2</span>
<span class="prompt">~#</span> <span class="kbd">a2enmod</span> <span class="kbd var">dav</span>
<span class="prompt">~#</span> <span class="kbd">a2enmod</span> <span class="kbd var">dav_fs</span></pre>

    <h4>Creating a password for the webdav</h4>
    <pre><span class="prompt">~#</span> <span class="kbd">htpasswd -c /etc/apache2/htpasswd-webdav <span class="kbd var">USERNAME</span></span></pre>

    <h4>Setting up the webdav directory</h4>
    <p>Add the following lines to the default vhost (in <code>/etc/apache2/sites-available/default</code>):</p>
    <pre>Alias /jtalk/ "/path/to/jtalk/"
&lt;Directory "/path/to/jtalk/"&gt;
      Options Indexes MultiViews FollowSymLinks
      DirectoryIndex index.html
      AllowOverride None
      Order allow,deny
      allow from all

      Dav on

      AuthType Basic
      AuthName "jtalk"
      AuthUserFile /etc/apache2/htpasswd-webdav
      &lt;LimitExcept GET OPTIONS&gt;
            Require valid-user
      &lt;/LimitExcept&gt;

&lt;/Directory&gt;</pre>
    <p>Make sure the group <code>www-data</code> has required rights to make changes to files in the webdav directory.</p>
    
    <h4>Restarting Apache</h4>

    <p>To restart Apache, evaluate the following: </p>
    <pre><span class="prompt">~#</span> <span class="kbd">/etc/init.d/apache2</span> <span class="kbd var">restart</span></pre>
    <p>and go to <code>http://localhost/jtalk/</code>.</p>
    <p>The class browser should now be able to commit changes to disk.</p>

    <h3>The counter example</h3>

    <p>The following example is the traditional Seaside-like multi-counter application. The buttons at the bottom of each counter increase or decrease the counter.</p>

    <div id="counters"></div>
    <script type="text/javascript">
      jQuery(document).ready(function() {'#counters'._asJQuery()._append_(smalltalk.Counter._new())._append_(smalltalk.Counter._new())});
    </script>

    <p>Open a  <button onclick="smalltalk.Browser._openOn_(smalltalk.Counter);">browser</button> on the <code>Counter</code> class in the <code>Canvas</code> class category.
    <p>Each Jtalk widget is a subclass of <code>Widget</code>. A widget is a graphical component. The <code>#renderOn:</code> method is used to generate HTML using the HTML canvas.</p>

    <p class="information">Rendering methods should be placed in the <code>rendering</code> method protocol, and action methods in the <code>actions</code> protocol.</p>

    {% highlight smalltalk %}renderOn: html
    html h1 with: count asString.
    html button
    	with: '++';
    	onClick: [self increase].
    html button
    	with: '--';
    	onClick: [self decrease] {% endhighlight %}

    <h3>The HTML canvas</h3>
    <h3>Widgets</h3>
    <h3>jQuery</h3>

  </div>
</div>

<!-- Add anchors to doc titles and build the dropdown menu -->
<script type="text/javascript">
  jQuery('#menu .main').append("<ul id='dropdown'></ul>");
  jQuery.each(jQuery('.doc h3'), function(i, heading) {
  	jQuery(heading).attr({'id': jQuery(heading).text().replace(/ /g,"_")});
  	jQuery(heading).html(i + ". " + jQuery(heading).html());
  	jQuery('#dropdown').append("<li><a href='#" + jQuery(heading).attr('id') + "'>" + jQuery(heading).text() + "</a></li>");
  	jQuery(heading).html(jQuery(heading).html() + " <a href='#" + jQuery(heading).attr('id') + "'>&para;</a>");
  });

  jQuery('#doc_link')
  	.bind('mouseenter', function() {jQuery('#dropdown').show()})
  	.bind('mouseleave', function() {jQuery('#dropdown').hide()});
  jQuery('#dropdown')
  	.bind('mouseenter', function() {jQuery('#dropdown').show()})
  	.bind('mouseleave', function() {jQuery('#dropdown').hide()})
  	.bind('click', function() {jQuery('#dropdown').hide()});
</script>