Adding a new Internal Command

This is an example of a script add-in that adds a new internal command to Opus.

This command, SelectNewest, selects one or more of the newest files in the current folder. You would use this by creating a new .js file in the Script Addins folder (type /dopusdata/Script Addins into the location field to find this).

You could then create a button or hotkey to run the SelectNewest command just like any other internal Opus command.

The basic procedure to add an internal command from a script add-in is:

• Either:

  • In the OnInit event, create a ScriptCommand object with the ScriptInitData.AddCommand method.

  • Or, in the OnAddCommands event, create a ScriptCommand object with the AddCmdData.AddCommand method.

• Initialize the properties of the ScriptCommand object. At a minimum you must populate the name and method properties.

• Create a separate function in your script-add in, with the method name you specified for the command. This will be your command's entry point.

  // Set the script type to JScript to use this script. // The OnInit function is called by Directory Opus to initialize the script add-in. function OnInit(initData) { // Provide basic information about the script by initializing the properties of the ScriptInitData object. initData.name = "Select Newest Files"; initData.desc = "Select the newest X files in the folder"; initData.copyright = "(c) 2016 Jonathan Potter"; initData.default_enable = true;

    // Create a new ScriptCommand object and initialize it to add the command to Opus.
    var cmd = initData.AddCommand();
    cmd.name = "SelectNewest";
    cmd.method = "OnSelectNewest";
    cmd.desc = initData.desc;
    cmd.label = "Select Newest Files";
    cmd.template = "NUMBER/N,FROM/K/N,NODESELECT/S";

  }

  // Implement the SelectNewest command (this entry point is an OnScriptCommand event). // The name of this function must correspond to the value specified for the method property when the command was added in OnInit. function OnSelectNewest(scriptCmdData) { // scriptCmdData is a ScriptCommandData object, and it provides the raw command-line and a Func object. // The Func object contains an Args object, which in turn contains our parsed arguments (if any), usually preferable to using the raw command-line. // We use the got_arg object to test if an argument was provided, before reading its value.

    // First get the starting index to select from, from the FROM argument. Default to 0 (newest) if not supplied.
    iStartPos = 0;
    if ( scriptCmdData.func.args.got_arg.from )
        iStartPos = scriptCmdData.func.args.from;
  
    // Next get the number of files to select, from the NUMBER argument. Default to 1 if not supplied.
    iNumber = 1;
    if ( scriptCmdData.func.args.got_arg.number )
        iNumber = scriptCmdData.func.args.number;
  
    // The func.sourcetab property returns a Tab object representing the function's source tab.
    // We create an enumerator for files in the source tab (sourcetab.files).
    // To change this to operate on files and folders rather than just files, use sourcetab.all instead.
    var objEnum = new Enumerator( scriptCmdData.func.sourcetab.files );
  
    // build an Array of the files so we can sort it.
    var objFiles = new Array();
    i = 0;
    while (!objEnum.atEnd())
    {
        objFiles[i++] = objEnum.item();
        objEnum.moveNext();
    }
  
    if (objFiles.length > 0)
    {
        // Sort the array by the "modify" property.
        // This will sort the file array in order from newest to oldest.
        objFiles.sort( function(a, b)
            {
                if (a.modify < b.modify)
                    return 1;
                if (a.modify > b.modify)
                    return -1;
                return 0;
            });
  
        // By default we get given a Command object pre-filled for the current tab.
        // We can use that instead of creating our own, but we need to clear
        // out its list of files if it has one already.
        scriptCmdData.func.command.ClearFiles();
  
        // Starting from the specified start position, add the requested number
        // of files to the command object. Because we have sorted the array from newest
        // to oldest, this will automatically add the newest files to the command.
        for ( i = iStartPos; i < objFiles.length && i < iStartPos + iNumber; i++ )
        {
            scriptCmdData.func.command.AddFile( objFiles[i] );
        }
  
        // Build the Select command line to run that will actually select the files.
        // The FROMSCRIPT argument is needed to select files from the command object.
        // The DESELECTNOMATCH argument is used to deselect all other files, unless the
        // script's NODESELECT argument was used.
  
        strCommand = "Select FROMSCRIPT";
        if (!scriptCmdData.func.args.got_arg.nodeselect)
            strCommand += " DESELECTNOMATCH";
  
        // run the Select command via the Command object's RunCommand method.
        scriptCmdData.func.command.RunCommand( strCommand );
    }

  }