amber/documentation.html

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

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

    <h3 id="intro">1. Introduction <a href="#intro">&para;</a></h3>

    <p class="warning">This documentation is a work in progress.</p>

    <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 id="differences-other-smalltalks">2. Differences with other Smalltalk implementations <a href="#differences-other-smalltalks">&para;</a></h3>

    <h3 id="committing">3. Committing changes to disk with the web-based IDE <a href="#committing">&para;</a></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>~# apt-get install apache2
~# a2enmod dav
~# a2enmod dav_fs</pre>

    <h4>Creating a password for the webdav</h4>
    <pre>htpasswd -c /etc/apache2/htpasswd-webdav USERNAME</pre>

    <h4>Setting up the webdav directory</h4>
    <p>Add the following lines to the default vhost (in /etc/apache2/sites-available/default):</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: <pre>~# /etc/init.d/apache2 restart</pre> and go to <code>http://localhost/jtalk/</code>.</p>
    <p>The class browser should now be able to commit changes to disk.</p>

    <h3 id="counter-example">4. The counter example <a href="#counter-example">&para;</a></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>

    <h3 id="html-canvas">5. The HTML canvas <a href="#html-canvas">&para;</a></h3>
    <h3 id="widgets">6. Widgets <a href="#widgets">&para;</a></h3>
    <h3 id="jquery">7. jQuery <a href="#jquery">&para;</a></h3>

  </div>
</div>