Options
All
  • Public
  • Public/Protected
  • All
Menu

Class TadGitHub

TadGitHub (Library)

This is a class that is used for interacting with GitHub (https://github.com).

Please note that GitHub is not designed to permit rapid successive pushes of the same file - it takes GitHub a bit of time to process all the requests it receives from the user base. When interacting with GitHub, try and batch up file updates into one push rather than say four or five all executed within a few seconds. If you try that you are more than likely to run into SHA and content mis-matches.

Hierarchy

  • TadGitHub

Index

Constructors

constructor

  • new TadGitHub(p_strUserID: string): TadGitHub
  • Creates new instance of the TadGitHub class. The construction striggers the specification/retrieval form the Drafts credentials store, of the GitHub access token.

    Parameters

    • p_strUserID: string

      the GitHub ID of the account to use for interacting with GitHub.

    Returns TadGitHub

Methods

TA_accountGetRepos

  • Get a set of GitHub repository data for the current account. The data is returned as an array of repository objects. This is based entirely around the GitHub API List Organization Repositories call. The API does not really document the return, but rather provides example output. We are not documenting the rather extensive output, but instead refer you back to the GitHub API documentation example on this.

    Parameters

    • Optional p_strSortOrder: TYPE_strGitHubRepoSortOrder

      the sort order for the returned repositories. Defaults to order in which they were pushed.

    • Optional p_intPerPage: number

      number of repositories returned per page of results. Valid values are integer values between 1 and 100 inclusive. Defaults to 100.

    • Optional p_intPage: number

      the page number for the pages of results to return. Valid values are integers greater than 0. The default is 1.

    • Optional p_strSortDirection: string

      can be set to asc for asceding or desc for descending sort order. Default is asc.

    • Optional p_strType: TYPE_strGitHubRepoType

      defines which type of repositories are returned. Default is all.

      // Example
      let tg = new TadGitHub("MyGitHubID");
      alert(JSON.stringify(tg.TA_accountGetRepos()));

    Returns object[]

TA_accountGistDescriptions

  • Generate an array of gist descriptions for the current account.

    Parameters

    • Optional p_strSortOrder: TYPE_strGitHubRepoSortOrder

      the sort order for the displayed gists. Defaults to order in which they were pushed.

    • Optional p_intPerPage: number

      number of gists returned per page of results. Valid values are integer values between 1 and 100 inclusive. Defaults to 100.

    • Optional p_intPage: number

      the page number for the pages of results to return. Valid values are integers greater than 0. The default is 1.

      // Example
      let tg = new TadGitHub("MyGitHubID");
      alert(tg.TA_accountGistDescriptions().join("\n\n---\n\n"));

    Returns string[]

TA_accountGistInfo

  • Retrieve information about gists for the current account. The data is returned as an array of gist objects This is based entirely around the GitHub API List gists for the authenticated user call. The API does not really document the return, but rather provides example output. We are not documenting the rather extensive output, but instead refer you back to the GitHub API documentation example on this.

    Parameters

    • Optional p_strSortOrder: TYPE_strGitHubRepoSortOrder

      the sort order for the displayed gists. Defaults to order in which they were pushed.

    • Optional p_intPerPage: number

      number of gists returned per page of results. Valid values are integer values between 1 and 100 inclusive. Defaults to 100.

    • Optional p_intPage: number

      the page number for the pages of results to return. Valid values are integers greater than 0. The default is 1.

      // Example
      let tg = new TadGitHub("MyGitHubID");
      alert(JSON.stringify(tg.TA_accountGistInfo()));

    Returns object[]

TA_accountLookupGistID

  • TA_accountLookupGistID(p_strDescription: any, p_bRefreshGists?: Boolean, p_strSortOrder?: TYPE_strGitHubRepoSortOrder, p_intPerPage?: number, p_intPage?: number): any
  • Given an account's gist's description, return the ID of the gist. If the description is not found, an empty string is returned.

    Parameters

    • p_strDescription: any

      the description of the gist to find the ID for. The description must be unique to uniquely identify a gist.

    • Optional p_bRefreshGists: Boolean

      gists can be populated against the TadGitHub instance, so you can reduce API calls and time by passing false in here. Defaults to true.

    • Optional p_strSortOrder: TYPE_strGitHubRepoSortOrder

      the sort order for the displayed gists. Defaults to order in which they were pushed.

    • Optional p_intPerPage: number

      number of gists returned per page of results. Valid values are integer values between 1 and 100 inclusive. Defaults to 100.

    • Optional p_intPage: number

      the page number for the pages of results to return. Valid values are integers greater than 0. The default is 1.

      // Example
      let tg = new TadGitHub("MyGitHubID");
      alert(tg.TA_accountLookupGistID("description of a gist"));

    Returns any

TA_accountRepoNames

  • Return an array of repository names for the current account.

    Parameters

    • Optional p_strSortOrder: TYPE_strGitHubRepoSortOrder

      the sort order for the returned repository names. Defaults to order in which they were pushed.

    • Optional p_intPerPage: number

      number of repositories returned per page of results. Valid values are integer values between 1 and 100 inclusive. Defaults to 100.

    • Optional p_intPage: number

      the page number for the pages of results to return. Valid values are integers greater than 0. The default is 1.

    • Optional p_strSortDirection: string

      can be set to asc for asceding or desc for descending sort order. Default is asc.

    • Optional p_strType: TYPE_strGitHubRepoType

      defines which type of repositories are returned. Default is all.

      // Example
      let tg = new TadGitHub("MyGitHubID");
      alert(tg.TA_accountRepoNames().join("\n"));

    Returns string[]

TA_accountSelectGist

  • Select a gist description from the gist descriptions for the current account. The function displays an HTML prompt populated with available gist descriptions. On selection, the description of the selected gist is returned. If the selection is cancelled, an empty string is returned.

    Parameters

    • Optional p_strSortOrder: TYPE_strGitHubRepoSortOrder

      the sort order for the displayed gists. Defaults to order in which they were pushed.

    • Optional p_intPerPage: number

      number of gists returned per page of results. Valid values are integer values between 1 and 100 inclusive. Defaults to 100.

    • Optional p_intPage: number

      the page number for the pages of results to return. Valid values are integers greater than 0. The default is 1.

      // Example
      let tg = new TadGitHub("MyGitHubID");
      alert(tg.TA_accountSelectGist());

    Returns string

TA_accountSelectGistReturnID

  • Select a gist name from the gist descriptions for the current account, and return the ID of the gist. The function displays an HTML prompt populated with available gist descriptions. On selection, the ID of the selected gist is returned. If the selection is cancelled, an empty string is returned.

    Parameters

    • Optional p_strSortOrder: TYPE_strGitHubRepoSortOrder

      the sort order for the displayed gists. Defaults to order in which they were pushed.

    • Optional p_intPerPage: number

      number of gists returned per page of results. Valid values are integer values between 1 and 100 inclusive. Defaults to 100.

    • Optional p_intPage: number

      the page number for the pages of results to return. Valid values are integers greater than 0. The default is 1.

      // Example
      let tg = new TadGitHub("MyGitHubID");
      alert(tg.TA_accountSelectGistReturnID());

    Returns string

TA_accountSelectRepo

  • Select the name of a repository from a list of available repositories. The user is presented with a button-based selection prompt where each button is labelled with and will cause a return of the name of one of the available repositories for the current account. If no repository is selected, the function will return null.

    Parameters

    • Optional p_strSortOrder: TYPE_strGitHubRepoSortOrder

      the sort order for the displayed repository names. Defaults to order in which they were pushed.

    • Optional p_intPerPage: number

      number of repositories returned per page of results. Valid values are integer values between 1 and 100 inclusive. Defaults to 100.

    • Optional p_intPage: number

      the page number for the pages of results to return. Valid values are integers greater than 0. The default is 1.

    • Optional p_strSortDirection: string

      can be set to asc for asceding or desc for descending sort order. Default is asc.

    • Optional p_strType: TYPE_strGitHubRepoType

      defines which type of repositories are returned. Default is all.

      // Example
      let tg = new TadGitHub("MyGitHubID");
      alert(tg.TA_accountSelectRepo());

    Returns string

TA_fileAdd

  • TA_fileAdd(p_strRepoName: string, p_strPath: string, p_strContent: string, p_strCommitMessage: string): object
  • Commit and push a new file into an existing repository's main branch. This function can only be used for brand new files that do not currently exist in the repository at the path specified. See the TA_repoUpdateFile() function if you wish to update an existing file. The function will return an object. If you try to update a file, or add to a repository name that is not found, the return message attribute of the object will inform you of this as a 'missing SHA '(former) or 'not found' (latter). A successful creation will return extensive details about the success. Please note that this function will create any new folder structures specified in the path.

    Parameters

    • p_strRepoName: string

      the name of the repository the file is in.

    • p_strPath: string

      the path to the file to be created, including the file name.

    • p_strContent: string

      the content to be written to the file.

    • p_strCommitMessage: string

      the message for the content commit.

      // Example
      let tg = new TadGitHub("MyGitHubID");
      alert(tg.TA_fileAdd("test repo", "rootfolder1/subfolder2/file3.txt", "Some words as content", "Addition of a file"));

    Returns object

TA_fileAppendContent

  • TA_fileAppendContent(p_strRepoName: string, p_strPath: string, p_strAppendContent: string, p_strCommitMessage: string, p_strSeparator?: string): object
  • Append content to the current content for a file in a repository's main branch. This function can be used to update existing files, and also create brand new files that do not currently exist in the repository at the path specified. The TA_repoAddFile() function is slightly faster for creating new files as it does not first query for the SHA hash. It also will not accidentally modify an existing file. But if you don't mind a fractional delay for each file, or overwriting existing files without warning, then this function can be used for creating new files too. The function will return an object. If you try to add to a repository name that is not found, the object's message attribute will inform you of this as a 'not found'. A successful creation will return extensive details about the success. Please note that this function will create any new folder structures specified in the path.

    Parameters

    • p_strRepoName: string

      the name of the repository the file is in.

    • p_strPath: string

      the path to the file to be created, including the file name.

    • p_strAppendContent: string

      the content to be appended to the end of the file.

    • p_strCommitMessage: string

      the message for the content commit.

    • Optional p_strSeparator: string

      this optional parameter allows you to specify additional text to be placed after the existing content, but before the appended content. The default value is a newline.

      // Example
      let tg = new TadGitHub("MyGitHubID");
      alert(tg.TA_fileAppendContent("test repo", "rootfolder2/subfolder3/file4.txt", "Add this text to the end of the file", "Append demonstration"));

    Returns object

TA_fileGetContent

  • Get the current content for a file in a repository's main branch. The function queries the GitHub API for the specified path and content and returns a GitHubFileContent content object. This is just a convenient way to pass back two pieces of information. The success of the fetch, and the result - be it the content of the file, or the content of the error message the API provided. The function carries out the Base64 decoding of any content retrieved from the GitHub API;

    Parameters

    • p_strRepoName: string

      the name of the repository the file is in.

    • p_strPath: string

      the path to the file to be created, including the file name.

      // Example
      let tg = new TadGitHub("MyGitHubID");
      let objReturn = tg.TA_fileGetContent("test repo", "rootfolder2/subfolder3/file4.txt")
      if (objReturn.success) alert("SUCCESS:\n" + objReturn.content);
      else alert("FAILURE: " + objReturn.content);

    Returns GitHubFileContent

TA_fileGetSHA

  • TA_fileGetSHA(p_strRepoName: string, p_strPath: string): string
  • Return the SHA hash for a file in a specific repository's main branch. If the file is not found, including if the repository name is not found, the function will return undefined.

    Parameters

    • p_strRepoName: string

      the name of the repository the file is in.

    • p_strPath: string

      the path to the file, including the file name.

      // Example
      let tg = new TadGitHub("MyGitHubID");
      alert(tg.TA_fileGetSHA("test repo", "rootfolder1/subfolder2/file3.txt"));

    Returns string

TA_filePrependContent

  • TA_filePrependContent(p_strRepoName: string, p_strPath: string, p_strPrependContent: string, p_strCommitMessage: string, p_strSeparator?: string): object
  • Prepend content to the current content for a file in a repository's main branch.. This function can be used to update existing files, and also create brand new files that do not currently exist in the repository at the path specified. The TA_repoAddFile() function is slightly faster for creating new files as it does not first query for the SHA hash. It also will not accidentally modify an existing file. But if you don't mind a fractional delay for each file, or overwriting existing files without warning, then this function can be used for creating new files too. The function will return an object. If you try to add to a repository name that is not found, the object's message attribute will inform you of this as a 'not found'. A successful creation will return extensive details about the success. Please note that this function will create any new folder structures specified in the path.

    Parameters

    • p_strRepoName: string

      the name of the repository the file is in.

    • p_strPath: string

      the path to the file to be created, including the file name.

    • p_strPrependContent: string
    • p_strCommitMessage: string

      the message for the content commit.

    • Optional p_strSeparator: string

      this optional parameter allows you to specify additional text to be placed after the existing content, but before the appended content. The default value is a newline.

      // Example
      let tg = new TadGitHub("MyGitHubID");
      alert(tg.TA_filePrependContent("test repo", "rootfolder2/subfolder3/file4.txt", "Add this text to the start of the file", "Prepend demonstration"));

    Returns object

TA_fileUpdate

  • TA_fileUpdate(p_strRepoName: string, p_strPath: string, p_strContent: string, p_strCommitMessage: string): object
  • Commit and push a new file into an existing repository's main branch. This function can be used to update existing files, and also create brand new files that do not currently exist in the repository at the path specified. The TA_repoAddFile() function is slightly faster for creating new files as it does not first query for the SHA hash. It also will not accidentally overwrite an existing file. But if you don't mind a fractional delay for each file, or overwriting existing files without warning, then this function can be used for creating new files too. The function will return an object. If you try to add to a repository name that is not found, the object's message attribute will inform you of this as a 'not found'. A successful creation will return extensive details about the success. Please note that this function will create any new folder structures specified in the path.

    Parameters

    • p_strRepoName: string

      the name of the repository the file is in.

    • p_strPath: string

      the path to the file to be created, including the file name.

    • p_strContent: string

      the content to be written to the file.

    • p_strCommitMessage: string

      the message for the content commit.

      // Example
      let tg = new TadGitHub("MyGitHubID");
      alert(tg.TA_fileUpdate("test repo", "rootfolder2/subfolder3/file4.txt", "Some words as content", "Update of a file"));

    Returns object

TA_gistCreate

  • TA_gistCreate(p_strGistDescription: string, p_bPublic: Boolean, p_astrFilename: string[], p_astrContent: string[]): string
  • Create a gist. The function is capable of creating both public and private gists, and can create gists containing multiple files. The function returns the url for accessing the gist in a web browser (html_url) when it runs successfully, and undefined should it fail.

    Parameters

    • p_strGistDescription: string
    • p_bPublic: Boolean

      determines if the gist is to be public (true), or private (false).

    • p_astrFilename: string[]

      an array of file names for the files to be created in the gist. Each entry is paired with the same position entry in p_astrContent.

    • p_astrContent: string[]

      an array of file contents for the files to be created in the gist. Each entry is paired with the same position entry in p_astrFilename.

      // Example
      let tg = new TadGitHub("MyGitHubID");
      app.setClipboard(tg.TA_gistCreate("New gist description", false, ["foo.txt", "bar.txt"], ["I contain foo", "I contain bar"]));

    Returns string

TA_gistFetch

  • TA_gistFetch(p_strGistID: string): object
  • Retrieve information about a gist. The data is returned as a gist object This is based entirely around the GitHub API Get a Gist call. The API does not really document the return, but rather provides example output. We are not documenting the rather extensive output, but instead refer you back to the GitHub API documentation example on this.

    Parameters

    • p_strGistID: string

      the ID of the gist to be retrieved.

      // Example
      let tg = new TadGitHub("MyGitHubID");
      alert(JSON.stringify(tg.TA_gistFetch("abc12345")))

    Returns object

TA_gistFetchContent

  • TA_gistFetchContent(p_strGistID: string): any
  • Retrieve file content for a gist. For each file in the gist identified by the ID, the function will populate the returned array with an entry whose content matches the content of the file. For the majority of gists this is likely be a single entry array.

    Parameters

    • p_strGistID: string

      the ID of the gist whose content is to be retrieved.

      // Example
      let tg = new TadGitHub("MyGitHubID");
      alert(tg.TA_gistFetchContentToDrafts("abc12345").join("\n\n---\n\n"));

    Returns any

TA_gistFetchContentToDrafts

  • TA_gistFetchContentToDrafts(p_strGistID: string): number
  • Retrieve file content for a gist into new Drafts. For each file in the gist identified by the ID, the function will create a new draft containing the content of the file. The drafts are created with the default syntax specified in Drafts. The function returns the number of drafts created, and a creation message is displayed in the app.

    Parameters

    • p_strGistID: string

      the ID of the gist whose file content is to be created as new drafts.

      // Example
      let tg = new TadGitHub("MyGitHubID");
      alert("Drafts created: " + tg.TA_gistFetchContentToDrafts("abc12345"));

    Returns number