Decipherlime

Current version:

Decipherlime is a channel for setting Sublime Text for programming Decipher (BOR) studies. The repository contains 2 packages: DecipherLib and DecipherXML.

∝Basics

This repo started as an attempt to port the clips from Notetab Pro to another code editor, mainly because of dislike for Notetab. Moving forward the Notetab library was successfully moved and some additional features appeared. Then we get to nowadays when quite a few additions and improvements have been implemented, and not much of the code is shared between the 2 editors' libraries anymore.

Thanks to Sublime's API and a lot of work this library has become an indispensable tool for making Decipher surveys.

The DecipherLib package is the actual library with all commands, shortcuts and logic. Usually referring to the channel (decipherlime) is interchangeable with referring to the library (DecipherLib).
DecipherXML is an independent package just for .xml syntax highlighting.

∝Installation and settings

If you don't have Sublime Text (ver. 3/4) installed yet, you can download it from here here. There is a portable version available too.
You should probably assign it in Windows to open .xml files, pin it on the task bar, etc. If you're using WinSCP you'll need to add it on top of your editors list to open files with it by default (right click on a file ⇨ Edit ⇨ Options).
The first thing to do once you launch it is to install Package Control (if you haven't already) through Tools ⇨ Install Package Control….

If you are using Sublime under OS X (Mac) or Linux you'll probably need to add the following to Package Control settings (Preferences ⇨ Package Settings ⇨ Package Control ⇨ Settings). Urllib causes issues with the channel's SSL certificates, but with curl it works properly.

    "downloader_precedence":
    {
        "linux":
        [
            "curl",
            "wget",
            "urllib",
            "oscrypto"
        ],
        "osx":
        [
            "curl",
            "urllib",
            "oscrypto"
        ],
        "windows":
        [
            "wininet",
            "oscrypto"
        ]
    }Copied

∝Install the packages

To add the Decipherlime channel select Preferences ⇨ Package Control ⇨ Add Channel, then in the input box (on bottom) enter this url: https://decipherlime.live.borsolutions.com/channel.jsonCopied. Both package will become available via Package Control ⇨ Install Package (search for DecipherLib and DecipherXML).
DecipherLib might have some conflicts if you don't disable/remove other Decipher-related packages you have installed (using Package Control ⇨ Disable Package), because DecipherLib and the installed package might have potential conflicts between each other. [DecipherLib auto-disables decipher-sublimetext-clips-master after installation]
For DecipherXML to work properly you should disable the built-in XML package (using Package Control ⇨ Disable Package), because otherwise it will be used by default. [DecipherXML auto-disables XML]

∝Additional settings

Below you can copy a few useful and recommended settings to your Preferences ⇨ Setting file.

• auto_find_in_selection will find and replace in text selection by default, otherwise it should be switched manually every time; [auto-enabled by DecipherXML]
• highlight_modified_tabs tabs with unsaved changes are highlighted more visibly; [auto-enabled by DecipherXML]
• highlight_line changes the color of the active line;
• Adaptive theme blends with the set color scheme and looks better than the Default theme;
• disabled detect_indentation will prevent Sublime from auto-changing tabs to spaces. [auto-enabled by DecipherXML]

"auto_find_in_selection": true,
"highlight_line": true,
"highlight_modified_tabs": true,
"theme": "Adaptive.sublime-theme"Copied

The BracketHighlighter package provides great bracket and tag matching. It's very useful for finding opening/closing block tags, for example. Install it through Package Control (Preferences ⇨ Package Control ⇨ Install Package) and put this file into your Packages/User directory (Preferences ⇨ Browse Packages...). The file contains a setting to match larger text regions, as the default is pretty limited.

There are other settings you can tweak in the Settings file (they're well documented). Also, there are many other packages from the main channel you can install, for syntax, editing, color schemes and other. It's up to you to install whatever you need.

∝DecipherLib

A package (lib) that adds commands/clips for creating Decipher XML tags and attributes. Based on the NoteTab libraries, replicating their functionality, but also extending and improving it. It is aimed to be easy for those migrating, that are used to Notetab.

∝Usage

The clips / commands can be used through several interfaces:

• All available commands can be run from Sublime’s quick panel. By default it is shown on Ctrl+Shift+P, but the DecipherLib adds another key shortcut - F1 (Escape also works, but isn't recommended). The DecipherLib's quick panel key shortcuts add a Decipher: prefix to the search, so only the related commands are listed and searching is easier.
  You don't need to match the command name exactly, as in Notetab - for example, add popup will show both the Decipher and the Responsive one.

• A lot of tags, attributes and other have auto-completion suggestions that appear while writing.

• Many commands also have keyboard shortcuts assigned. If a command has a shortcut assigned, it’s displayed in the Decipher menu, so it can be used as a reference.

• An application (window) menu named Decipher is added, where all commands are accessible and sorted in categories.

• Some of the more common used commands are available through the context menu (right click).

∝Features

If you take a quick look in the Decipher menu, the commands there don't seem that different than the Notetab clips. Most of the changes are under-the-hood and in the accessibility and functionality of commands. That doesn't include only the quick panel, key shortcuts and completions, but also the behavior of some commands.

An addition to many commands is smarter cursor placement. For example, making a survey comment (html tag) put the cursor at label="", loopvars get VAR_NAME selected, and so on. Learning to use that can distinctly speed up your work flow. You may only be saving 1-2 clicks per command, but multiply that by all the commands you run per shift. And every "click" is a waste of time and efforts.
All commands from the Attributes category aren't just text insertions, but they recognize what output is needed. An attribute can be added to multiple rows/cols for example.

DecipherLib aims to be exactly what its called - a library for Decipher. There is just one library, that is updated automatically and tries to be universal for all survey types (only Qarts available now). Client specifics are handled by itself - the survey type is detected and a lot of commands are adjusted accordingly and the right Parser mode is set.

There are also quite a few bugs and issues that have been patched or updated. Commands like make question types and elements have been completely rewritten, because of the many imperfections they had. Except DecipherLib's features there are some very useful ones, that come with Sublime. For example, multiple selections are available, and they are wonderful for some edits. The split layout view is useful if you're working with 2 files, or just so you can leave there some commonly used snippet. There is also an integrated Python console where you can quickly run and check some code.

∝Parser

The DecipherLib has a universal parser, which implements the QArts Parser functionality, but also add a lot of additional features and isn't exclusive just for QArts studies.

• Correct submessage per client is set, according to question type and attributes, if not disabled in preferences;

• Question elements are checked if they should be exclusive, anchored, or open-end;

• Question text is checked for randomize instruction;

• Programmer notes are commented out of the element (this is done for texts in [brackets]);

• If a submessage is found in the question text, it is commented out or set as a comment tag if preference is enabled.

So if we run the Parser on this question:

<checkbox label="Q1" atleast="1">
  <title>Some question here? 
   Please select all that apply. [Randomize]</title>
  <row label="r1">A simple row</row>
  <row label="r2">Another simple row (Anchor)</row>
  <row label="r3">Some option [terminate]</row>
  <row label="r4">Another non-elig option [terminate]</row>
  <row label="r5">Other row (Please specify)</row>
  <row label="r6">None row [exclusive]</row>
</checkbox>
<suspend/>

The result will be:

<checkbox label="Q1" atleast="1" qa:atype="text" qa:tool="rp" shuffle="rows" uses="qarts.2360">
  <title>Some question here?</title>
  <comment>Please select all that apply.</comment>
  <row label="r1">A simple row</row>
  <row label="r2" randomize="0">Another simple row</row>
  <row label="r3">Some option </row> <!--[terminate]-->
  <row label="r4">Another non-elig option </row> <!--[terminate]-->
  <row label="r5" open="1" openSize="25" qa:rplaceholder="Please specify" randomize="0">Other row</row>
  <row label="r6" exclusive="1" randomize="0">None row</row>
</checkbox>
<suspend/>

∝Auto-Parsing

There is also an auto-parse feature which runs the Parser on each question after creation, so there is no need to select the question and manually run the BOR Parser command. As some additional attributes or elements might be added to a question, it’s not parsed immediately. Instead the Parser detects where you’re working, and if it’s outside the question, the Parser is ran. For example, if a question is made and new rows are created in it, it won't be parsed, but once a row is made under the question, it will be parsed.

The Parser can be triggered, after a question has been made, by F7, with no need to select the question again. It is also activated on file save.

The auto-parser tries to detect hidden (where="execute") questions on creation and doesn't run the Parser on them. Instead, it makes them hidden directly.

Auto-Parser can be enabled/disabled via Decipher ⇨ Settings ⇨ Toggle Auto-Parser. This setting is global and saved between files and sessions. If you want to disable parsing just for the current study, use the Set Current Survey Type setting.

∝Completions

Tab completions are suggestions that you get while typing. They are shown in a popup next to the cursor and selected with Tab. A lot of tags and attributes have been implemented already. What's best about completions is that they aren't just static text that gets inserted. They can be modified after paste, again with the Tab key. Depending on the element they can have up to 3-4 'Tabs'. For example, the verify attribute gets the max range selected on first Tab, the min on second, and the whole range() on third (so it can be changed to another verifier, like len()).

A lot of completions don't have a corresponding command (quick panel/Decipher menu), especially the attributes. But even the ones that have, are best used as auto-completions. Opening the F1 panel, searching for make terminate and then setting label first, then the cond and finally the text, takes so much longer than writing term, pressing Tab, writing the cond, pressing Tab again, and writing the text, because the label and the text beginning are auto-captured from the condition. Similar case with quota.

The list of preset conditions is quite long, so it's not posted here, but you see them while writing, so if you just take a look now and then you'll be able to learn them. There are short notes in the completion popup defining each completion that you can use for reference.

∝Shortcuts

DecipherLib comes with a rich set of keyboard bindings for commonly used commands. As mentioned somewhere above, clicking is very slow, but typing command names constantly is not that quick either, so starting to use the shortcuts will make your life easier.

The key bindings follow specific logic, which you'll get after reviewing the table. Under Misc. there are a few key bindings that come from Sublime, not DecipherLib, but they are very useful and have been included. All shortcuts not in Misc. are only active for XML files, so if syntax isn't set to XML they just won't activate.

You can also assign your own shortcuts through Decipher ⇨ Settings ⇨ Key Bindings.

∝Preferences

DecipherLib has several additional features that may not be suitable for everyone, so there are preferences implemented from which they can be enabled/disabled. They can be found in Decipher ⇨ Settings. Here they are:

• Toggle Qarts Usage switch the active file to Qarts mode. When On Qarts attributes are put by the Parser as well as additional Qarts-specific modifications will be used. When Off the Parser still does a few automations to questions, but only general Decipher attributes and modifications. Useful to turn off Qarts usage for specific sections of the survey or a whole survey.
• Auto-Parser enables or disabled the auto-parsing feature globally or just for the current file. When disabled, manually running the Parser (F8) still works, but the Parser will never be auto-triggered. Enabled by default.
• Escape-On-Save can be set globally or just for the current file. Non-ascii (special) characters and ampersands are auto-escaped when this preferences is enabled. While generally quite useful, there are some cases when enabled escape-on-save can cause issues and even break a survey. Enabled by default.
• Message Dialogs defines if errors/warnings are shown in a popup dialog on save. They will still be shown in the status bar if setting is disabled. Currently XML syntax errors and usage of "or 1" in conds trigger a message. Sometimes usage of macros causes false errors. It can be set globally or just for current file. Enabled by default.
• Comment Tags Parsing is for whether to set default comments (submessages/instructions) when parsing. There are 3 modes:
  • Strict: comments are set for all survey types/clients;
  • Standard: only for survey types with specific instructions (QArts/AG/M3);
  • Off: no comments are set in any mode.
  Set globally and "strict" by default.
• Found Comment will set potential instructions from the question text as comment tag automatically in the Parser. It finds Please/Select/Check sentences at the end of the Q-text. When this preference is disabled the instruction gets commented out after the title. Setting applies only for the current file. Disabled by default, except for FV surveys.
• Kantar Vars - Should the popup for selecting kantar:clienttype/office/complexity/etc. be displayed when creating new Survey (after entering the alt name) or not. When disabled default variables are set without the confirmation popup. Enabled by default.

∝DecipherXML

DecipherXML is an XML syntax highlighter, optimized for Decipher. It uses the default Sublime XML package as a base. The differences include Python highlighting in executable tags (e.g., validate) and CSS / Javascript in styles, and recognition of macros (@define Macro). Instead of just as plain text, a long exec will have its different elements highlighted appropriately, as well as Python specific completions and syntax rules. This can be quite helpful for complex/large execs and scripts.

∝Contact

If you have any feedback, bugs to report, recommendations, or questions please contact or .