SDK
==================================

.. note:: Only available since 4.2

The PiAnoS Software Development Kit is an alternative release that includes the necessary files to modify PiAnoS. It differs from the regular download in that it contains:

	- the source code of the frontend and backend Javascript applications (the regular download contains only the minified versions)
	- the standalone frontend test HTML and PHP files
	- the source ``.rst`` files of this documentation (to be used with `Sphinx <http://sphinx-doc.org/>`_)
	- more bugs due to untested features
	
Downloads
-------------------------

You can download the SDK here:

	- 4.2.1: `pianos-sdk-4.2.1.tar.gz <https://ips-labs.unil.ch/pianos/downloads/pianos-sdk-4.2.1.tar.gz>`_
	- 4.2.0: `pianos-sdk-4.2.0.tar.gz <https://ips-labs.unil.ch/pianos/downloads/pianos-sdk-4.2.0.tar.gz>`_

.. note:: This SDK is in essence not meant to be deployed as such as a production instance, but unfortunately we are not distributing the build script. Therefore, for the time being, you are not able to automatically produce a release tarball (the "regular download") from the SDK - as we are doing from our SVN. This can be fixed, but I have no time for this currently.


Getting started
-------------------------

Once you have the SDK, you have several main courses of action:

	- If you intend to modify only the frontend (e.g. so as to embed it in your own application) you do not need to install anything. Just open ``demo.html`` (you don't even need a web server at this point), and see the interface in action. You can start modifying the HTML/Javascript code in place.
	
	- If you want to link your modified frontend to a custom server, you'll need to deploy the files to a web server (Note that you do not need to install or use the PHP part at all). Have a look at ``pianos4.js`` to see which hooks you can define [#f1]_, tweak them in the HTML file and implement the server responses.
	
	- If you want to use the full stack (frontend+backend+server) you'll have to install the database and the PHP files. For this you should first follow the regular installation procedure (see :doc:`../admin/install/index`). Then you should modify the ``settings-local.php`` file to not use the minified .js files (if you intend to modify the Javascript part).

Depending on the scope of your modifications, you might want to review the :doc:`architecture` first, so as to find your way in the source code.
 	
Then it might be a good idea to have a look at the :doc:`examples` to have an idea of what is possible.

Armed with your concept, a deep understanding of the source, and the right tools (see below), you can start coding !

	
Tools
-------------------------
	
In theory you can develop PiAnoS just using the stock tools available on your system (e.g. Notepad and Internet Explorer on Windows, vim and Epiphany on Debian Linux, etc.).

In practice, you will want serious tools to do anything beyond correcting a typo in an obscure page of the inline help. Of course, if you are a seasoned web developer and already have tools you are proficient with, just skip this paragraph.

	- Firefox + Firebug. Although other browsers now have built-in debugging facilities (F12 opens the developer panel for most of them), the Firefox + Firebug combo is a must in my opinion. Anyhow, you need a web debugging tool to track requests, their content, debug Javascript, tweak CSS classes, etc. You really do.
	
	- Notepad++, if you are on Windows. No excuses. I can't recommend anything for other systems as I don't use them to develop.
	
You will also need a version control system. You can use SVN, Git, etc. The choice is up to you, but because you are working on 3rd party code does not mean you can work without a VCS. For Subversion, see the `Vendor Branches <http://svnbook.red-bean.com/en/1.7/svn.advanced.vendorbr.html>`_ concept.

There are optional tools/software packages you might need (e.g. Sphinx for the documentation), but these are discussed in the relevant pages.


.. rubric:: Footnotes

.. [#f1] The parameters ``loadResults`` and ``saveResults`` are especially interesting: the former is called when the application starts, to get the results to display, and the latter is called when the user clicks the Save button.