diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 1737200..f01f768 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -14,4 +14,8 @@ - [Video Component](./chapter1/web-components/video.md) - [References Component](./chapter1/web-components/references.md) - [Pushing the changes you made to Github](./chapter1/push-to-github.md) -- [Optional enhancement]() +- [Chapter 2: Optional enhancement](./chapter2/index.md) + - [Make your report into multiple pages](./chapter2/pages.md) + - [Working with Chart.js](./chapter2/chart.md) + - [Working with Mermaid.js](./chapter2/diagram.md) + - [Working with 3D Render](./chapter2/3d-render.md) diff --git a/src/chapter2/3d-render.md b/src/chapter2/3d-render.md new file mode 100644 index 0000000..45b3a96 --- /dev/null +++ b/src/chapter2/3d-render.md @@ -0,0 +1,76 @@ +# Working with 3D Render + +To render 3D object such as your CAD in the format of `.stl` file, we will use the [Three.js](https://threejs.org/) library. It is a very cool library that allows you to do mind-blowing graphic stuff in the browser. However, it is very out-of-scope for our purpose, so we have helped written a component script so you can just simply use it with minimal configuration to display your `.stl` file. + +To use the 3D render component, we need to import the following into our `index.html` file. + +```html + + ... + + + + + ... + + + +``` + +It is a bit more complicated than other module because of the `three.js` library. It is important that you make sure the import is in the order above for `three.js` to work properly. Don't forget the `type="module"` when importing the `render.js` file as it is necessary for the script to work properly. + +To use the component, you just simply have to create a `
` with the `id` value that you want: + +```html +
+``` + +Then, in the `render.js` file call the `createRender` function accordingly as shown. + +```js +createRender( + "render1", + 400, + [0, -1, 0], + [0.05, 0.05, 0.05], + [-Math.PI / 2, 0, 0], + false, + "../assets/benchy.stl", +); +``` + +It will render your `.stl` file in the specified `
`. + +Now, let take a loot at what each of the arguments means, and how you can use them: + +```js +function createRender( + id, + height, + position, + scale, + rotation, + enableAxes, + stlFilePath, +) { +``` + +- `id`: is the id you gave to the `div` element that you want to render your `.stl` to. +- `height`: is the height in pixel of the view box of your object. You can adjust the width by modifying the `div` width directly +- `position`: the position of your object in 3D space, in the following order [x , y , z] +- `scale`: same as position but for scaling, you will have to experiment to see what scale would work for you as some stl can be very big, and some can be very small. +- `rotation`: same as position and scale, but for the rotation angle of your object. It uses Euler angle. As a rule of thumb you should use `Math.PI / 2` as trial value because it equals to a rotation of 90 degree. +- `enableAxes`: whether you want to enable the X Y Z axis for debugging purposes or not. +- `stlFilePath`: this is the path to your `.stl` file. Do note that Github has file size limitations to what you can upload there, so if your CAD is just too big in memory size, maybe it would be better if you upload it to some other storage method such as Google Drive or Dropbox and then provide the url to that `stl` file here. Otherwise, just put your `stl` file into the `assets` folder, and write the correct path to that `stl` file here. + +Rendering 3D can be quite intensive on some more underpowered devices, so try to only use this component to show things that would highlight your effort instead of dumping every single CAD that you have here. Because remember, the user would need to download all of you CAD before they can view them, so it doesn't make sense to make user download 1GB worth of CAD to view it for only 5 seconds. + +In another word, use this component prudently and responsibly. diff --git a/src/chapter2/chart.md b/src/chapter2/chart.md new file mode 100644 index 0000000..9823c36 --- /dev/null +++ b/src/chapter2/chart.md @@ -0,0 +1,254 @@ +# Working with Chart.js + +To make the process of creating chart simple and streamline, we will utilize [Chart.js](https://www.chartjs.org/docs/latest/) library. If you open up the `index.html` in the `chart` folder. You should see the following: + +```html + + + + + ..... + + + + + + + + + + + + +
+ Back + +

1. Pie and Doughnut Chart

+
+
+ +
+
+ +
+
+ +
+

2. Bar Chart

+
+ +
+ +
+

3. Line Chart

+
+ +
+ +
+

4. Scatter Chart

+
+ +
+ + + + + + + + + +``` + +We import the `Chart.js` library by simply adding the following line: + +```html + +``` + +Now, we will create elements where we will draw the chart using Javascript later. To do that we use the following syntax: + +```html +
+ + + + + + +``` + +This is because Javascript cannot grab an element if it has not been initialized yet. As we will see in the subsequent code in `chart.js`, it needs to know that `pie-chart` exist, before it can grab that elements, so we cannot declare the import before the declaration of the elements. In general, people tend to import Javascript code at the bottom of the body for this reason, but for organisation purpose, we would like to put thing related together closer to each other unless we have no other choice. + +Now open up the `chart.js` file. Take this sample code: + +```js +const PieCtx = document.getElementById("pie-chart"); +const DoughnutCtx = document.getElementById("doughnut-chart"); + +const PieData = { + labels: ["Red", "Blue", "Yellow"], + datasets: [ + { + label: "My First Dataset", + data: [300, 50, 100], + backgroundColor: [ + "rgb(255, 99, 132)", + "rgb(54, 162, 235)", + "rgb(255, 205, 86)", + ], + hoverOffset: 4, + }, + ], +}; + +new Chart(PieCtx, { + type: "pie", + data: PieData, +}); + +new Chart(DoughnutCtx, { + type: "doughnut", + data: PieData, +}); +``` + +The `PieCtx` constant holds the container which is the ``, this is how we tell Javascript which `` to draw what which is why we need the `id` to be unique. + +Then we define what the data we want the chart to render. We will go indepth into this in a bit. + +Finally, we will render this chart. To do this the syntax is: + +```js +new Chart(ctx, { + type: "pie", + data: PieData +}) +``` + +Where `ctx` stands for context, in another word, the `` element that you grab. `type` refer to chart type you want to render, and finally the data you want the chart to render. + +Now, we will go more indepth regarding the configuration of each graph, you could also learn more directly from [here](https://www.chartjs.org/docs/latest/charts/) + +## 1. Pie and Doughnut Chart + +```js +const PieData = { + labels: ["Red", "Blue", "Yellow"], + datasets: [ + { + label: "My First Dataset", + data: [300, 50, 100], + backgroundColor: [ + "rgb(255, 99, 132)", + "rgb(54, 162, 235)", + "rgb(255, 205, 86)", + ], + hoverOffset: 4, + }, + ], +}; +``` + +Let break down what each of this fields means: +- `labels`: the labels for your data, it should match with the number of data you have +- `datasets`: the content of chart + - `label`: is the label for this particular dataset, it will make more sense in subsequent charts + - `data`: this is where you specify your data in an array, make sure you have same number of data as the labels + - `backgroundColor`: this is for aesthetic purpose, you can use any standard css color syntax. If you don't want any color variation, just delete this portion. + - `hoverOffset`: is just show how far should the offset from the center of the chart where the tooltip show when you hover over the chart + +## 2. Bar Chart + +```js +const BarData = { + labels: ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul"], + datasets: [ + { + label: "My First Dataset", + data: [65, 59, 80, 81, 56, 55, 40], + borderWidth: 1, + }, + { + label: "My Second Dataset", + data: [23, 40, 67, 20, 79, 30, 80], + borderWidth: 1, + }, + ], +}; +``` + +We can see that the `datasets` now have 2 set of data: `My First Dataset` and `My Second Dataset`. + +This is why datasets is declared as an array of object. Because you can show one or more dataset on the same chart space. + +`borderWidth` just specify how thick the border of the bar you want them to be. + +## 3. Line Chart + +```js +const LineData = { + labels: ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul"], + datasets: [ + { + label: "My First Dataset", + data: [65, 59, 80, 81, 56, 55, 40], + fill: false, + tension: 0.1, + }, + { + label: "My Second Dataset", + data: [23, 40, 67, 20, 79, 30, 80], + tension: 0.1, + }, + ], +}; +``` + +- `fill`: whether you want the area under the line to be filled or not. +- `tension`: whether you want to smooth out the turn at each data point. At 0, it will just be straightline connect at each data point. + +## 4. Scatter Chart + +```js +const ScatterData = { + datasets: [ + { + label: "Scatter Dataset", + data: [ + { + x: 2, + y: 4, + }, + { + x: 3, + y: 2, + }, + { + x: 4, + y: 5, + }, + { + x: 0.5, + y: 5.5, + }, + ], + backgroundColor: "rgb(255, 99, 132)", + }, + ], +}; +``` + +Each data point in a scatter chart requires an `x` and `y` coordinates. We suggest that if you need to use a scatter graph, you should create a simple Python script maybe with the help of ChatGPT to convert all of your data to the format above and then just copy paste accordingly. diff --git a/src/chapter2/diagram.md b/src/chapter2/diagram.md new file mode 100644 index 0000000..ab9ca4b --- /dev/null +++ b/src/chapter2/diagram.md @@ -0,0 +1,39 @@ +# Working with Mermaid.js + +[Mermaid.js](https://mermaid.js.org) can be said to be the defacto standard when it comes to creating diagram using Domain Specific Language. In fact, if you have ever seen diagram being render on Github repository before, it is all thanks to mermaid.js. + +This section won't be teaching you how to create diagram but only how to allow you to render those diagram. To learn how to create this beautiful diagram, you can read their [document](https://mermaid.js.org/syntax/flowchart.html) or use their [Live Editor](https://mermaid.live) instead. + +If you open the `diagram` folder, you should be able to see 3 files: + +- `index.html` +- `diagram.js` +- `svg-pan-zoom.min.js` + +In the `index.html` file, we import 2 things: + +```html + + +``` + +The former is to import `mermaid.js`, the latter is to import the `svg-pan-zoom` library. Since this library have a bit of a problem being loaded from the CDN, we instead download it down to a file locally and name it as `svg-pan-zoom.min.js`. + +The purpose of the `svg-pan-zoom` is allowing us to zoom in and out and pan around our diagram, which will allow you to draw bigger diagram without worrying that it is not readable. This is the main advantage over just taking a picture of your diagram. You don't have to use it if you don't want to, but it surely would make your report more interactive. + +To render a mermaid chart, you just have to declare the `
` element and give it the mermaid class. It will automatically be rendered.
+
+Similar to the chart, we need to import `diagram.js` file at the bottom of the `` element.
+
+```html
+    ...
+
+    
+      
+    
+
+    
+
+```
+
+We don't actually need to know what is happening in the `diagram.js` file as it is only glue code to help with stitching the `svg-pan-zoom` with `mermaid.js` library. Just remember to include all of this file if you decide to use mermaid.js to draw your diagram.
diff --git a/src/chapter2/index.md b/src/chapter2/index.md
new file mode 100644
index 0000000..272f2cf
--- /dev/null
+++ b/src/chapter2/index.md
@@ -0,0 +1,15 @@
+# Chapter 2: Optional enhancement
+
+In this chapter, we will be learning how to use more advanced components to enhance your web report. We will learn how to:
+
+1. Split your report into seperate sections and tabs for ease of readability.
+2. Import components and code as you need them.
+3. Use Chart.js to create simple charts.
+4. Make interactive diagram with Mermaid.js.
+5. Render 3D object such as your CAD using Three.js.
+
+To view what the template for the optional enhancement, you can visit the link below:
+
+[Demo](https://edic-nus.github.io/advanced/)
+
+The source code is available [here](https://github.com/edic-nus/advanced)
diff --git a/src/chapter2/pages.md b/src/chapter2/pages.md
new file mode 100644
index 0000000..d693214
--- /dev/null
+++ b/src/chapter2/pages.md
@@ -0,0 +1,159 @@
+# Make your report into multiple pages
+
+In this section, we will learn how to split the content up into their respective pages so that you can more neatly organised your content for readability.
+
+## 1. Create a new content page
+
+So we have learn from Chapter 1 that when you visit your web report on Github, it will serve the `index.html` file back down to your browser and the rest of your report is render from there. However, if you try to cramp your whole report into only one page, it can become quite lengthy and sluggish to read. Overall, it is not just an ideal web experience. 
+
+It is in fact quite trivial to split up the content into their own respective pages. If you look at the [template repo](https://github.com/edic-nus/advanced), you can see that to create a new page, we can simply just create a new folder and put another `index.html` file inside it.
+
+Take for example the `chart` folder. If you look inside, you can see that there are 2 files:
+- `chart.js`
+- `index.html`
+
+So when you visit the path:
+
+> https://edic-nus.github.io/advanced/chart/
+
+It will render the `index.html` file inside the `chart` folder on your browser. You can try the same thing for `/diagram` and `/3d-render`.
+
+So to summarize, to create a new page for your report. You just simply have to create a new folder and put a `index.html` file inside it. The name of your folder will be the name of your path.
+
+> 

Warning +> +> This should come as something obvious but you should not use a name with a special character (eg. space, tab, etc.) in them, as it might have trouble linking the path correctly. As a standard practice, just use a one word name such as `about` or `diagram`. If you need more than one word, use `-` to connect the words instead: `about-us`. + +## 2. Using `template-page.html` + +Now that you know how creating a new page works, you must be wondering what to put into the `index.html` file. No worry, we have provided you with a template so you can just copy paste everytime you create a new page. You can find it in our demo code under the name `template-page.html`. Let's take a look at what is inside the template and how to use it. + +```html + + + + + + + + Project Title + + + + + + + + + + + + + +

