Open Document Build Scripts

NOTE: This exercise assumes you have completed the previous exercise.

In this exercise you'll learn to open the new scripts that were created as part of the process of creating a new application shell in the previous exercise. There are two new scripts:

Table 1.1. Document Build Scripts

Script File Description
app_octopus_scripts.ssl Contains macros (commands) that can be installed in the user interface of a Scenome application. May also contain functions. You can only install command macros as items in Scenome app user interfaces.
app_octopus_util.ssl Contains functions only. These functions are used by other functions or command macros. You cannot install functions as command items in Scenome app user interfaces. By convention, macros are never stored in Scenome Scripting Language files ending in _util.ssl.

This is a common script document pattern. Scripts that contain commands (called macros) that can be installed in the interface of an application use _scripts.ssl in their name. Related script libraries that store functions used by the command library use the same name but _scripts.ssl is replaced with _util.ssl.

In this exercise, we'll open both these scripts.

Get The Macro Library Script Path

  1. Return to the running Octopus application.
  2. Examine the main menu and select File » Get Application Script Path from the listed options.

    The application displays a dialog that allows you to search for application scripts.

    This is a picture of the app script search box.
  3. Type app_octopus_scripts.ssl in the text entry.

    Copy Text To Clipboard

    app_octopus_scripts.ssl

    The script entry appears in the dialog.

  4. Left click the entry named app_octopus_scripts.ssl and click OK or hit ENTER when you are finished.

    The application copies the script path to the Windows® clipboard.

Open The Macro Library Script

  1. Start a text editor of your choice and select the option to open a file from disk.
  2. Select CTRL + V to paste the script command library file path (into the place in the dialog where you specify the file to open).
  3. Open the file.

    The script appears in the text editor.

    ///////////////////////////////////////////////////////////////////////////////
    //
    // $author           Scenomics LLC
    // $description      Implements commands for the Octopus application.
    //
    // Copyright 2004-2021 Scenomics LLC. All Rights Reserved.
    //
    ///////////////////////////////////////////////////////////////////////////////
    
    import library "app_octopus_util.ssl";
    import library "app_service_assert_util.ssl";
    import library "app_service_build_util.ssl";
    import library "app_service_console_util.ssl";
    import library "app_service_settings_util.ssl";
    import library "type_node_buffer_util.ssl";
    
    ///////////////////////////////////////////////////////////////////////////////
    // macro
    ///////////////////////////////////////////////////////////////////////////////
    
    function void OctopusExecuteBuild_OnUpdate( CommandPresentationModuleInfo commandInfo )
    {
       commandInfo.Status.SetHint( "Builds this document" );
    }
    
    macro OctopusExecuteBuild( CommandPresentationModuleInfo commandInfo )
    [Category="Build Commands", Guid="{B43182D4-3BA2-49FA-8404-31CE45BCA6D9}", Image=".\\icons\\generic_script_icon.bmp"]
    {
       if( LibAppServiceSettings.GetBoolParam( "ClearOutputWindowBeforeBuild" ) )
       {
          Console.Clear();
       }
    
       auto StrList a_slMessages;
       a_slMessages.AddBlank();
       LibAppOctopus.GenerateProjectBuildHeader(
          Model.Filename, a_slMessages );
    
       LibAppOctopus.Build( a_slMessages );
    
       a_slMessages.AddBlank();
       a_slMessages.Add( "Build completed." );
       LibAppOctopus.Out( a_slMessages );
    }
    

    Let's review the contents of this script file.

    Table 1.2. Review Script Contents

    Section Description
    Header A brief description of the document.
    Package Declaration Declares the package with which this script is associated.
    Imports Library imports that allow us to call functions implemented in other function libraries.
    OctopusExecuteBuild_OnUpdate This function is invoked by when macro OctopusExecuteBuild appears in the user interface. This function determines if the macro is enabled (or grayed out), and sets the hint text that appears when the user selects this command in the user interface.
    macro OctopusExecuteBuild This macro implements a generic build command. Right now it doesn't do anything except print a simple build log to the output window.

Get The Utility Library Script Path

  1. Return to the running Octopus application.
  2. Examine the main menu and select File » Get Application Script Path from the listed options.

    The application displays a dialog that allows you to search for application scripts.

    This is a picture of the app script search box.
  3. Type app_octopus_util.ssl in the text entry.

    Copy Text To Clipboard

    app_octopus_util.ssl

    The script entry appears in the dialog.

  4. Left click the entry named app_octopus_util.ssl and click OK or hit ENTER when you are finished.

    The application copies the script path to the Windows® clipboard.

Open The Utility Library Script

  1. Return to the running text editor and select the option to open a file from disk.
  2. Select CTRL + V to paste the utility library file path (into the place in the dialog where you specify the file to open).
  3. Open the file.

    The script appears in the text editor.

    ///////////////////////////////////////////////////////////////////////////////
    //
    // $author           Scenomics LLC
    // $description      Implements common Octopus app functions.
    //
    // Copyright 2004-2021 Scenomics LLC. All Rights Reserved.
    //
    ///////////////////////////////////////////////////////////////////////////////
    
    library LibAppOctopus;
    
    import library "app_service_assert_util.ssl";
    import library "app_service_console_util.ssl";
    import library "app_service_file_util.ssl";
    import library "app_service_html_util.ssl";
    import library "app_service_main_util.ssl";
    import library "app_service_shell_util.ssl";
    import library "type_file_node_algorithms.ssl";
    import library "type_file_path_algorithms.ssl";
    import library "type_group_util.ssl";
    import library "type_service_create_util.ssl";
    import library "type_service_enumeration_util.ssl";
    import library "type_str_util.ssl";
    import library "type_str_list_util.ssl";
    
    ///////////////////////////////////////////////////////////////////////////////
    // function
    ///////////////////////////////////////////////////////////////////////////////
    
    function string GenerateProjectBuildHeader( string p_sName, StrList p_slMessages )
    {
       string a_sProjectBuildHeader = "--- <Building Project \'" + p_sName + "'> ---";
       p_slMessages.Add( a_sProjectBuildHeader );
       p_slMessages.AddBlank();
       return a_sProjectBuildHeader;
    }
    
    ///////////////////////////////////////////////////////////////////////////////
    // function
    ///////////////////////////////////////////////////////////////////////////////
    
    function void Out( StrList p_slMessages )
    {
       for( int i = 0; i < p_slMessages.GetCount(); ++i )
       {
          Console.Out( p_slMessages.GetAt( i ) );
       }
    }
    
    ///////////////////////////////////////////////////////////////////////////////
    // function
    ///////////////////////////////////////////////////////////////////////////////
    
    function bool Build( StrList p_slMessages )
    {
       p_slMessages.Add( "Doing build work..." );
    
       return true;
    }
    

    Let's review the contents of this script file.

    Table 1.3. Review Script Contents

    Section Description
    Header A brief description of the document.
    Library Declaration Declares this document as a library so that its functions can be accessed from other utility and command libraries. You must use the library name to access these functions from other files. For example: LibAppOctopus.Build( ... ).
    Imports Library imports that allow us to call functions implemented in other function libraries.
    GenerateProjectBuildHeader This function populates a <StrList> object with a build log header.
    Out This function displays the build log in the output window.
    Build This function performs the build.

    This exercise is complete. Please proceed to the next exercise.