Getting Started - LiquidGalaxyLAB/Presentation-Tool GitHub Wiki

Getting Started with the User Interface

Home page

With the front end already installed the first view you’ll have is the HOME PAGE. The home page contains all the presentations created for the connected Liquid Galaxy and offers a few interactions

On the right corner of the toolbar we have a configuration button that has the “Clean Storage” functionality. It triggers the CLEAN endpoint to clean the whole media storage.
On the left corner of the toolbar, if you click either the name of the project or the logo will be redirect to this HOME PAGE
The text fields give you the possibility to filter the presentations. They can be filtered by name or category

Each presentation card has 2 main interactions:

If you click on the center of the card you will trigger the EXECUTE endpoint and start the selected presentation on the Liquid Galaxy. The card that opens up after this interaction allows you to see some information and also to stop the execution. The “stop” button will trigger the STOP endpoint
You can click the configure button and it will show the options to Export, Edit or Delete the selected presentation
The export button trigger the EXPORT endpoint and downloads the presentation in .zip
The edit button sends the user to the PRESENTATION BUILDER to make the wanted editions
The delete button triggers the DELETE endpoint and deletes the selected presentation

On the bottom right of the page it’s located the “new presentation” button, where you can choose between import or create a new one

If you choose to import, a dialog will open up and you will be asked to submit a .zip. The IMPORT endpoint is triggered.
In the other hand if you want to create a new one you will be redirected to the PRESENTATION BUILDER

Presentation Builder

The builder is the tool you will be using to create and edit your presentations, it has many functionalities as described below:

The first part to be filled up is the Basic information. If you don’t fill up this part you will not be able to start creating slides It’s very important to select the correct number of screens you have on your Liquid Galaxy, as you may have problems if you get the number wrong. After finishing to complete, make sure to hit save
The second part has the slide creator to create the first slide just click on the new slide icon on the slide form you will see the options:
Fly to (use if you want to use google earth and fly somewhere)
Audio (if you want this slide to have a nice sound)
Duration (REQUIRED - the duration this slide will last)
Media (all the media this slide will use and on which screen/position it will be). To add new media to the slide, hit add and choose between image of video. Note video only has the options to be used in one screen. Image can be put in the sharing position, meaning it can be seen in two screens or one screen
Make sure to save the slide every time you edit it. After saving each slide, all of them will be displayed in a list and you can edit, delete or preview them at any time
Create as many slides you want, having as many media you need. Just take note that if you create a very big presentation it will take a lot more time to be saved on the Liquid Galaxy
Besides those two main parts, on the top of the slide creator there are three operations:
Discard (that will discard all the changes you’ve made)
Preview (that will show you the overall work you’ve done till now)
Save presentation (that will be used after you finished all your work and wants to send it to Liquid Galaxy). A preview is also shown before saving. This action will trigger the CREATE and UPLOAD endpoints
If the PRESENTATION BUILDER is called to edit a presentation, after all desired changes are made it will call the UPDATE and (if there is any new media) the UPLOAD endpoints

Getting Started using Swagger API Documentation

To serve as an API documentation and as an easy testing environment to users, it was integrated to the project the Swagger UI. Basically swagger auto generates API documentation based on comments on the routes code. The implemented UI is located on /api-docs route, but if you try to reach to the base route /, you are redirected to /api-docs as well.

On the generated HTML page, users can test each API endpoint and be able to see what are the required parameters, the models of the requests and all possible responses. The UI is more for exploratory purposes, but users can use them with no problems for long term activities if preferred. All endpoints are divided in 4 groups: demo, presentation,share and storage.

Demo

Very simple to use, just click on "Try it out" and then "Execute". This route imports a demo presentation to the server and executes it.

Presentation

presentation/execute/{id}

This route executes a presentation. Receives the _id as a parameter in the path. Just fill up the input with the _id and click "execute"

presentation/stop

Stops all the current tasks used when running a presentation. Just click "execute"

presentation/getall

Gets all saved presentations from the database. Click "execute" to retrieve a json containing all documents.

presentation/create

Receives a json with the structure of a presentation a creates a new presentation in the database

The structure that has to be followed is shown below:

{
  "id": "string",
  "title": "string",
  "description": "string",
  "maxscreens": 0,
  "category": "string",
  "audiopath": "string",
  "slides": [
    {
      "id": "string",
      "duration": 0,
      "audiopath": "string",
      "flyto": "string",
      "screens": [
        {
          "screennumber": 0,
          "media": [
            {
              "id": "string",
              "filename": "string",
              "type": "string",
              "storagepath": "string",
              "position": "string",
              "sharing": true,
              "partner": 0
            }
          ]
        }
      ]
    }
  ]
}