+ Back + + + + + + + +``` + +As you can see, it is quite a short file. For the most parts, you can ignore all of it. There are only 2 things that you should pay attention to, that is: + +1. How to add components that you need +2. How the back button works + +### 2.1. How to add components that you need + +Look at this portion of the code: + +```html + + + + + + +``` + +There are 2 kinds of import that we utilize that is `` and ` +``` + +to import the js files needed to run the javascript for that web page. + +Please note that, you would have to do this for every new `index.html` file you created, as importing on one `index.html` does not get share with other `index.html` files in different folders / paths. + +One of the important thing to understand is how path syntax works to tell the element in HTMl to figure out where your file is located relative to each other. + +- `./` is used to specify looking at the current folder and locate the file. For example: `./components/scroll-to-top/scroll-to-top.css` means to look in the current folder, find `components` folder, go into `components` folder, find `scroll-to-top` folder, go into `scroll-to-top` folder, and find `scroll-to-top.css` file. +- `../` is use to go 1 folder above the current folder. For example, if you are currently in the `scroll-to-top` folder, then `../scroll-to-top` is one folder above / outside of it, that would be the `components` folder. + +I know it could be a bit confusing, but the best way to get used to it is just try to add components yourself to see how the path would work, and if you are stuck you can ask ChatGPT for help in figuring out how to import your files correctly. + +With that out of the way, you should notice by now, that with our current path declaration, our template would not be able to properly import `index.css` file when it is used inside another folder. That is because it used `./index.css`. But when inside another folder, such as `chart`, it actually needs to be `../index.css` instead, because the file `index.css` is in a folder one level above the `chart` folder. So do pay attention to this when trying to import file from different location. + +### 2.2. How the back button works + +Let look at the code: + +```html +Back +``` + +You should have noticed that we used a shoelace button from the introduction to Shoelace in previous chapter. However, you could also just use the default button provided by html, there is no different in functionality. + +You should see that the `href` attribute use the same path syntax that we have discussed above. This is because navigating within a website is very similar to how you navigate between folders. So a `href="../"` just simply mean to go one folder above, or in another words, go back to our main folder that contains the entry `index.html`. + +## 3. How to navigate between pages + +Now that we roughly understand how path syntax works, let looks at how do we provide link from one page to another. If we open up the main entry `index.html` files, you can see the familiar Table of Contents code: + +```html +
+

Table of Contents

+ + + Chart + + 1. Pie and Doughnut Chart + + + 2. Bar Chart + + + 3. Line Chart + + + 4. Scatter Chart + + + + + Interactive diagram + + + + 3D Render + + +
+``` + +What to focus on here is the value we provided to the `href` attribute. Using our previous knowledge regarding path, it should be easy to see that `./chart/` means to go to the `chart` folder or equivalently the `/chart/` path in the url. As long as you understand this concept, the rest is similar to what we have learnt in Chapter 1. To specify a `id` we want to target in another page, we just have to add the `#id` syntax in the url as shown above.