Help Center

Menu

Tutorial 3 - Editing data

Your event app currently allows you to create new events, each of which stores a name, description, date, time, and cost data, in separate uneditable fields.

In this tutorial, you will extend the existing blueprint and event app functionality (utilising the JS SDK) to add field editing capabilities to existing events.

This tutorial takes around 20-30 minutes to complete.

Define a PATCH method for event documents

A PATCH request will be defined in your API specification to allow any values of properties for an existing event (passed in the body of such an HTTP request), to be updated.

To define this method:

  1. In the event-app/api/ directory, open the api.yaml file.

  2. Copy YAML snippet (below), and paste it to the end of your api.yaml file, ensuring that patch: lines up with the get: definition above it.

        patch:
      description: Update an event info
      x-datastore-acl: public
      responses:
        '200':
          description: The event info is returned
          content:
            application/json:
              schema:
                $ref: './schemas/event.json'
      requestBody:
        content:
          application/json:
            schema:
              $ref: './schemas/event.json'

    You should now see that this additional YAML snippet defines the PATCH request on the /events/{eventid} endpoint of your API specification.

    The PATCH request to (and response from) the /events/{eventid} endpoint returns properties defined by the event.json object. The request updates one or more properties of an existing event document (specified by /events/{eventid}), where these properties are defined by the event.json object. The response is also an event document, whose properties are defined by event.json. (The functionality that handles the processing of the request and response is part of the JS SDK and Datastore service.)

  3. Save the updated api.yaml file.

Define the eventid property on event documents

Define the eventid property within the event.json file to allow your app to retrieve the internal ID of an event document stored in your Datastore service. This allows your event app to retrieve and interact with event documents stored within your Datastore service using this internal ID, which is exposed to your app via the eventid property.

This eventid definition, along with the API specification defined back in Tutorial 1, allows API calls with the:

  • GET request to the /events endpoint to retrieve a collection of event documents (each identified by their eventid property values).

  • GET request to the /events/{eventid} endpoint to retrieve a specific event document, identified by its eventid property value.

  • PATCH request to the /events/{eventid} endpoint to update a specific event document, identified by its eventid property value.

To define the eventid property:

  1. In the event-app/api/schemas/ directory, open the event.json file.

  2. Copy the JSON snippet (below), and paste it immediately between the parent properties and child name entries near the top of your event.json file, such that the new eventid entry lines up as a sibling with the existing name entry below it.

            "eventid": {
            "x-datastore-source": "document.$id",
            "description": "The ID of the document."
        },

  3. Save the updated event.json file.

This new eventid property uses a Datastore extension to JSON Schema called x-datastore-source. The
x-datastore-source directive instructs Datastore to expose the document’s internal ID (referred to by document.$id) to a document object that can be utilized by your app through the eventid property.

Copy the 'tutorial 3' files over to your event-app directory

Now copy the next level of your app’s functionality (which handles your API changes above) from the source tutorial repository over to your event-app directory.

  1. From the event-app directory, copy the content of the step4 directory to the event-app directory:

    $ cp -r ../tutorial/step4/*.* .

  2. Refresh or re-open the initial index.html file in the event-app directory.

Test the updated app

Notice that each existing event you had previously created now has an Edit link to the right of it.

  1. Click an Edit link to the right of an existing event to edit its values in the resulting Edit an event dialog box.

  2. Update some of the fields' values on this dialog box.

  3. Click Update event to update the event’s modified values.

Examine the updateEvent function in the main.js file

In the event-app directory, open the main.js file and examine the const updateEvent …​ function definition towards the middle of the file.

The following code snippet shows the JS SDK call to update an existing event document from the events collection.

/**
 * Updates the current event.
 */
const updateEvent = () => {
    ...
    const data = getData('#editEvent'); (1)
    ...
    if (Object.keys(data).length !== 0) {
        datastore.collection('events').doc(editingEvent.eventid).update(data).then((event) => { (2)
            ...
        }).catch((error) => { (3)
            printError('#editEvent .modal-body', error);
        });
    }
};
1 JavaScript code to retrieve the property values from the event document (which the user is about to edit through the app), and assigned to the data object constant.
2 The JS SDK call to update data in an existing event document (specified by its ID) in your Datastore service.
The datastore.collection() method sets the top-level collection (i.e. events initially defined in tutorial 1) as an object.
The doc() method is then called on this collection() object to prepare a document request object for the existing event document, specified by its ID. This ID value is retrieved from a property of your app’s event document object (editingEvent.eventid).
The update() method is then called on the prepared document request object to update the properties for the event document (whose ID is editingEvent.eventid), with those held temporarily in the data object. This method uses the API’s patch definition within /events/{eventid}, also initially defined in tutorial 1, to update the event document (specified by your app’s editingEvent.eventid value).
Note: editingEvent is an object representing an event document, whose value is set elsewhere in main.js.
3 The JavaScript function to handle the error response from the Datastore service, if the update() method does not return an HTTP status value of 200. The error response from the Datastore service is temporarily held by error, which the app then outputs.
An error may occur if the value of editingEvent.eventid does not match that of an existing event document ID in your Datastore service.

Now that you understand how to define API endpoints to update properties of existing documents using the JS SDK, you can now extend the functionality of your event app to handle the ability to edit your data.