.. _scriptlets:

Scriptlets
==========

Scriptlets are small python modules that you can add, edit and execute directly
inside the smartCommander. They give you total flexibility right to your fingertips.
To access the scriptlets menu you can either choose the **scriptlets** entry from
the bottom left drop down menu or use the hotkey:

**ctrl + 3** (Linux/Windows) / **cmd + 3** (Mac)

.. image:: img/scriptlets/scriptlets.jpg

To execute any scriptlet you can simply click it like any other command inside
smartCommand.

Scriptlets location
-------------------

The scriptlets are python files being read directly from your disk. This is the
default location where scriptlets live in::

    Linux: /home/[username]/cragl/smartCommand/scriptlets
    Mac: /Users/[username]/cragl/smartCommand/scriptlets
    Windows: C:\users\[username]\cragl/smartCommand/scriptlets

In the `Settings <settings.html>`_ section you can customize this path and point
to a different path. This gives you the flexibility to share and use scriptlets
within your team or to sync scriptlets over different machines.

smartCommand will scan the above mentioned folder for python files. These files
contain the **.py** file extension. You can temporarily hide any scriptlet by
renaming a scriptlet to start with an underscore. For instance given the
following scriptlets::

    rendermanager.py
    startrender.py
    _test.py

Only the first two scriptlets will be listed inside the scriptlets section because
**_test.py** starts with an underscore and will be invisible for smartCommand.

Getting started with pre defined scriptlets
-------------------------------------------

By default the scriptlets menu is empty. Here you can download some pre defined
scriptlets that you can use as a starting point:

Download-sciptlets_

The scriptlet editor
--------------------

Let's create a new scriptlet using smartCommands scriptlet editor. Click in an
empty space and choose **New scriptlet** from the context menu.

.. image:: img/scriptlets/new_scriptlet.jpg

The scriptlet editor launches which lets you create a new scriptlet. By default
it uses a template that you can use to fill with your commands.

.. image:: img/scriptlets/scriptleteditor.jpg

At the top of the scriptlet editor you need to add a name for this scriptlet.
The middle section is obviously the most important section. In here you can
add your logic. The scriptlet editor supports line numbers and code highlighting.

At the bottom of the editor you will find an **execute** button to execute the
scriptlet and test its behavior. When you are finished click the blue **Create** button.
This will save your code as a python module with your entered name into the scriptlets
root directory as listed above. As mentioned, this root directory can be changed
to a custom path in the `Settings <settings.html#the-settings-section>`_ section.

The scriptlet editor offers enough functionality to quickly create any needed
functionality. But you can always switch to an external editor or IDE and continue
working in there.

Context menu
------------

We have already seen that we can right click in an empty space in the scriptlets
list to create a new scriptlet. If you right click directly on any scriptlet
you will have an additional command to edit the currently selected scriptlet.

.. image:: img/scriptlets/scriptlets_contextmenu.jpg

Anatomy of a scriptlet
----------------------

Let's have a look at the building structure of a scriptlet::

    """Add Scriptlet description in here."""

    import nuke

    def execute():
        """Entry point function to execute."""
        pass


This is basically a normal python module. At the top (*Line 1*) you can add your doc string
for this command in order to describe what this scriptlet does. This information
will then be visible in a tooltip once you hover over your scriptlet as seen below.

.. image:: img/scriptlets/tooltip.jpg

In *line 3* we import the nuke module to make all nuke internal functions accessible.
You can import any other module from python's standard library in here and import
external modules that are in your NUKE_PATH.

Each scriptlet needs to contain an **execute()** function as seen in *line 5*.
This is the main entry point that gets executed once you click the scriptlet in
the smartCommander. This function is mandatory, everything else can be freely edited to your needs.

Using a custom scriptlet template
---------------------------------

If required, you can use a custom scriptlet template that will be used whenever
you create a new scriptlet. In order to apply one, please create a **scriptlet.py**
python file under the following path, depending on your used operating system::

    Linux: /home/[username]/cragl/smartCommand/scriptlet.py
    Mac: /Users/[username]/cragl/smartCommand/scriptlet.py
    Windows: C:\users\[username]\cragl/smartCommand/scriptlet.py

You can freely edit this custom template as required. The content will be used
the as a starting point the next time you create a new scriptlet. Please keep in
mind to include an **execute()** function in your template so that the scriptlet
can be executed.

.. download links
.. _Download-sciptlets: http://www.cragl.com/scriptlets