PxPlus Google Docs Object |
The PxPlus Google Docs object provides the ability to work with Google Workspace® Docs, a cloud-based word processing application. This object consists of various properties and methods that are used to interact with Google Docs documents. See Properties and Methods below.
The Google Docs object allows more than one document to be opened at one time.
(The PxPlus Google Docs object was added in PxPlus 2021.)
To instantiate the Google Docs object using the handle docs_obj (where docs_obj could be any numeric variable), enter the following command:
docs_obj=NEW("*obj/GoogleDocs",client_ID$,client_secret$[,login_token$])
The constructor requires a Client ID and Client Secret, both of which must be obtained from Google via the Google API Console. See Google API App Setup for detailed steps.
The login token can be optionally used to avoid having to select a Google account and login more than once. See Google Authentication for information on how to get a login_token$.
To access any of the available properties and/or methods, the Google Docs object handle (docs_obj) is used, followed by an ' (apostrophe) and the property or method (with the desired parameters).
Examples:
doc=docs_obj'ACTIVE_DOCUMENT
retVal=docs_obj'SetDocument(3)
During object instantiation, the user will be asked to select and login to a Google account and allow PxPlus access to it via their default Web browser. When this process is completed, the Login( ) method must be run to complete login to Google Docs.
Successful login can be confirmed via the IsLoggedIn( ) method. If successfully logged in, then documents can be read, modified and saved to the local file system.
Once logged in to Google Docs, the LOGIN_TOKEN$ property can be accessed and saved to avoid having to select and login to a Google account, allow access, and run the Login( ) method again. The login token can either be hard-coded into an encrypted program or saved to an encrypted file. The next time the Google Docs object gets instantiated, just include the saved login token and it will be logged into the same Google account automatically.
After one hour of inactivity, Google automatically expires a login. If logged in and Google expires the login, the next time you run a method, the object will automatically re-login. This may be noticeable if a method takes longer than usual to complete.
Google Docs documents are stored in your Google Drive cloud storage, not as local files. Google Drive supports directories and sub-directories. All methods of this object that support a document path allow the Google Drive directories and the document name to be specified so that documents can be organized more easily. For example, to create a new document "SalesReport" in the Google Drives directory "Template", the following method can be used:
CreateDocument("Templates\SalesReport")
All modifications made to a Google Docs document are automatically saved. There are no Save methods. Modifications should not be made unless they are to be saved. If the original unmodified document needs to be preserved, create a copy and modify it.
To work with a local document, upload it to Google Docs by using the UploadDocument( ) method. This method converts the local document file into a Google Docs document, allowing you to work with it using this object. Supported file types that can be uploaded and converted are Microsoft Word (.doc, .docx, .dot), OpenDocument Text (.odt), HTML (.htm, .html), RTF (.rtf) and plain text (.txt).
To download a Google Docs document, use the ExportDocument( ) method. This method converts the Google Docs document into a local document file. The type of document is determined by the file extension specified in the output path. Supported file types that a document can be converted to and downloaded are Microsoft Word (.doc, .docx, .dot), Open Office doc (.odt), HTML (.htm, .html), zipped HTML (.zip), RTF (.rtf), plain text (.txt), PDF (.pdf), and EPUB (.epub).
The properties used by the Google Docs object are listed below.
Property |
Description |
Defaults to '0' for case insensitive searches. Set to '1' for case sensitive searches. See Find, FindInsert, FindReplace, FindReplaceAll, FindSetColor and FindSetFont methods below. | |
(Read Only) Index of the active open document. This property is set by using the SetDocument( ) method. If the ACTIVE_DOCUMENT is not set with the SetDocument( ) method, it is always the last opened document/highest index number. Returns '0' if no documents are opened. | |
DOCUMENTS_COUNT |
(Read Only) Number of documents opened. |
Defaults to '0' so that the Insert (see FindInsert) will insert text after the position located with the Find method. To insert text before the position located with the Find method, set this value to '1'. | |
Login token (also known as an Oauth2 refresh token) that can be used when instantiating the object to avoid having to login again. | |
Defaults to '1' so that the FindReplaceAll and the various Find methods (see Find, FindInsert, FindReplace, FindSetColor and FindSetFont) will search from the beginning of the document to the end. To begin at the end of the document (i.e. find the last occurrence of a string), set this value to '0'. |
The methods used by the Google Docs object are listed below. To make it easier to locate information for a particular method, this list has been broken into smaller groups as follows:
|
For logging into Google and confirming logged in status | |
|
For working with Google Docs document files | |
|
For working with paragraphs in a Google Docs document | |
|
For working with sentences in a Google Docs document | |
|
For working with found text in a Google Docs document |
Common Parameters
The following is a list of some of the common parameters used by multiple methods of the Google Docs object:
Parameter |
Description |
document |
1-based index number in the list of sequentially opened documents. If DocA, DocB and DocC were opened in that order, the corresponding indexes would be 1, 2 and 3. If DocAwas closed at index 1, then DocB and DocC would now have indexes 1 and 2 respectively. |
document_fileID$ |
Every document in a Google Drive cloud has a unique file ID. The file ID is displayed in the address bar when a Google Docs document is opened in a Web browser. Since it is possible to have more than one document with the same path, the file ID is used to specify a particular document. This parameter is used by methods that end with ByID. |
document_path$ |
The Google Docs path consists of any directories and a document name. It can be used as a simple and readable method to specify a document. This parameter is used by methods that end with ByPath. Note: |
Authentication Methods |
Description |
Returns '1' if logged into Google Docs. Returns '0' if not yet logged into Google Docs. Note: | |
During object instantiation, the user will be asked to select a Google account and allow access to it. When this process is completed, run this method to complete login to Google Docs. Returns '1' if successful. Returns '0' if any error is encountered while logging in. |
Document Methods |
Description |
CloseDocument(document) CloseDocumentByID(document_fileID$) CloseDocumentByPath(document_path$) |
Closes the document specified by an open document index number, a Google Docs file ID, or a Google Docs path. If no document is specified, the active document will be closed. If you close the ACTIVE_DOCUMENT, the ACTIVE_DOCUMENT is set to the last opened document still open; i.e. the highest document index or 0 if no documents are left opened. Note:
|
CloseDocuments( ) |
Closes all open documents. Returns '1' if successful. Returns '0' if any error is encountered while closing the documents. |
CopyDocument(copy_path$) CopyDocument(copy_path$,document) CopyDocumentByID(copy_path$,document_fileID$) CopyDocumentByPath(copy_path$,document_path$) |
Makes a copy with the given path of the document specified by an open document index number, a Google Docs file ID, or a Google Docs path. If no document is specified, the active document will be copied. Returns '1' if successful. Returns '0' if any error is encountered while copying the document. |
CreateDocument(document_path$) |
Creates a new blank Google Docs document with the path document_path$. The new document is opened and becomes the ACTIVE_DOCUMENT. If the document_path$ parameter is null, the document is named "Untitled". Important Note:
|
DeleteDocument( ) DeleteDocument(document) DeleteDocumentByID(document_fileID$) DeleteDocumentByPath(document_path$) |
Deletes the document from Google Docs specified by an open document index number, a Google Docs file ID, or a Google Docs path. If no document is specified, the active document will be deleted. The document is closed as well. Returns '1' if successful. Returns '0' if any error is encountered while deleting the document. |
ExportDocument(output_path$,document) ExportDocumentByID(output_path$,document_fileID$) ExportDocumentByPath(output_path$,document_path$) |
Converts the ACTIVE_DOCUMENT or the document specified by the open document index number, a Google Docs file ID, or a Google Docs path from a Google Docs document to a document file, and then downloads the file to the local file system. The type of local document file and the path of the file is determined by output_path$. For supported output_path$ file types, see Cloud-Based Documents. Returns '1' if successful. Returns '0' if any error is encountered while converting and downloading the document. |
GetFileID$( ) GetFileID$(document) |
Returns a Google Docs file ID of the document specified by an open document index number. If no document is specified, the Google Docs file ID of the active document is returned. Before getting a file ID, the file must be opened first. Returns "" if unable to locate the document. |
GetPath$( ) GetPath$(document) |
Returns a Google Docs path of the document specified by an open document index number. If no document is specified, the Google Docs path of the active document is returned. Returns "" if unable to locate the document. |
OpenDocumentByID(document_fileID$) OpenDocumentByPath(document_path$) |
Opens the Google Docs document specified either by a Google Docs file ID or a Google Docs path. After opening a document, the ACTIVE_DOCUMENT property is set to the document index corresponding to the document just opened. Note:
|
SetDocumentByID(document_fileID$) SetDocumentByPath(document_path$) |
Sets the ACTIVE_DOCUMENT index to the document specified by an open document index number, a Google Docs file ID, or a Google Docs path. For a document to be set as active, the document must be opened. Returns '1' if successful. Returns '0' if unable to locate the document. |
Upload a local document file input_path$ to Google Docs and convert to Google Docs document. The new Google Docs document is given the specified Google Docs path. For supported input_path$ file types, see Cloud-Based Documents. Returns '1' if successful. Returns '0' if any error is encountered while uploading the document. |
Paragraph Methods |
Description |
AppendParagraph(para_text$) AppendParagraph(para_text$,document) AppendParagraphByID(para_text$,document_fileID$) AppendParagraphByPath(para_text$,document_path$) |
Appends the text para_text$ as a new paragraph at the end of the document specified by an open document index number, a Google Docs file ID, or a Google Docs path. If no document is specified, the active document is assumed. To insert a paragraph with no text, set para_text$="". Returns '1' if successful. Returns '0' if unable to locate the document specified. |
InsertParagraph(para_text$) InsertParagraph(para_text$,para_num) InsertParagraph(para_text$,para_num,document) InsertParagraphByID(para_text$,para_num,document_fileID$) InsertParagraphByPath(para_text$,para_num,document_path$) |
Inserts the text para_text$ as a new paragraph added to the document specified by an open document index number, a Google Docs file ID, or a Google Docs path. The paragraph will be inserted as paragraph number para_num. If no document is specified, the active document is assumed. If para_num is not specified or is set to 0, the paragraph will be inserted as paragraph 1. If para_num is larger than the current number of paragraphs, the paragraph will be inserted as the last paragraph. Alternatively, to insert a paragraph at the very end of the document, use one of the AppendParagraph( ) methods. To insert a paragraph with no text, set para_text$="". Returns '1' if successful. Returns '0' if unable to locate the document specified. |
ReadParagraph$(para_num) ReadParagraph$(para_num,document) ReadParagraphByID$(para_num,document_fileID$) ReadParagraphByPath$(para_num,document_path$) |
Reads the contents of the paragraph numbered para_num in the document specified by an open document index number, a Google Docs file ID, or a Google Docs path. If no document is specified, the active document is assumed. A para_num value of less than 1 will read the first paragraph. Returns a string containing the text for the paragraph specified if successful. Returns "0" if unable to locate the document specified or the paragraph number para_num does not exist. |
DeleteParagraph(para_num) DeleteParagraph(para_num,document) DeleteParagraphByID(para_num,document_fileID$) DeleteParagraphByPath(para_num,document_path$) |
Deletes the paragraph numbered para_num from the document specified by an open document index number, a Google Docs file ID, or a Google Docs path. If no document is specified, the active document is assumed. A para_num value of less than 1 will delete the first paragraph. Returns '1' if successful. Returns '0' if unable to locate the document specified or the paragraph number para_num does not exist. |
Sentence Methods |
Description |
AppendSentence(sent_text$) AppendSentence(sent_text$,document) AppendSentenceByID(sent_text$,document_fileID$) AppendSentenceByPath(sent_text$,document_path$) |
Appends the text sent_text$ as a new sentence (or sentences) at the end of the document specified by an open document index number, a Google Docs file ID, or a Google Docs path. If no document is specified, the active document is assumed. Returns '1' if successful. Returns '0' if unable to locate the document specified. |
InsertSentence(sent_text$) InsertSentence(sent_text$,sent_num) InsertSentence(sent_text$,sent_num,document) InsertSentenceByID(sent_text$,sent_num,document_fileID$) InsertSentenceByPath(sent_text$,sent_num,document_path$) |
Inserts the text sent_text$ as a new sentence (or sentences) added to the document specified by an open document index number, a Google Docs file ID, or a Google Docs path. If no document is specified, the active document is assumed. If sent_num is set to 0, the sentence will be inserted as sentence 1. If sent_num is larger than the current number of sentences, the sentence will be inserted as the last sentence. Alternatively, to insert a sentence at the very end of the document, use one of the AppendSentence( ) methods. Returns '1' if successful. Returns '0' if unable to locate the document specified. |
ReadSentence$(sent_num) ReadSentence$(sent_num,document) ReadSentenceByID$(sent_num,document_fileID$) ReadSentenceByPath$(sent_num,document_path$) |
Reads the contents of the sentence numbered sent_num in the document specified by an open document index number, a Google Docs file ID, or a Google Docs path. If no document is specified, the active document is assumed. A sent_num value of less than 1 will read the first sentence. Returns a string containing the text for the sentence specified if successful. Returns "0" if unable to locate the document specified or the sentence number sent_num does not exist. |
DeleteSentence(sent_num) DeleteSentence(sent_num,document) DeleteSentenceByID(sent_num,document_fileID$) DeleteSentenceByPath(sent_num,document_path$) |
Deletes the sentence numbered sent_num from the document specified by an open document index number, a Google Docs file ID, or a Google Docs path. If no document is specified, the active document is assumed. A sent_num value of less than 1 will delete the first sentence. Returns '1' if successful. Returns '0' if unable to locate the document specified or the sentence number sent_num does not exist. |
Text Methods |
Description |
Find(find$,document) Find(find$,document,instance) FindByID(find$,document_fileID$) FindByID(find$,document_fileID$,instance) FindByPath(find$,document_path$) FindByPath(find$,document_path$,instance) |
Determines if a particular string (find$) exists in a document specified by an open document index number, a Google Docs file ID, or a Google Docs path. If no document is specified or the document index number is 0, the active document is assumed. Specify an instance value to indicate which occurrence of the find$ text that the Find is to locate if different from the first occurrence. (e.g. instance of 2 refers to second occurrence). If the Find is to begin from the end of the document, set the SEARCH_FORWARD property to '0'. Searches are case insensitive by default. For case sensitive searches, set the CASE_SENSITIVE_SEARCH property to '1'. Returns '1' if the text find$ was found. Returns '0' if unable to locate the document or if the text find$ was not found in the document. |
FindInsert(find$,insert$,document) FindInsert(find$,insert$,document,instance) FindInsertByID(find$,insert$,document_fileID$) FindInsertByID(find$,insert$,document_fileID$,instance) FindInsertByPath(find$,insert$,document_path$) FindInsertByPath(find$,insert$,document_path$,instance) |
Finds the text find$ in a document specified by an open document index number, a Google Docs file ID, or a Google Docs path and inserts the text insert$ into the document. If no document is specified or the document index number is 0, the active document is assumed. To perform the Insert on all opened documents, pass a document_path$ of "ALL" (case insensitive). Specify an instance value to indicate which occurrence of the find$ text that the Find is to locate if different from the first occurrence. (e.g. instance of 2 refers to second occurrence). If the Find is to begin from the end of the document, set the SEARCH_FORWARD property to '0'. Searches are case insensitive by default. For case sensitive searches, set the CASE_SENSITIVE_SEARCH property to '1'. By default, the insert$ text will be inserted immediately following the find$ text. To insert the insert$ text before the find$ text, set the INSERT_BEFORE property to '1'. Returns '1' if successful. Returns '0' if the Find was unsuccessful or if unable to locate the document or insert the text. |
FindReplace(find$,replace$,document) FindReplace(find$,replace$,document,instance) FindReplaceByID(find$,replace$,document_fileID$) FindReplaceByID(find$,replace$,document_fileID$,instance) FindReplaceByPath(find$,replace$,document_path$) FindReplaceByPath(find$,replace$,document_path$,instance) |
Finds the text find$ in a document specified by an open document index number, a Google Docs file ID, or a Google Docs path and replaces the find$ text with the replace$ text. If no document is specified or the document index number is 0, the active document is assumed. To perform the Replace on all opened documents, pass a document_path$ of "ALL" (case insensitive). Specify an instance value to indicate which occurrence of the find$ text that the Find is to locate if different from the first occurrence. (e.g. instance of 2 refers to second occurrence). If the Find is to begin from the end of the document, set the SEARCH_FORWARD property to '0'. Searches are case insensitive by default. For case sensitive searches, set the CASE_SENSITIVE_SEARCH property to '1'. Returns '1' if successful. Returns '0' if the Find was unsuccessful or if unable to locate the document or replace the text. |
FindReplaceAll(find$,replace$) FindReplaceAll(find$,replace$,document) FindReplaceAllByID(find$,replace$,document_fileID$) FindReplaceAllByPath(find$,replace$,document_path$) |
Finds the string find$ and replaces all occurrences with the string replace$. When only the find$ and replace$ parameters are passed, Find/Replace is performed on the active document. Pass an open document index number, a Google Docs file ID, or a Google Docs path to perform Find/Replace on a document other than the active document without changing the ACTIVE_DOCUMENT property. To perform the Find/Replace on all opened documents, pass a document_path$ of "ALL" (case insensitive). Searches are case insensitive by default. For case sensitive searches, set the CASE_SENSITIVE_SEARCH property to '1'. Searches will replace all occurrences of the find$ string. The FindReplace method can be used to replace a single occurrence of the find$ string. Returns '1' if successful. Returns '0' if unable to perform Find/Replace on any of the documents specified or if the find$ value was not found. When finding/replacing on all documents: Returns '-1' if only able to perform Find/Replace on some of the documents successfully. |
FindSetColor(find$,color_index) FindSetColor(find$,color_index,document) FindSetColor(find$,color_index,document,instance) FindSetColorByID(find$,color_index,document_fileID$) FindSetColorByID(find$,color_index,document_fileID$,instance) FindSetColorByPath(find$,color_index,document_path$) FindSetColorByPath(find$,color_index,document_path$,instance) FindSetColor(find$,color$) FindSetColor(find$,color$,document) FindSetColor(find$,color$,document,instance) FindSetColorByID(find$,color$,document_fileID$) FindSetColorByID(find$,color$,document_fileID$,instance) FindSetColorByPath(find$,color$,document_path$) FindSetColorByPath(find$,color$,document_path$,instance) |
Finds the text find$ in a document specified by an open document index number, a Google Docs file ID, or a Google Docs path and sets the color for that text as specified in color_index or color$. If no document is specified or the document index number is 0, the active document is assumed. To set the color of the find$ text on all opened documents, pass a document_path$ of "ALL" (case insensitive). Specify an instance value to indicate which occurrence of the find$ text that the Find is to locate if different from the first occurrence. (e.g. instance of 2 refers to second occurrence). If the Find is to begin from the end of the document, set the SEARCH_FORWARD property to '0'. Searches are case insensitive by default. For case sensitive searches, set the CASE_SENSITIVE_SEARCH property to '1'. The text color may be passed as one of the following: • A color index (numeric) • An RGB value in the format "RGB:rrr,ggg,bbb" (string) • "HSL:hhh,sss,lll" (string) • Hex "#nnnnnn" (string) • One of the 16 basic PxPlus named colors, such as 'Red', 'Dark Blue' or 'Light Cyan' (string) • A color-blended string, such as 'Red'+'Yellow' • Dynamic color lightening, such as "Red*50" (string) Returns '1' if successful. Returns '0' if the Find was unsuccessful or if unable to locate the document or set the color. |
FindSetFont(find$,font$,document) FindSetFont(find$,font$,document,instance) FindSetFontByFileID(find$,font$,document_fileID$) FindSetFontByFileID(find$,font$,document_fileID$,instance) FindSetFontByPath(find$,font$,document_path$) FindSetFontByPath(find$,font$,document_path$,instance) |
Finds the text find$ in a document specified by an open document index number, a Google Docs file ID, or a Google Docs path and sets the font information (font name, font size, font style) for that text as specified in font$. If no document is specified or the document index number is 0, the active document is assumed. To set the font of the find$ text on all opened documents, pass a document_path$ of "ALL" (case insensitive). Specify an instance value to indicate which occurrence of the find$ text that the Find is to locate if different from the first occurrence. (e.g. instance of 2 refers to second occurrence). If the Find is to begin from the end of the document, set the SEARCH_FORWARD property to '0'. Searches are case insensitive by default. For case sensitive searches, set the CASE_SENSITIVE_SEARCH property to '1'. The font$ variable can pass font name, font size and font style (Bold, Italic, etc.), separated by commas. The font name is case sensitive. If an unsupported font name is specified, Arial is used. Example: Note:
|
This example program tests the Google Docs object.
! Test Google Docs object
!
! Instantiate object where you define the clientID$ and clientSecret$ variables to be the values you got from Google
gd=NEW("*obj/GoogleDocs",clientID$,clientSecret$)
!
! Wait for user to complete Google sign-in and allow PxPlus access
INPUT "Press any key to continue after logging into Google account and allowing PxPlus access:",*;print ""
!
! Complete the Google Docs login
gd'Login()
!
! Open document from root Google Docs folder
path$="SalesReport"
if gd'OpenDocumentByPath(path$)=0 then MSGBOX "Error opening first document"
!
! Open another document this one from a different Google Docs folder
path2$="Notifications/NewDiscount"
if gd'OpenDocumentByPath(path2$)=0 then MSGBOX "Error opening second document"
!
! Check number of documents open
MSGBOX STR(gd'documents_count),"Open Document Count"
!
! Set document to first document opened
if gd'SetDocumentByPath(path$)=0 then MSGBOX "Error making first document active"
!
! Search and Replace on all opened documents
find$="[FirstName]"
replace$=firstName$
if gd'FindReplaceAllByPath(find$,replace$,"all")<>1 then MSGBOX "Error inserting name into templates"
!
! Set active document
if gd'SetDocument(2)=0 then MSGBOX "Error making second document active"
!
! find text and set font in active document
if gd'FindSetFont("New discount","Algerian,18,bold")=0 then MSGBOX "Error setting font"
!
! find second instance of text and set color to light blue of active document
if gd'FindSetColor("Sample text",4,0,2)=o then MSGBOX "Error setting color"
!
! Find last instance of text and replace with alternate text in test.docx
gd'search_forward=0
if gd'FindReplaceByPath("Find Text","Replace text",path2$,1)=0 then MSGBOX "Error replacing last instance of text in second document"
!
! Save active document as local docx file
gd'ExportDocument("c:\users\user\documents\NewDiscount.docx")
!
!
DROP OBJECT gd
END
This example demonstrates using the Google Docs object to replace given placeholders in a template document with variable data:
promo document:
PxPlus promo program:
! promo - Use Google Docs object for mail merge
!
OPEN (HFN,IOL=*)"client"
clients=LFO
!
path$="C:\PVX Plus Technologies\PxPlus version_number\word\"
!
! replace x's with your client ID, client secret, and login token before running this program
clientID$="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" ! Get from Google
clientSecret$="xxxxxxxxxxxxxxxx" ! Get from Google
loginToken$="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" ! Get from running Google Docs object, doing a login, and getting LOGIN_TOKEN$ property previously
!
gd=NEW("*obj/GoogleDocs",clientID$,clientSecret$,loginToken$)
!
! populate client name and address data
search_fields$="ClientName$"+SEP+"Address1$"+SEP+"Address2$"+SEP+"City$"+SEP+"State$"+SEP+"Country$"+SEP+"ZipCode$"+SEP+"ytdSales"+SEP
SELECT * FROM clients WHERE ytdSales>10000
ERASE path$+clientID$+".docx",ERR=*NEXT
gd'DeleteDocumentByPath("promos/"+clientID$)
gd'UploadDocument(path$+"promos.docx","promos/"+clientID$)
gd'OpenDocumentByPath("promos/"+clientID$)
!
!
FOR field$ FROM search_fields$
find$="["+field$+"]"
IF find$="[ytdSales]" THEN replace$="$"+STP(STR(ytdSales:"###,###.00"),"L"," ") ELSE replace$=VIS(field$)
gd'case_sensitive_search=1
gd'FindReplaceAll(find$,replace$)
NEXT
!
! populate dates
gd'FindReplaceAll("[TodaysDate]",DTE(0:"%Ml %D,%Y"))
gd'FindReplaceAll("[YearDate]",DTE(0:"%Y"))
!
! highlight '25% off coupon'
gd'FindSetColor("25% off coupon","red")
!
gd'ExportDocument(path$+clientID$+".docx")
gd'CloseDocument(1)
!
NEXT RECORD
!
DROP OBJECT gd
CLOSE (clients,ERR=*NEXT)
!
END
PxPlus Google Drive Object
PxPlus Google Sheets Object
Google Workspace® is a registered trademark of Google LLC