Question

I have developed several general purpose script functions, for Google Spreadsheet apps.
Currently I keep each function in an individual file on my lap-top. In order to include them
into a spreadsheet, I only know of one way.

Merge the individual function-files into one file.
Then copy and paste the data in the merged file into the
spreadsheet’s script editor, replacing the previous content.

It would be nice if there was a way (e.g. using a “project”) where
the individual function files could be saved once and then I could
just reference those functions as needed in a new script.

I don’t know if there is such a possibility. I only see one node
called “code” in the tree list of the spreadsheet content.

Any help is appreciated.

Answer 1

Thanks Serge. I looked into “Libraries” here is what I found.

1. Any spreadsheet file which contains one or more Script Projects can be referenced as a
   Library. The script_project makes up the library definition.

2. A spreadsheet file can contain one or more script_projects.

3. The interface to script functions is found under the “tools” menu
   in the spreadsheet file. This menu contains three (3) entries related
   to scripts:

   1. Script Gallery (I have not yet explored this entry)
   2. Script Manger
      a. This entry provides a list view of all the projects and functions
      found in each “project”. The list is sorted by function_name, then
      project_name. The third column is “service” which I currently only
      find a value of “spreadsheet”. I have not explored other types of
      documents, “sites” and “services” to know what else can appear.
      b. At the bottom of this display is a menu of what actions you can
      perform on the list entries: Run, Edit, New, Close.
      – Run: executes the highlighted script.
      – Edit: opens the “Script Editor” on the selected project/function.
      This is the same the third (3) on the “tools” menu (see below).
      – New. opens the “Script Editor” on an untitled (empty) projects. This
      the same action that selecting “Script Editor” option from the “tools”
      menu when there are no previously saved scripts.
      – Close: this closes the Script Manager window. This is the same as
      pressing the “X” button in the top right corner.

   3. Script Editor.
      This provides you access to functions for manipulating:
      a. LIBRARY – a script PROJECT with a defined version number
      b. PROJECT – a collection of one or more FILEs.
      c. FILE – a collection of one or more JavaScript FUNCTIONs.
      d. FUNCTION – A set of JavaScript statements that can be referenced
      (called) by either a Spreadsheet interface or another
      JavaScript FUNCTION.

       When the Script Editor is accessed from a new spreadsheet, it creates
       a new (untitled) PROJECT. The new project contains one FILE. The name 
       of the initial file is "Code". This is the initial "tree" entry under
       the "untitled project" root in the left column of the editor's screen.
       The contents of the "Code" file is listed in the right column "text_area".
       The text_area is initialized with an empty FUNCTION definition which has
       the name "myFunction".
      
       The text_area provides normal standard text editing functions that you find
       in other script editors (copy, paste, cut; overlay/insert typing text 
       selection replace(with paste) and delete. 
      
       The text_area shows the complete contents of the file. This may be
       one or more "function" definitions. 
      
       The major functions of the editor in managing PROJECTs and FILEs at
       a "higher" level are found under the "File" menu. 
      
       The "File" menu contains the following entries:
      
       1. New - This allows you to insert a new PROJECT into the spreadsheet,
                or a new FILE in the current PROJECT. It also allows you to 
                create other types of documents. But I have not explored these
                options.
       2. Open - This sub-menu provides you with a list of PROJECTS contained
                 within the spreadsheet and allows you to switch projects, or
                 to access an additional file under a project. 
      
                 When a PROJECT is opened, The tree structure lists all of
                 the files contained in the project. The names of the files
                 are also listed in "tab" above the text_area. You can switch
                 between files by either clicking on the tree entry or the 
                 "tab" name.  
       3. Revision History - provides you with a list of saved contents of 
                 the project. You can back-off changes using this option.
      
       4. Rename - This sub-menu allows you to change the name of a FILE
                   within a PROJECT, or the name of the PROJECT. The object
                   that is renamed is determined by the entry selected in 
                   the "tree" in the left column.
      
       5. Delete - This sub-menu allows you to delete either a FILE within
                   a PROJECT or the entire PROJECT. The object deleted is
                   determined by the high-lighted entry in the tree structure
                   in the left column.
      
       6. Make A Copy - inserts a duplicate copy of the current file selected
                   in the tree structure, and switches access to the copied 
                   file's contents. If the current entry in the tree structure
                   is the PROJECT entry, then this and other sub-functions 
                   which do not apply at the PROJECT level are inactivated
                   (grayed out).
      
       7. Save   - Marks the current contents of the selected file as a
                   restore point, and saves its contents so that it is
                   accessible the next time the editor manipulates this project.
                   You can have unsaved changes in multiple files. This option
                   only saves changes to the currently active file.
      
       8. Save All - This saves the contents of all files that have unsaved
                     changes. The editor places a "red star" in front of the 
                     FILE's name in the "tab" for that file. As each file's
                     changes are saved. the "red star" is removed.
      
      
       9. Manage Versions - This sub-menu allows you to assign a NEW version
                     number to a project. It really does not allow you 
                     to manage the current version definitions. It prompts
                     you for a description (a reason for creating a new version).
      
                     By defining a "version" number you make the PROJECT usable
                     as a library. 
      
      10. Project Properties - This sub-menu provides access to a set of attributes
                     that are associated with the PROJECT object. I have not 
                     explored the use of "User Properties" and "Project Properties"
                     tabs. I expect that they are concerned with saving Key-value
                     pairs (as global variables) across spreadsheet access sessions.
                     But I will explore them later.
      
                     The important attribute on the "INFO" tab (for me) is the
                     "Project Key" attribute. This is the value that you must
                     copy/paste into another spreadsheet file, in order to access
                     the functions contained in this PROJECT without having to 
                     copy the actual function definitions into referencing 
                     spreadsheet file. 
      
       11. Build a user interface - I have not explored this sub-menu.
      
      
       Now once you have assigned a "version" number to a project, that project
       can be used as a "reference" (i.e. LIBRARY) in another spreadsheet file.
      
       Here is how you do this:
          1. Go to the spreadsheet file that contains the PROJECT (i.e.LIBRARY)
             that contains the PROJECT you want to "reference"
          2. Access the "tools" menu to gain access to the project. Use either
             the "Script Manager", or the "Script Editor" options. If your 
             spreadsheet only has one PRJOECT, then the "Script Editor" will
             take you to that PROJECT. Otherwise, use the Script Manger, to
             select the PROJECT. (If you open the Script Editor, and the spreadsheet
             file has more than one PROJECT, it will prompt you to select which
             PROJECT that you want to access.
          3. Go to the "File/Project Properties" sub-menu within the editor and
             select (high-light) the Project Key's attribute's value. and copy
             it to your "clip board" (i.e. CTRL-c). You can then close this
             spreadsheet file.
          4. Open the spreadsheet file that contains the scripts that needs
             to reference the functions from the other PROJECT(LIBRARY). 
          5. Access the PROJECT containing the functions that are to call
             the external functions from the LIBRARY.
          6. In the editor go to the "Resourses/Manger Libraries" sub-menu.
             You will receive a panel with the title "INCLUDED LIBRARIES".
          7. To add the new library reference, paste the copied Project Key
             value into the "Find a Library" field, and press the "SELECT"
             button. 
          8. If you have not made an error, you will set the list of libraries
             updated to include your PROJECT added to the list. 
      
       Each row in the PROJECT (library) list contains 5 entries. Here
       is how they are used.
      
             1. Title - This contains the name of the PROJECT from the other
                        spreadsheet file. This is the name that is associated
                        with the "Prject Key". You can not change this value,
                        within this referencing file. 
             2. Version - This shows which version of the PROJECT resources that
                        you are allowed to access by this definition. The 
                        drop-down list shows you which versions are available
                        and the comment you entered when you created the version.
             3. Identifer - This shows you the qualifier that you are to use
                        within your FUNCTION definitions to uniquely identify
                        which function you are calling.  You are allowed to 
                        change this value even after you have initially defined
                        it. This identifier is similar to a "namespace" qualifier
                        that is found in an XML document. If you change the 
                        qualifier value you must make a similar change to 
                        all code within your functions that reference this 
                        identifier, otherwise an error is thrown at execution
                        time (to the end user) that an undefined identifier has
                        been encountered.
             4. Development Mode - This attribute impacts the execution of the
                        scripts in the current spreadsheet. It tells the spreadhseet
                        engine NOT TO SAVE the compiled image of the target 
                        (referenced) library. This will slow down the execution
                        of your script since the spreadsheet engine will compile
                        your script every time you execute it, and it will also
                        recompile the contents of the LIBRARY each time. You should
                        only use "Development mode" when you are debugging a problem
                        with a library script.
             5. Remove - when clicked removes the "Library definition" from the list
                        of included libraries. 
      
          Library definition changes are automatically saved when you close the
          mangers access panel. At the bottom of the panel are two buttons.
          "SAVE" - allows you to save changes and continue to make Library 
          definitions. CANCEL - causes the manger function to exit. Any 
          changes since the last SAVE are discarded.
      
          To call a Library function in your script is similar to calling
          the "msgBox" method of the "Browser" object. For example to 
          call the msgBox function you include "Browser.msgBox('...')"
          clause.
      
          To call the "doSomething" function in a library (project) for
          which you assigned the "identifier" of "LETS", you would 
          code the clause "LETS.doSomthing(....)". 
      
      
      
      After discovering these "facts", I have come to the following 
      conclusions:
      
          1. The purpose of the spreadsheet file should be to only hold the 
             LIBRARY function definitions.  
      
          2. If you are going to use a PROJECT as a LIBRARY, then you probably
             will want to have multiple PROJECTs in the spreadsheet file that 
             contains the LIBRARY.  The primary PROJECT should hold the 
             function definitions that make up the LIBRARY. A second project
             should be defined that holds testing functions. Only the LIBRARY
             project should be given a version number.
      
          3. The spreadsheet data in general will not be available to the
             scripts that references the LIBRARY. They can be made available
             but not without opening the libraries spreadsheet file as a 
             separate application.
      
          4. I don't know (since I have not tested this), but I assume that
             the PROJECT PROPERTIES and USER PROPERTIES of the library (spreadsheet)
             file are NOT accessible to the library functions when they are called.
             I can see both, views which would allow and prohibit this access.
             For security reasons I would guess that they would not be available.
             (I could be wrong! - and generally I am).
      
          5. I like the idea of using FILES. In fact, I plan to use one file 
             for each function.  From a Object Oriented Programming perspective,
             you will probably want to use a separate file for each Object's
             definition.  You must realize (at this time) the JavaScript language
             does not support "Object Definitions".  The use of FILES as a container
             seems to be the reason for creating the FILE construct. 
      
          6. The FILE object also allows you to limit the scope of view and change
             to functions within the FILE. In this way, you cannot corrupt other 
             functions which are not in the file. 
      
          7. I found a significant impact on execution time when a script is run
             that references one or more Libraries.  My guess is that execution
             performance can be improved over time, with the use of JIT and caching
             facilities.
      
          8. From an end-user's perspective, it would be nice is a "clock" type
             cursor icon would appear to the end user when a script is executing.
             This is very important considering the time it takes to execute code
             that references library functions.
      
          9. For script execution performance reasons, you may anticipate that
             you will have to make the library functions an actual part of your
             spreadsheet file.  Looking ahead to this possibility, I would 
             create dummy (skeleton) functions within my spreadsheet scripts
             which do nothing more that pass the input parameters to the 
             library functions with the proper namespace identifier. Then
             when I have to copy in the library functions I only have to 
             change the dummy functions. I would put these skeleton functions
             into a separate file. I would use one file for each library 
             reference definition.