Tip 1: Labeling (Advanced/Shared actions)

Intro

Many Captivate developers use advanced actions, which is an easy way to extend the functionality of the application without need for learning the rules of a programming language. After publishing the project, those actions are converted to JavaScript. This is also the case for the more flexible (underestimated) shared actions.

However the  ‘point-and-click’ approach for scripts has rules and limitations.  If you start using advanced/shared actions,  understanding those rules will avoid frustrating situations.  This first Tip is all about the importance of customizing labels, the reasons for establishing a labeling discipline (especially when working with a team). Last week two questions in the Adobe forums about issues with advanced actions were due to lack of knowledge about correct labeling.

The terminology used in this blog is the same as in the Adobe documentation. You can check the in-depth exploration of the Advanced Actions dialog box in one of my previous blogs meant also for starters with actions: 

Advanced Actions Outfit since CP2017 – eLearning (adobe.com.

This article will first explain Generic names (labels) attributed by Captivate, continue with Custom labeling. At the end you'll see also an explanation of 'Smart labeling', term used by Adobe when copy/paste is used on items with a custom name.

Generic names (labeling) - Uniqueness

Almost all items in Captivate get a generic name when they are created in a course: objects, placeholders, groups, slides, states, decisions (in actions)... There are a few exceptions:

  • User variables: you need to define a custom name except for the variable associated with a Text Entry Box.
  • Advanced/Shared actions: they also need a custom name 

The first global ruleis fully respected in those generic names. 

 'Each name needs to be unique'
Names are case sensitive, so it is easy to use similar names, by changing one or more characters to uppercase from lowercase. Uniqueness applies also to items from different type: do not use the name for a button, which has already been used for a variable (common mistake), or the name of an action for an advanced action (another common mistake). There are some minor exceptions:

  • Generic name for a Text Entry Box and its associated variable are the same. I don't really like this, and tend to create a new user variable with a custom name, using the X button next to the generic variable name:
    It is not wrong to keep the generic name, but it bumps on the general rule.

  • If you define the name of a button, and use the same name for the action to be triggered by the Success event, it will not be flagged as an error. But if you do the reverse (first action, later the button) you do get an error. I would avoid doing this. 

  • States can have the same name for multiple multistate objects, because as identifier the combination of the object name and the object will be unique if the object has a unique name.

  • Similar for decisions within an advanced/shared action. Although years ago I had issues with an advanced action using the same name as a decision in another advanced action. But decisions can have same name in multiple advanced actions.

When using Generic names, and duplicating the item, the duplicate will have a similar name but ending on another number. Check this screenshot, showing the timeline of a slide with multiple objects and of a duplicate slide:

Custom names (labeling)

Why and when is replacing generic names worthwhile, because it takes time?

  • It will be easier to understand, especially for your clients and collaborators. Referring to the screenshots of the Timeline posted above, if you replace the name of the TEB which will ask for a name by 'TEB_name', and the button is named 'Bt_Next' reading the timeline is more comfortable. Have a look at this Timeline, which is from the Stopwatch tutorial to understand better.
  • When using the items in advanced or shared actions, where you often will need to choose from dropdown lists, it is almost impossible to identify the right item for your choice when working in a project with tons of items.
  • To take advantage of the filtering (see Tip 2) provided by Captivate, custom names can save you lot of time. Look at this screenshot from the Memory Game tutorial where a parameter needs to be chosen for the shared action. There are lot of shape buttons in this game. By typing out one or two characters (here _2) the long list is filtered to facilitate the choice.

Setting up a custom labeling 'system' is also a timesaver, not only when you are collaborating with a team. The global rule of Uniqueness will have to be respected. Names cannot start with a number, nor have strange characters. Try to keep to short names, avoid spaces and remember that names are case sensitive! Here is a short summary of my personal labeling system, however this is just an example. Over a decade ago I started labeling for user variables. At that moment the only way to find a variable in the dropdown lists was by using the first character, because they were sorted alphabetically. To have the group of user variables separated from the system variables (which started with r or c at that moment) user variables started with v_. The first character indicating the type of item, followed by an underscore (replacing a space). This meant the item was also identified by that first character, and I continued to follow the same logic for other items. Some examples:

  • Bt_: first characters of buttons of the three old types (text, transparent, image)
  • SS_: smart shape
  • SB_: shape used as button
  • Im_: bitmap image
  • Ib_: bitmap image used as button
  • SV_: SVG image
  • SVB_: SVG used as button
  • Gr_: group both for object groups and slide groups (Table of Contents)
  • Tx_: text caption
  • CB_: click box
  • ...

For advanced actions I don't have a fixed system. One exception: if an action is meant to be used On Enter for a slide, I will start its name with Enter. I am a frequent user of shared actions whenever possible, which avoids the need for names for multiple duplicate advanced actions,  since you need only one name for a shared action that can be applied multiple times with different parameters. 

For the other characters in the name I will use camel notation. The system allows you to have the second part identical for items which are linked. Example: SVB_Reset can be linked with an advanced action ResetAct, and a variable v_reset.

Maybe I'll add an extra extension to multistate objects in the future, because they are not easily identifiable.

Tip: for much used variables create a shared action as explained in Rare tips (tip 1). By importing that action in a new project you avoid lot of typing.

Smart labeling

When you copy/paste an item with a custom name, the custom name will be preserved, but an extra number is added to the name. This is indicated as 'smart labeling', was introduced some versions ago. 

Example: Duplication of the Next shape button (from the Timeline screenshot for the Stopwatch slide), will lead to this:

The duplicate gets the original name followed by an underscore and a number. In this case the duplicate of SB_Next, became SB_Next_20. It means that the numbers 1-19 had already been used. Same would happen if you copy that button to another project, but the number will be different. If I copy this button to a almost empty new project, the name becomes SB_Next_2, because only one object already existed ending on 1. Keeping at least part of the custom name can be very useful. However it can also become a problem as I learned when importing Shared actions using the same variables. If you don't import (or drag) those actions in one workflow, but in steps, you will end up with duplicate variable bearing another name. You also need to be careful when copying interactive objects which are triggering actions using variables.

Conclusion

I hope this article convinced you of the importance of consistent labeling. Be sure I do not label every item, but I will when they will be needed in an advanced or a shared action. For slides the names do not need to be unique, because internally they are identified by cpInfoCurrentSlide which is a number. However slide names are important if you want to use a Table of Content.

Next tip about Filtering is closely linked to this first tip, and will save you time when developing advanced and shared actions. You will get an overview of the locations where filtering is possible, and those where - saddening - it is not available.