As the presentation consists of a set of slides that contains a set of screen that contains a set of media, feel free to add as many slides, screens and media as needed, as well as omitting and adding fields. For example, when we want to open an image in only one screen specific, we have to remove the "sharing" and "partner" fields, if we don't remove them we can face problems withing the API functionality.

presentation/delete/{id}

Receives the _id of a presentation as parameter and deletes it from the database and from the Liquid Galaxy storage. Just fill up the input with the _id and then click "execute".

presentation/update

Receives the fields of the document that needs to be updated in the database the _id of the presentation. The data field respects the same structure of the presentation.json used on CREATE. Complete the json and click "execute".

{
  "id": "string",
  "data": {}
}

share/export/{id}

Receives the _id of the presentation that needs to be exported. The presentation is exported as a .zip, but unfortunately you cannot download the file from swagger, you can only see the binary response.

share/import

Receives a .zip containing a presentation and save its content into the database and storage. It has to be in a valid format, meaning it needs to be organized inside in a way the server can understand. This format is created with the EXPORT endpoint, so make sure to import only presentations that were exported by that functionality.

Storage

storage/upload

Receives an array of multipart content-type media + storagepath + array of screens. Unfortunately the swagger instance only accepts one media file per time, so fill up each input with the correct information for the current media you are uploading.

storage/clean

Use this endpoint to clean up the local temporary storage of the master machine, the one that has a copy of all the media that has passed to the Liquid Galaxy instance. This action won't delete any of the presentations or harm any of them.

Getting Started using Postman

Install Postman, you can either use it on the master machine or in your computer
Import on Postman the collection file Presentations.postman_collection.json located inside the repository to use as a guide
Configure the url with the correct IP and PORT of your Liquid Galaxy
Also inside the repository there is a file called presentation.json, in the file you can see the correct way of setting up the body of your request for upload, create and update routes and also a explanation of all the parameters a presentation has.

Creating a presentation

When creating a presentation, the first thing you’ll have to send is the media you want. Go to the UPLOAD route and add the media on form-data just like explained below

As when uploading files on postman you can’t be sure of the order you upload them, in our case, order is very important, so I recommend you upload one media at a time to make sure you’re sending it to the correct place
Sending a simple media, that shows only in one screen: in this case you don’t need to use the partner parameter
Sending a media that appears in more than one screen (image): you have to add the partner screen (which is always the screen on the right). When you send the media, it will be cropped inside the API and each side will be sent to the correct lg

After using the upload route, you have to use the CREATE route to store the json that will be parsed by the API

On the CREATE route on postman, you’ll need to send a json via POST containing all required information for that presentation. Again, check out the presentation.json file inside the repository to get more info on how to build the json
After having the json ready to go, if there is any field you won’t use, omit it. For example, if you’re not going to set up an image that will be divided in two screens, you don’t have to put the key “sharing” and “partner”.
If everything goes well you’ll receive a status 201 in the response

Get all presentations

You can use the GETALL route to retrieve all the presentations stored in the database

Execute

On the EXECUTE route you can pass the _id of the presentation you want to run as a parameter on the path . If the presentation exists, you’ll receive a 202 status

Delete

To delete a presentation just pass the _id of the desired document to the DELETE route, it will delete the document in the database and the local media storage of that presentation in all machines

Stop a presentation in the middle of the execution

Use the STOP route, you don’t need to pass any values to this request.

Clean storage

The CLEAN route cleans up the main storage of the API. When deleting a presentation you clean only the folder of that specific presentation, this route cleans the folder that has the first access to the media, that contains all media that has been sent to the API

Update presentation

To update a presentation you have two steps to follow:

Update the media, for that just use the UPLOAD route to send it again
Update the json inside the database. To do that you can use the UPDATE route and a json containing two main keys:

id - that holds the id of the doc you want to update data - all the fields with the new values. This section follows the same structure as the one mentioned on CREATE, so make sure to have the json built just like that

Import

To import a presentation will you need a .zip file that was generated by the API using the EXPORT endpoint. If you try to use any other .zip the API doesn’t guarantee it will work, as may not be correctly formatted.
On the IMPORT route of the postman collection go to Body
Select Form data and choose the File type
There is only one field for this route that is the presentationzip, make sure to use this exact name
Upload the .zip
Send your request and if everything went as planned you will receive a 200

Export

To export a selected presentation use the EXPORT endpoint passing as a parameter the _id of the presentation you want to download.
Unfortunately you cannot download the .zip directly from postman. You can only use it to see the binary data that is a .zip