octomments

    1.0.5 • Public • Published

    Octomments client

    The core functionality of Octomments.

    Setup

    <script src="https://unpkg.com/octomments/build/ocs.min.js"></script>

    or

    > npm i octomments

    Usage

    import Octomments from 'octomments';
    
    function Renderer(api, container) {
      api.on(Octomments.USER_NONE, (loginURL) => {
        console.log(loginURL);
      });
    }
    
    const octomments = Octomments({
      github: {
        owner: '<username>',
        repo: '<repo name>',
      },
      issueNumber: <issue number>,
      renderer: [Renderer, '<selector>']
    });
    
    octomments.init();

    Options

    • github (required) - object containing owner (GitHub username) and repo (GitHub repository) fields.
    • issueNumber (required) - the number of an existing in the repository issue
    • renderer (required) - an array where the first element is a renderer function and the second one is a valid DOM element selector.
    • debug (optional) - a boolean. If true the library will print each of the dispatched events.
    • endpoints (optional) - an object with issue and token fields. The values of these fields are valid URLs pointing to Octomments server endpoints. You'll probably never need to setup those unless you deploy your own server. The already existing one is at ocs.now.sh.

    Methods

    api.init()

    Initiates the comments and user fetching.

    api.add(text)

    Adding of a new comment where text is the markdown of the comment.

    api.on(event, callback)

    • event - event type
    • callback - function called when the event is triggered

    Here is a table with all the possible events:

    event callback params description
    Octomments.ERROR
    • error
    • type of error
    when there is an error. Check the errors section below to see the possible types.
    Octomments.COMMENTS_LOADING
    • none
    when the loading of the comments begins
    Octomments.COMMENTS_LOADED
    • comments
    • pagination info
    when the comments are loaded
    Octomments.COMMENT_SAVING
    • none
    when the user submits a comment
    Octomments.COMMENT_SAVED
    • an array with one item - the new comment
    when the comment is saved successfully
    Octomments.USER_LOADING
    • none
    when the library initiates a request for the user's data
    Octomments.USER_NONE
    • user login url
    when there is no user logged in. Use this event to render a "log in" link.
    Octomments.USER_LOADED
    • user's data
    • first time
    when the data of the user is fetched successfully. The second parameter shows if the user is just logged in or his/her data is pulled from the local storage

    api.logout(refresh = true)

    Removes the user's data from the localStorage and (potentially) refreshes the page.

    api.page(index)

    Initiating a new comments fetching for a page with specific index.

    api.generateNewCommentURL()

    Returns a URL which you can use to make the user log in. It will redirect the user to ocs.now.sh/GitHub for authentication and then back to your page.

    api.off()

    Removes all the listeners added with api.on.

    Errors

    • 1 - comments: issue doesn't exists
    • 2 - comments: other problem loading the issue
    • 3 - comments: issue request succeed but can't parse the json response
    • 4 - comments: hit the V3 rate limit
    • 5 - user: corrupted data in local storage
    • 6 - user: can't get the access token
    • 7 - user: problem parsing the access token response
    • 8 - new comment: adding new comment failed
    • 9 - new comment: not authorized
    • 10 - new comment: request succeed but can't parse the json response

    Install

    npm i octomments

    DownloadsWeekly Downloads

    585

    Version

    1.0.5

    License

    MIT

    Unpacked Size

    77.5 kB

    Total Files

    19

    Last publish

    Collaborators

    • krasimir