diff --git a/docs/vanilla-javascript/overview.md b/docs/vanilla-javascript/overview.md new file mode 100644 index 00000000000..491f19c9d73 --- /dev/null +++ b/docs/vanilla-javascript/overview.md @@ -0,0 +1,35 @@ +--- +title: 'Ionic Vanilla Javascript Overview' +sidebar_label: Overview +--- + + + Ionic Vanilla JavaScript Overview | Vanilla Javascript Documentation + + + +import DocsCard from '@components/global/DocsCard'; +import DocsCards from '@components/global/DocsCards'; + +`@ionic/core` brings the Ionic Experience to any project — no framework, no CLI. + +## Ionic Framework CDN + +Ionic Framework can be included from a CDN for quick testing in a [Plunker](https://plnkr.co/), [Codepen](https://codepen.io), or any other online code editor! + +It's recommended to use [jsdelivr](https://www.jsdelivr.com/) to access the Framework from a CDN. To get the latest version, add the following inside the `` element in an HTML file, or where external assets are included in the online code editor: + +```html + + + +``` + + The CSS bundle will include all of the Ionic [Global Stylesheets](../layout/global-stylesheets). + + +## Using Components +To use Ionic Components, you can browse our [UI Components Library](../components) and copy the `JavaScript` sample code. This code can then be modified for your purposes. \ No newline at end of file diff --git a/docs/vanilla-javascript/your-first-app.md b/docs/vanilla-javascript/your-first-app.md new file mode 100644 index 00000000000..6bd1a4bcd41 --- /dev/null +++ b/docs/vanilla-javascript/your-first-app.md @@ -0,0 +1,421 @@ +--- +sidebar_label: Build Your First App +--- + +# Your First Ionic App: Vanilla JavaScript + +The great thing about Ionic is that with one codebase, you can build for any platform using just HTML, CSS, and JavaScript. Follow along as we learn the fundamentals of Ionic app development by creating a realistic app step by step. + +Here's the finished app running on all three platforms: + + +## What We'll Build +We'll create a Photo Gallery app that offerrs the ability to take photos with your device's camera and display them in a grid. + +You can find the **complete app code** referenced in this guide [on GitHub](https://github.com/kkindrai/Ionic--VanillaJS-Getting-Started-Application) + +## Download Required Tools +Download and install these right away to ensure an optimal Ionic development experience: + +- **A code editor** for... writing code! We are fans of [Visual Studio Code](https://code.visualstudio.com/). + +## Create Your Working Directory + +Before you start building your app, you'll need to set up a folder where all your project files will live. This includes creating an HTML file and generating the basic structure of a webpage using VS Code. + +### 1. Create a new project folder + +Start by creating a new folder on your computer. You can name it anything you like — for example, `my-ionic-app`. + +To do this: + +- Open your computer’s file manager (Finder on macOS, File Explorer on Windows) +- Navigate to where you want your project to be saved (like your Desktop or Documents folder) +- Right-click and choose **New Folder** +- Name the folder something like `my-ionic-app` + +### 2. Add a blank `index.html` file + +Next, create a new file inside your folder called `index.html`. + +To do this: + +- Open the folder you just created +- Right-click inside the folder and choose **New File** (or **Text Document**, then rename it) +- Name the file `index.html` — make sure the extension is `.html`, not `.txt` + +> **Note:** If you don’t see the file extension, you may need to enable “Show file extensions” in your system settings. + +### 3. Generate the base HTML template + +Now, open the folder in [Visual Studio Code](https://code.visualstudio.com/), and open the `index.html` file. + +In the editor: + +1. Click inside the file +2. Type `!` and press `Tab` +3. VS Code will automatically expand it into a full HTML5 document structure: + +```html + + + + + + Document + + + + + +``` + +> **Tip:** If `! + Tab` doesn’t work, make sure the file is saved as `index.html`, and that your cursor is inside the file. + +## Import Ionic Scripts + +To start using Ionic components in your app, you'll need to include the Ionic JavaScript and CSS files. These are loaded from a CDN (Content Delivery Network) and allow your project to access the full Ionic Core library. + +### Add the Ionic scripts to your HTML file + +Open your `index.html` file and locate the `` section. Inside the ``, directly below the `` tag, paste the following lines: + +```html +<!-- Import Ionic Scripts --> +<script type="module" src="https://cdn.jsdelivr.net/npm/@ionic/core/dist/ionic/ionic.esm.js"></script> +<script nomodule src="https://cdn.jsdelivr.net/npm/@ionic/core/dist/ionic/ionic.js"></script> +<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ionic/core/css/ionic.bundle.css" /> +``` + +After adding the scripts, your file should look like this: + +```html +<!DOCTYPE html> +<html lang="en"> + <head> + <meta charset="UTF-8"> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + <title>Document + + + + + + + + + + +``` + +> **Note:** These scripts load Ionic Core in a way that works with most modern browsers. The `type="module"` version is used for browsers that support JavaScript modules, while the `nomodule` fallback ensures compatibility with older browsers. + + +## Downloading App Specific Resources + +In addition to the Ionic Core scripts, your app will use two custom files: a JavaScript file for functionality and a CSS file for styling. + +### 1. Download the files + +Download each of the following files and save them in the same folder as your `index.html` file: + +- [View `demo.js`](https://raw.githubusercontent.com/kkindrai/Ionic--VanillaJS-Getting-Started-Application/main/demo.js) +- [View `styles.css`](https://raw.githubusercontent.com/kkindrai/Ionic--VanillaJS-Getting-Started-Application/main/styles.css) + +> **Note:** Make sure both files are saved directly inside your project folder (next to `index.html`), not in a subfolder. + +#### `demo.js` (click to expand) + +
+View file contents + +```js title="demo.js" +// Code Sample Modified from Mozilla +// https://developer.mozilla.org/en-US/docs/Web/API/Media_Capture_and_Streams_API/Taking_still_photos + +// Global Variables +const gallery = []; // Array to store captured images +const size = 320; // Viewport Size +let streaming = false; +let canvas = null; +let photoRow = null; +let startButton = null; +let video = null; + + +/** + * Clears the canvas by filling it with a gray color. + * This is used to reset the canvas before capturing a new image. + */ +function clearPhoto() { + const context = canvas.getContext("2d"); + context.fillStyle = "#AAA"; + context.fillRect(0, 0, canvas.width, canvas.height); +} + +/** + * Renders the gallery of captured images. + * It creates a grid layout using ion-col elements for each image. + */ +function renderGallery() { + photoRow.innerHTML = ""; + gallery.forEach((imgUrl) => { + const ionCol = document.createElement("ion-col"); + ionCol.setAttribute("size", "4"); + + const ionImg = document.createElement("ion-img"); + ionImg.setAttribute("src", imgUrl); + ionImg.style.width = "100%"; + ionImg.style.height = "auto"; + ionImg.style.margin = "4px"; + + ionCol.appendChild(ionImg); + photoRow.appendChild(ionCol); + }); +} + + +/** + * Captures a picture from the video stream and adds it to the gallery. + * The picture is centered and cropped to a square based on the video aspect ratio. + */ +function takePicture() { + const context = canvas.getContext("2d"); + if (size) { + canvas.width = size; + canvas.height = size; + + // Center-crop the video to a square + const videoAspect = video.videoWidth / video.videoHeight; + let sx, sy, sWidth, sHeight; + + if (videoAspect > 1) { + // Video is wider than tall + sHeight = video.videoHeight; + sWidth = sHeight; + sx = (video.videoWidth - sWidth) / 2; + sy = 0; + } else { + // Video is taller than wide or square + sWidth = video.videoWidth; + sHeight = sWidth; + sx = 0; + sy = (video.videoHeight - sHeight) / 2; + } + + // Draw the video frame onto the canvas + context.drawImage( + video, + sx, sy, sWidth, sHeight, // source rectangle + 0, 0, size, size // destination rectangle + ); + + // Convert the canvas to a data URL and add it to the gallery + const data = canvas.toDataURL("image/png"); + gallery.push(data); + renderGallery(); + } else { + clearPhoto(); + } +} + +/** + * Initializes the app by setting up the video stream and event listeners. + */ +function startup() { + // Get references to the HTML elements + video = document.getElementById("video"); + canvas = document.getElementById("canvas"); + startButton = document.getElementById("start-button"); + photoRow = document.getElementById("photo-row"); + + // Check if the browser supports the MediaDevices API + navigator.mediaDevices + .getUserMedia({ video: true, audio: false }) + .then((stream) => { + video.srcObject = stream; + video.play(); + }) + .catch((err) => { + console.error(`An error occurred: ${err}`); + }); + + // Set up event listeners for the video element + video.addEventListener( + "canplay", + () => { + if (!streaming) { + video.setAttribute("width", size); + video.setAttribute("height", size); + canvas.setAttribute("width", size); + canvas.setAttribute("height", size); + streaming = true; + } + }, + false, + ); + + // Set up the start button to capture a picture + startButton.addEventListener( + "click", + (ev) => { + takePicture(); + ev.preventDefault(); + }, + false, + ); + clearPhoto(); +} + +// Initialize the app when the window loads +window.addEventListener("load", startup, false); +``` + +
+ +#### `styles.css` (click to expand) + +
+View file contents + +```css title="styles.css" +ion-content { + display: flex; + justify-content: center; + align-items: center; + height: 100%; + min-height: calc(100vh - 23vh); /* Ensure full window height minus nav bar */ +} + +ion-grid { + height: 100%; +} + +ion-row { + min-height: 100%; + height: 100%; +} + +ion-col { + display: flex; + justify-content: center; + align-items: center; + height: 100%; +} + +ion-grid.gallery-scroll ion-col { + height: fit-content; +} + +.gallery-scroll { + overflow-y: auto; + height: 100%; +} + +.video-container { + width: 75%; + aspect-ratio: 1 / 1; + height: auto; + display: flex; + align-items: center; + justify-content: center; + margin: 0 auto; +} + +#video { + width: 100%; + height: auto; + aspect-ratio: 1 / 1; + object-fit: cover; + background: #000; + display: block; + border-radius: 8px; +} + +.fab-inside-video { + margin-top: 75%; + z-index: 2; +} + +.hidden { + display: none; +} +``` + +
+ +### 2. Add local imports to your HTML file + +Once the files are downloaded, import them into your project. Add the following lines directly below the Ionic import scripts inside your ``: + +```html + + + +``` + +Your updated `` section should now look like this: + +```html + + + + Document + + + + + + + + + + +``` + +### 3. Add the hidden canvas + +At the very end of your `` section, just before the closing `` tag, add a hidden canvas element. This will be used later by the camera component: + +```html + + +``` + +This canvas will remain invisible to users but will help process image data behind the scenes. + + +**This is what your `index.html` file should look like at the end of this step:** +```html title="index.html" + + + + + + Document + + + + + + + + + + + + + + + + + +``` + diff --git a/docs/vanilla-javascript/your-first-app/2-using-ionic-components.md b/docs/vanilla-javascript/your-first-app/2-using-ionic-components.md new file mode 100644 index 00000000000..689522d8287 --- /dev/null +++ b/docs/vanilla-javascript/your-first-app/2-using-ionic-components.md @@ -0,0 +1,366 @@ +--- +sidebar_label: Using Iconic Components +--- + +# Using Ionic Components in Vanilla JavaScript + +## Add Ionic Tabs + +Ionic’s `ion-tabs` component lets you build tabbed navigation similar to what you’d find in a mobile music or podcast app. In this section, we’ll add a basic tab layout to your project using just HTML. + +We’ll be using the **Basic Usage** example from the [Tabs component documentation](../../api/tabs), and modifying it slightly to work in our Vanilla JavaScript project. + +--- + +### 1. Insert Tabs Markup + +Copy the following HTML and paste it inside the `` element of your `index.html` file. This creates four tabs: **Listen Now**, **Radio**, **Library**, and **Search**. + +:::note +You only need the HTML portion — you can ignore the `.ts` example shown in the documentation. +::: + +```html + + +
+ + + Listen now + + + +
Listen now content
+ +
+ + + +
+ + + Radio + + + +
Radio content
+ +
+ + + +
+ + + Library + + + +
Library content
+ +
+ + + +
+ + + Search + + + +
Search content
+ +
+ + + + + + Listen Now + + + + + Radio + + + + + Library + + + + + Search + + + +``` + +Our application should now appear something like this: + +![Screenshot of the application at this point in development](https://i.imgur.com/Cf0AcXu.png) + +--- + +### 2. Modify the Radio Elements + +Next, we’ll replace the **Radio** tab with a **Gallery** tab to better suit our photo app. + +Update your HTML by replacing the existing Radio tab markup with this: + +```html + + +
+ + + Gallery + + + +
Gallery content
+ +
+ +``` + +Then, update the corresponding tab button inside the tab bar to: +```html + + + + Gallery + +``` + +Your application should now display **Gallery** in place of **Radio**. +![Screenshot of the application at this point in development](https://i.imgur.com/OGC3nbn.png) + +## Page Layouts + +To build responsive layouts in Ionic, we’ll use the [`ion-grid`](/docs/api/grid), [`ion-row`](/docs/api/row), and [`ion-col`](/docs/api/col) components. These help us structure the content of our app so it displays well across all screen sizes. + +We’ll now update the Gallery tab to include these layout elements. We'll build the structure step by step. + +--- + +### 1. Add `ion-grid` + +The `ion-grid` acts as the main container for rows and columns. It uses a flex-based layout system and supports responsive breakpoints. + +Update your Gallery tab to include a grid inside the ``: + +```html + + + ... + + +``` + +### 2. Add `ion-row` +Inside the grid, we use an `ion-row` to organize horizontal sections. This acts like a flex row and wraps ion-col elements. + +Add a single row within your grid: +```html + + + ... + + +``` + +### 3. Add `ion-col` for Layout Sections +Within each row, use `ion-col` to define individual columns. Columns are responsive by default and will automatically stack on smaller screens. + +For our layout, we’ll use two columns: + +**Camera Column** +```html + + + ... + +``` + +**Gallery Column** +```html + + + ... + +``` + +#### Full Layout Example +Once you’ve added all the elements, your `Gallery` tab should now look like this: +```html + +
+ + + Gallery + + + + + + + + ... + + + + + ... + + + + +
+ +``` + +#### Lets Get Visual +To help understand this concept, below is an image with each of these elements added, with CSS borders around each element: +- Purple: `ion-grid` +- Red: `ion-row` +- Blue: `ion-col` +![Demonstration of Element Borders](https://i.imgur.com/bqOsPpd.png) + +## Smile! Adding a Camera + +Let’s start setting up the **Camera Column** of our app. This is where we’ll display a live video preview from your device’s camera and eventually capture photos. + +### 1. Create a Camera Frame + +We’ll begin by creating a wrapper `
` that will hold our camera feed. Inside that wrapper, we’ll add a `