Documentation
The Shotgun Panel is a small and lightweight version of Shotgun which runs directly inside artist applications such as Maya and Nuke. In application where the Toolkit integration supports docking, the Shotgun Panel will appear seamlessly docked inside the UI. In other applications, it will be displayed as a normal window.
The Shotgun panel implements a subset of the concepts found inside the Shotgun web app, and includes an activity stream, access to Notes and Publishes, and a global search function that let's you quickly navigate around your project. You can work with Notes and launch Versions for playback in Screening Room. An extensive actions framework makes it possible to quickly and easily write add actions menu items to various points in the UI that run your custom code.
The Shotgun panel consists of a couple of main UI elements. On top you'll find a toolbar with buttons for navigation and searching. Right below the toolbar you have the details area which displays information about the item you are currently viewing. This details area is configurable, so if you want to display custom fields or have data that is extra important in your pipeline, it is easy to make it appear here. Lastly, you find a number of Content tabs. These all display listings of Shotgun data and makes it easy to navigate around in the Shotgun Panel to quickly browse things like publishes, review Versions, or see who is assigned to the Tasks linked to your current focus.
Below is a brief overview of the different tabs and features available in the Toolkit Shotgun Panel.
The activity stream works just like the activity stream in Shotgun - it shows you all the things happening in and around the object you are looking at: users creating Notes, Versions being submitted for review, and publishes being created by the pipeline. You can add new Notes directly from the activity stream and also reply to existing Notes. Attachments will show up automatically and clicking them will show a large preview.
Creating or replying to a Note is easy with the Shotgun Panel. Simply navigate to an activity stream or Note details page and click either create note or reply to note. A dialog will appear where you can type in the Note text. You can use @name notation if you want to send the Note to a specific person - this will add that person to the TO field of the Note automatically.
The Notes, Versions, publishes, and Tasks tabs all work the same way - by displaying data associated with the current item you are seeing. You can double click an item to focus on that item. Once you have navigated to a Publish, you can view the dependencies for that publish. This is useful if your pipeline is tracking dependency information and gives you instant access to how your assets are interconnected.
If you cannot find what you are looking for in the other tabs, try navigating to the info tab. This holds most of the Shotgun fields for your focused entity and you can click on the blue hyperlinks in order to navigate around to other Shotgun locations.
If you want to quickly navigate to another location or object in Shotgun, you can use the built-in search. This is similar to the global search in the Shotgun web application. Just start typing the name or description of what you are looking for, and results will be displayed once you have typed in three or more characters.
You can also use the Shotgun Panel to use Shotgun data to run operations in your scene. Similar to the Toolkit Loader, the Shotgun Panel has an actions system that makes it easy to register snippets of code to be triggered by a menu on an item in the browser. You can access actions from the detail area as well as from the listings. The actions button in the details area also contains some handy built-in functions to quickly jump to Shotgun and to refresh your current view.
The icon on the top left navigates you to your current work area. This is typically the Task that you are currently working on and is a quick way to get access to Notes, review Versions and other information relevant to what you are currently working on. This is also the location that the Shotgun Panel always starts focused on.
On the top right you find a button displaying the current user's thumbnail. This button will take you to a page which displays information associated with the current user. This includes
- All the publishes and Versions you have submitted
- Tasks that are assigned to you
- All note conversations where you are either participating or where the Note is relevant to you - e.g. Notes that are associated with Tasks that you are assigned to.
There are two main areas that you can configure extensively in the Shotgun Panel: The appearance of text in the UI and the actions you want to associate with data. The sections below outline how to control the configuration for the two systems.
The values in the detail area and the listings are both configurable through the shotgun_fields hook. You can subclass this hook and change the implementation in order to display the exact values you want:
Templating System
The hook supports a simple templating language, allowing for great flexibility. It also supports the HTML subset supported by Qt, so you can control color, font size, weight, etc. of your displayed values. The template language works in the following way:
-
Shotgun values are enclosed in
{brackets}, for example<b>Description:</b> {description}. When this template is rendered, the{description}part will be replaced with the description field value. -
If you want an optional pre- or post-fix for a value which is only shown if the value is not empty, you can use the syntax
{[Prefix]sg_field[suffix]}. The template{[Start: ]start_date} {[End: ]end_date}will renderStart: 12 July 2009 End: 14 July 2012if both values are populated butStart: 12 July 2009if end date isn't set. -
You can define fallbacks in the case some values are not set. For Shotgun Versions, the
artistfields takes precedence over thecreated_byfield in order to support a workflow where a producer submits versions on behalf of an artist. In this case, the Version will be created by the producer but theartistfield will be set to the artist. This, however, is not always the case - in some cases, artist is left blank in pipelines where artists submit their own work. When displaying versions, it is therefore useful to be able to check theartistfield first, and in case this isn't set, fall back on thecreated_byfield. This is done using the{field1|field2}syntax, for example:Created By: {artist|created_by}. You can combine this with optional fields too, e.g.{[Created By: ]artist|created_by}
This hook contains the following methods:
Controlling items appearing in lists
The get_list_item_definition() method returns a dictionary that controls the appearance of items in the various listings, given a Shotgun entity type. It returns a dictionary with the keys top_left, top_right and body, for example:
{
"top_left": "<big>{code}</big>",
"top_right": "{updated_at}",
"body": "By: {created_by}<br>Description: {description}"
}
Controlling the top detail area
The get_main_view_definition() method returns a dictionary with the keys title and body given a Shotgun entity type. These values controls the appearance of an object in the detail area, for example:
{
"title": "{type} {code}",
"body": "By: {created_by}<br>Description: {description}"
}
Controlling the fields shown in the Info tab
The get_all_fields() methods returns a list of fields to display for a given entity when this is rendered in the Info tab.
Actions are little snippets of code that operate on a piece of Shotgun data. Examples include:
- An action that launches RV for a given Shotgun Version
- An action that allows a user to assign herself to a given Task
- An action that loads a Shotgun publish into Maya as a Maya reference.
The actual payload of an action is defined in an action hook. Once you have defined the action logic, you can then map that action to Shotgun objects in the app configuration. These action mappings may for example look like this:
action_mappings:
PublishedFile:
- actions: [reference, import]
filters: {published_file_type: Maya Scene}
- actions: [texture_node]
filters: {published_file_type: Rendered Image}
Task:
- actions: [assign_task]
filters: {}
Version:
- actions: [play_in_rv]
filters: {}In the above example, we use the actions reference, import, texture_node, assign_task and play_in_rv. We then map the actions to various Shotgun objects and conditions. For example, we are requesting the import action to appear for all publishes of type Maya Scene.
When an object is loaded into the Panel, the action configuration above is read in and analyzed. A list of suitable actions for the current object is determined and the generate_actions() hook method will be executed. Shotgun data for the given entity will be passed to the hook at this point so that the hook code can determine if the action can be run for this particular Shotgun object. This is a way to allow each hook to run a check prior to being displayed. For example, the play_in_rv hook may only be relevant in the case there is media available locally - the action mappings set up in the configuration tells the panel which actions to enable for a given shotgun entity but they may not all be displayed because the generate_actions() method may determine that they are not suitable for the given object.
The actions returned from the generate_actions() method will be displayed on the actions menu and when a user clicks on it, the execute_acton() hook method is called to run the action.
For each application that the panel supports, there is an actions hook which implements suitable actions. For example, with something like Maya, the default hook will implement reference, import and texture_node actions, each carrying out specific Maya commands to bring publishes into the current Maya scene. As with all hooks, it is perfectly possible to override and change these, and it is also possible to create a hook that derives from the built in hook, making it easy to add additional actions to a built-in hook without having to duplicate lots of code.
The panel uses Toolkit's second generation hooks interface, allowing for greater flexibility. This hook format uses an improved syntax. You can see this in the default configuration settings, looking something like this:
actions_hook: '{self}/tk-maya_actions.py'
The {self} keyword tells Toolkit to look in the app's hooks folder for the hook. If you are overriding this hook with your implementation, change the value to {config}/panel/maya_actions.py. This will tell Toolkit to use a hook called hooks/panel/maya_actions.py in your configuration folder.
For more information, please see the hook files that come with the app. The hooks also take advantage of inheritance, meaning that you don't need to override everything in the hook, but can more easily extend or augment the default hook in various ways, making hooks easier to manage.
LINKBOX_DOC:5#The%20hook%20data%20type:Learn more about the second gen hook format here.
By using inheritance in your hook, it would be possible to add additional actions to the default hooks like this:
import sgtk
import os
# toolkit will automatically resolve the base class for you
# this means that you will derive from the default hook that comes with the app
HookBaseClass = sgtk.get_hook_baseclass()
class MyActions(HookBaseClass):
def generate_actions(self, sg_data, actions, ui_area):
"""
Returns a list of action instances for a particular object.
The data returned from this hook will be used to populate the
actions menu.
The mapping between Shotgun objects and actions are kept in a different place
(in the configuration) so at the point when this hook is called, the app
has already established *which* actions are appropriate for this object.
This method needs to return detailed data for those actions, in the form of a list
of dictionaries, each with name, params, caption and description keys.
Because you are operating on a particular object, you may tailor the output
(caption, tooltip etc) to contain custom information suitable for this publish.
The ui_area parameter is a string and indicates where the publish is to be shown.
- If it will be shown in the main browsing area, "main" is passed.
- If it will be shown in the details area, "details" is passed.
:param sg_data: Shotgun data dictionary with all the standard publish fields.
:param actions: List of action strings which have been defined in the app configuration.
:param ui_area: String denoting the UI Area (see above).
:returns List of dictionaries, each with keys name, params, caption and description
"""
# get the actions from the base class first
action_instances = super(MyActions, self).generate_actions(sg_data, actions, ui_area)
if "my_new_action" in actions:
action_instances.append( {"name": "my_new_action",
"params": None,
"caption": "My New Action",
"description": "My New Action."} )
return action_instances
def execute_action(self, name, params, sg_data):
"""
Execute a given action. The data sent to this be method will
represent one of the actions enumerated by the generate_actions method.
:param name: Action name string representing one of the items returned by generate_actions.
:param params: Params data, as specified by generate_actions.
:param sg_data: Shotgun data dictionary with all the standard publish fields.
:returns: No return value expected.
"""
if name == "my_new_action":
# do some stuff here!
else:
# call base class implementation
super(MyActions, self).execute_action(name, params, sg_data)
We could then bind this new action to a set of publish types in the configuration:
action_mappings:
PublishedFile:
- actions: [reference, import, my_new_action]
filters: {published_file_type: Maya Scene}
Version:
- actions: [play_in_rv]
filters: {}By deriving from the hook as shown above, the custom hook code only need to contain the actual added business logic which makes it easier to maintain and update.