¶ basic concepts
In teaching scenes, sometimes we want to show lesson plans (such as slides, documents, etc.) in the room. These lesson plans are usually files in ppt, pptx, word, pdf and other formats. In order to display a lesson plan file in the room, the following operations are required.
- Upload the lesson plan document file to the source oss.
- Use Netless's document conversion service to convert teaching plan document files into static images or dynamic HTML, and store them in the target oss.
- Insert the converted lesson plan document into the room as a scene on the client to display it.
¶ Upload to source oss
oss, that is, Object Storage Service. It can provide safe, highly reliable, low-cost data storage capabilities, and can create, modify, upload, download, and delete objects. At present, mainstream cloud service vendors provide their own oss services (such as Alibaba Cloud's oss, AWS's S3, Qiniu Cloud's cloud storage).
You need to upload the lesson plan document file to your oss first, and then expose an accessible URL address to the public network to ensure that the address can be accessed by the Netless server. After that, the URL can initiate the document conversion task in the next chapter.
Netless's document conversion service only needs a URL address accessible from the public network. In theory, you can build an Nginx server yourself to replace the oss service, but we do not recommend you to do this. At present, the oss service provided by mainstream cloud service vendors is safe, reliable, low-cost, and free of operation and maintenance. Why bother to build an Nginx server by yourself?
Let’s take Alibaba Cloud as an example to create an oss service (other cloud service platforms are similar. You can read Alibaba Cloud’s official document, 《Opening OSS Service》, 《Create Storage Space》.
After that, you need to enable the public read permission for the newly created oss bucket to ensure that the Netless service can access the URL of the lesson plan document file stored here.
Of course, according to your business logic and the plan of the cloud service provider you choose. You don't have to set the bucket to "public read". You can also use other schemes according to business needs. As long as it can be ensured that the Netless service has the right to access the teaching plan document file through the URL.
¶ Document Conversion Service
The Netless document conversion task will read the teaching plan document file you just uploaded from the source oss through the URL you provided, then convert it into a picture or HTML file, and finally store it in the target oss.
There are two types of document conversion: "to image" and "to web page". The specific differences are as follows.
| Mode | Support Format | Support Animation | Product |
|---|---|---|---|
| Convert picture | pptx, ppt, word, pdf | Not supported | Picture |
| To web page | pptx | Support | HTML |
Before using the document conversion service, you need to configure the target oss to store the converted files.
The target oss should also be configured with public read (or above) permission to ensure that the client SDK can access it. In addition, if the oss is different from the domain name of your web application, you should configure the appropriate Cross-Domain Settings. No configuration or wrong configuration across domains may cause your web application service to fail to read the converted teaching plan document file.
First, enter the Netless Application Management Page, find the project you want to configure, and click the "Configuration" button to enter the configuration interface.
Then configure oss for "document to image" and "document to web page" respectively. First, click "Add Storage Configuration".
Then select the oss supplier (here, take Alibaba Cloud as an example).
Then follow the interface prompts to fill in the configuration items of the oss bucket, and finally click "Start Service" to complete the settings.
In particular, when choosing to use the storage service of Qiniu Cloud, an additional field of the external domain name needs to be configured, otherwise Netless will not be able to access the resources in the storage service.
Fill it in here in the Netless console.
After that, whenever you need to convert the lesson plan document file. You need to obtain the URL of the document file from the source oss, and then call the Netless server API (refer to 《PPT Conversion》 for details).
Specifically, you need to create a conversion task first. Then get the uuid of the conversion task, and create the accompanying taskToken. Then use uuid and taskToken as parameters to poll the status of the task. If the task is found to be successful, it means that the converted content (picture or web page) has been stored in the target oss. If the task is found to be failed, the abnormal process is followed.
It is recommended to leave a timeout logic for your polling process design.
¶ Show lesson plans in the room
After the conversion is successful (refer to 《Query conversion progress｜ PPT conversion》, you can get a JSON from the server. Among them, .progress .convertedFileList is an array used to describe the status of each page of the converted document.
Each element of the array is an object like the following.
{
"width": 1024, // current page width
"height": 960, // current page height
"conversionFileUrl": "xxxx://xxxx.xxx.xx/xxxx.xxx", // conversion result file address
"preview": "xxxx://xxxx.xxx.xx/xxxx.xxx", // Optional, preview image address, this field will only exist when the body parameter preview is true and type is dynamic when the conversion is initiated
}
We can return this array directly to the client, or store it in the database. When the client initiates a request to the business server, we can read it from the database and return it to the client.
After the client receives this array, it translates the information of each page into a scene object, and calls the Netless SDK method to insert it into the room.
{
name: "page-name-xxx",
ppt: {
src: conversionFileUrl, // Obtained from the previously mentioned object
preview: preview,
width: width,
height: height,
},
}
Netless is based on multiple scenarios, we can design multi-page whiteboard function, PPT presentation function. For details, please refer to 《Scene Management》.