.. _app-dev-tutorial:

========
Tutorial
========

:Author:    Stefan Eletzhofer
:Date:      |today|

Abstract
========

In this short tutorial, we'll walk through the process of:

- creating a *nexiles|elements app*
- packing and uploading a *nexiles|elements app*
- launching the app.

We'll create a simple app called `tutorial`.

.. note:: Need to explain the nxtools configuration.


Prerequisites
=============

All new apps are derived from a **template app**.


Template App
------------

An example app which can be used as a template app ships with this package
and can be found in the **apps** folder.

This template app needs to live in Windchill and can be located by a
specific **name** which can be configured in the configuration file.

The name of the template can be set in the global configuration file.


Configuration
-------------

The configuration file lives in **$HOME/.nxtools/default.ini**
or in **%windir%\.nxtools\default.ini** on Windows hosts.

The configuration defaults to::

    [nxtools]
    verbose=true

    ; to enable logging to a file set this to a path
    ; logfile=nxtools.log

    ; logging level
    loglevel = debug

    ; to enter the post-mortem debugger on exceptions
    ; set this to true
    post-mortem = false

    [apps]
    ; the name of the app template for the 'app-create' command
    app-template=template


.. important:: Although the name of the template app defaults to
               **template**, the name of the WTDocument has to be
               **nexiles.template.app**.
               The pre- and postfix are convention and get
               automatically set when a new app is uploaded.


To specify a container and folder for all apps, you should define something
like this in your configuration::

    [apps]
    ; the name of the app template for the 'app-create' command
    app-template-name=template
    app-container-name=TestProduct
    app-folder-path=/Default/apps


Uploading the Template app
--------------------------

To get started with app development, you should provide an template app::

    nxtools app-pack --source-dir apps/template/static --name template
    nxtools app-upload --source-dir apps/template/static --name template



Creating A *nexiles|elements app*
=================================

Steps to perform:

- create a initial app structure
- create a initial app package
- upload the package
- test the app.

Create initial app structure
----------------------------

To speed up the app creation process, we supply a *template* suitable for
bootstrapping the app development process.  The template app is stored on
the Windchill server.  To use it and create a initial structure for
our `tutorial` app, do::

    $ mkdir tutorial
    $ cd tutorial
    $ nxtools app-create --name tutorial

This command will fetch the template package from the server and unpack it
to a new directory `static`.

The `static` directory contains a special file `app-meta.json`, which
contains *meta data definitions* for the app, such as the app name and
description.  This file looks something like this::

    {
        "version":      "0.1dev"
        "thumbnail":    "images/gruenerpunkt.png",
        "app-url":      "index.html",
        "name":         "nexiles|elements template",
        "description":  "nexiles|elements app template"
    }

Please refer to the **nexiles|gateway App Specification** for a detailed
explanation of the keys of this file.  For now, just edit the `name` and
`description` fields.


Create a intial app package
---------------------------

Prior to uploading a new or updated app, we need to *pack* the application
to a *app package*.  To pack the app, issue::

    $ cd tutorial
    $ nxtools app-pack --name tutorial

The app package should now be in `static/build/tutorial-app.zip`.

Upload the app
--------------

Now that we have a app package, we are able to *upload* it.::

    $ cd tutorial
    $ nxtools app-upload --name tutorial

Test the app
------------

To open a local browser, do::

    $ nxtools app-open tutorial

Your configured web browser will open and you should see the template app
content, but served from the `tutorial` package.  In effect, we created a
copy of the `template` app.


.. vim: set ft=rst tw=75 nocin nosi ai sw=4 ts=4 expandtab: