diff --git a/README.md b/README.md index a9ba8fb..a4f0764 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,10 @@ # Docs Template -[![Netlify Status](https://api.netlify.com/api/v1/badges/7126a0d2-2cd2-48ab-908e-3bf66217ef33/deploy-status)](https://app.netlify.com/sites/docs-template-main/deploys) +[![Netlify Status](https://api.netlify.com/api/v1/badges/56666731-326a-46c0-b240-247a100d1fa0/deploy-status)](https://app.netlify.com/sites/c4gt-docs/deploys) --- - [Contributing Guide](./CONTRIBUTING.md) :flashlight: +### Steps to run +- `npm install` +- `yarn start` + diff --git a/docs/.assets/C4GT-Architecture.png b/docs/.assets/C4GT-Architecture.png new file mode 100644 index 0000000..7d5777f Binary files /dev/null and b/docs/.assets/C4GT-Architecture.png differ diff --git a/docs/.assets/C4GT-Community.jpg b/docs/.assets/C4GT-Community.jpg new file mode 100644 index 0000000..4cc2d79 Binary files /dev/null and b/docs/.assets/C4GT-Community.jpg differ diff --git a/docs/.assets/C4GT-Onboarding.jpg b/docs/.assets/C4GT-Onboarding.jpg new file mode 100644 index 0000000..840f8ab Binary files /dev/null and b/docs/.assets/C4GT-Onboarding.jpg differ diff --git a/docs/.assets/zoomable.jpg b/docs/.assets/zoomable.jpg deleted file mode 100644 index 8bd4ef0..0000000 Binary files a/docs/.assets/zoomable.jpg and /dev/null differ diff --git a/docs/index.md b/docs/index.md index 773a778..3c53da5 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,70 +1,57 @@ --- -title: Samagra Documentation -sidebar_label: Overview +title: C4GT +sidebar_label: Introduction slug: / -hide_table_of_contents: true -demoUrl: https://docs-template-main.vercel.app/ -demoSourceUrl: https://github.com/Samagra-Development/docs-template +id: index --- -import DocsCard from '@components/global/DocsCard'; -import DocsCards from '@components/global/DocsCards'; - - Samagra Docs + C4GT Docs - - + - - - - - - - - -

Step-by-step guides to setting up your system and installing the framework.

-
- - - -
- ## Overview -Your project's overview - -![Sample zoomable image](.assets/zoomable.jpg) -A sample zoomable image ^ [Source](https://cdn.esahubble.org/archives/images/large/heic2017a.jpg) - -### Sub Heading -1 -"Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum." - - -### Sub Heading -2 - -"Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum." - - -## Appflow - -Your App Flow - -## Ecosystem - -Your App's Ecosystem - -### Join the Community - -There are millions of Ionic developers in over 200 countries worldwide. Here are some ways to join: - - -## License - -Your Project license +Launched in 2022, C4GT is a one-of-its-kind initiative that aims to build a community of communities +around Digital Public Goods (DPG), Digital Public Infrastructure (DPI) & Tech for Good products. +Through various efforts, it aims to encourage ongoing contributions and strengthen collaboration +between DPG/DPI builders, adopters, and contributors (students or working professionals). The +initiative works towards facilitating long-term collaboration and innovation within the fast +evolving DPGs/DPI & Tech for Good ecosystem, enhancing the efficiency and quality of contributions, +and aligning the incentives for both organizations and contributors. +More about C4GT here: https://codeforgovtech.in/ + +## This Website Audience + +This website tries to document the tech systems powering the C4GT initiatives. If you are a product +manager, community manager or a software engineer, wanting to understand how to build a system that +integrates multiple tools used by open source developers together, this is the right place for you. + +## Architecture + +![C4GT Architecture](.assets/C4GT-Architecture.png) +[Source](https://drive.google.com/file/d/1hzB6voh36gB87t9LrPLWLlBboRl2bziM/view?usp=sharing) + +* **GitHub and Discord** - We listen to events from external systems like GitHub and Discord. These + could be joining a discord server, sending a message in a discord channel, joining a discord + channel, logging into a github app, commenting on a github issue, raising a PR and so on. Both + these external systems are commonly used in the tech ecosystem to manage open source software and + contributions. +* **DMP Cron** - We run a + yearly [Dedicated Mentorship Program (DMP)](https://codeforgovtech.in/dedicated_mentoring_program/) + initiative. This module pulls data from Github related to that. +* **Server** - This module is responsible to power authentication across GitHub and Discord for our + members. It also manager + the [Open Community](https://codeforgovtech.in/community-program-projects/) tickets raised & + closed in the community. +* **C4GT website** - The website uses elements from server to render itself. +* **Discord Bot** - The custom flows of [our discord server](https://discord.gg/V3Aa9qk4Wt) are + controlled by this module. A major flow is connecting discord users to github users. +* **DB** - All modules have a single source of truth and database. +* **DMP API** - This flask module powers the DMP docs website APIs. +* **DMP Docs** - This docusaurus module powers https://milestones.c4gt.samagra.io/. \ No newline at end of file diff --git a/docs/initiatives/community.md b/docs/initiatives/community.md new file mode 100644 index 0000000..792cccb --- /dev/null +++ b/docs/initiatives/community.md @@ -0,0 +1,44 @@ +--- +title: Community Projects +--- + + + C4GT - Community Projects + + +## Goal +The C4GT community forms the core of the C4GT program, serving as a dynamic bridge between contributors and organizations. It facilitates collaboration by presenting problem statements as actionable tickets and enables seamless end-to-end tracking and management using C4GT's proprietary technology modules. +## Product +### Exploring Contribution Opportunities: + + +Users visit the C4GT website to discover opportunities to contribute and they join the C4GT community through an onboarding process. + +### Community Engagement: + + +After joining the community server, users connect with participating organizations and fellow contributors for collaboration and support in achieving ticket milestones. This fosters a collaborative environment for learning and growth. + +### Ticket Tracking: + +Users explore available tickets on the website and on GitHub. The C4GT community bot collects all relevant ticket-related data including ticket content, status updates (open, in-progress, closed), comments and discussions on tickets, timestamps of activities, Pull Requests (PRs) raised and merged, etc. + +### Role Assignment: + + +Based on the data collected by the bot, contributors are assigned specific roles to reflect their progress and contributions. + +### Ticket Closure and Points Allocation: + + +When contributors submit solutions, ticket owners review and close the tickets upon acceptance. Points are then awarded to contributors based on the difficulty level of the tickets. + +### Leaderboard and Recognition: + +Points are reflected on a leaderboard displayed on the C4GT website and contributors are ranked based on their accumulated points, providing recognition for their efforts. + +## Tech + + +![C4GT Community flow](../.assets/C4GT-Community.jpg) +[Source](https://drive.google.com/file/d/1hzB6voh36gB87t9LrPLWLlBboRl2bziM/view?usp=sharing) diff --git a/docs/initiatives/dmp.md b/docs/initiatives/dmp.md new file mode 100644 index 0000000..13f5c65 --- /dev/null +++ b/docs/initiatives/dmp.md @@ -0,0 +1,82 @@ +--- +title: Dedicated Mentoring Program +--- + + + C4GT - Dedicated Mentoring Program + + +## Goal + +Code for GovTech (C4GT) has conducted multiple rounds of Dedicated Mentoring Program (DMP) since +2022 where selected students and working professionals get an opportunity to contribute to critical +tech building blocks with the guidance of a dedicated mentor. They work closely with DPG builder and +adopter organizations on real world problem statements that have a population-scale social impact. + +As part of the initiative, DMP is an experiential learning opportunity for technology enthusiasts +across the globe who are passionate about technology. Participants will solve population-scale +problems, work on live open-source projects and drive impact. + +As part of DMP 2024, C4GT has launched the product usability & design track that aims to support +organizations by articulating design and product usability gaps and developing people-centered +solutions. Projects under this track will focus on improving usability and accessibility of the +products and is open for applicants currently enrolled in design or research programs or possess 0-2 +years of professional experience. + +## Product + +In DMP 2023, contributors and mentors tracked project completion using a Vercel app and dedicated a significant amount of time to manually update markdown files to showcase project completion. This meant that progress tracking was not always up-to-date as and when required, and C4GT organizers were not able to intervene on time to resolve project bottlenecks. And in DMP 2024, with the project count increasing exponentially, the need for a smoother, more efficient tracking system had become paramount. + +The revamped C4GT DMP CMS aimed to solve this by providing a platform for monitoring the progress of such open-source projects assigned to contributors during the Dedicated Mentoring Program(DMP) period of 3 months. The revamped Vercel app enabled easier and more efficient collaboration between contributors and mentors by linking to GitHub directly, while providing visibility to other relevant stakeholders. And a new second module, the dashboard, allowed administrators/organizers to set certain criterion and be flagged in time to swiftly resolve bottlenecks. + +## Tech + +### Project Selection + +Each organization submits project ideas through a Google Form. The information is vet by the C4GT +program team and shortlisted problem statement are sent for applications. + +### Candidate Selection + +Candidate selection is done through the [Unstop +platform](https://unstop.com/competitions/dedicated-mentoring-program-dmp-2024-code-for-govtech-932803). + +### Contribution management + +Once the candidate is selected for a problem statement and start contributing, the DMP Management +System comes into the picture. The DMP management system consists of a DMP documentation frontend +which gets updates from each project via github comments. + +Flow: + +1. DMP tickets are added into the database +2. We lookup comments for each ticket every few hours +3. We filter the comment by the mentor for `Weekly Goals` +4. We filter the comment by the contributor for `Weekly learnings` +5. We parse the ticket contents and display onto the frontend. + +Modules: +* DMP Cron +* DMP API +* DMP FE + +#### DMP Cron + +This flask app runs a cron job at periodic intervals. This job pulls all the current DMP tickets, +loops through their comments and saves the relevant information into our database. + +Repo: https://github.com/Code4GovTech/DMP-CMS-Backend-CRON + +#### DMP APIs + +This flask based API system reads information from our database and formats it in a way expected by +the FE. + +Repo: https://github.com/Code4GovTech/DMP-CMS-Backend-API + +#### DMP FE + +This docusaurus website contains a custom react page to load updates related to the DMP projects via +the DMP API. + +Repo: https://github.com/Code4GovTech/dmp-documentation diff --git a/docs/initiatives/onboarding.md b/docs/initiatives/onboarding.md new file mode 100644 index 0000000..8ae34aa --- /dev/null +++ b/docs/initiatives/onboarding.md @@ -0,0 +1,56 @@ +--- +title: Onboarding +--- + + + C4GT - Onboarding + + +## Goal + +The C4GT onboarding flow provides a seamless experience for contributors joining the C4GT community, +enabling personalized interactions that enhance their journey within the community + +## Product + +### Discovering C4GT: + +The user learns about C4GT through various channels (social media, word-of-mouth, or invitations) +and accesses a shared link to join the community. + +### Joining the Discord Server: + +The user is redirected to C4GT’s Discord server, where they begin the onboarding process. +Upon joining, the user is prompted to answer a few introductory questions, such as gender, location, +and educational institution. + +### Exploring the Server Guide: + +After completing the initial questions, the user is guided to the Server Guide channel. +This channel provides an overview of the onboarding steps, community guidelines, and a snapshot of +C4GT initiatives and opportunities. + +### Linking GitHub with Discord: + +To streamline contributions, the user is prompted to link their GitHub account with their Discord +profile using C4GT’s dedicated Discord bot. + +### Introducing Themselves: + +The user is encouraged to introduce themselves to the community by sharing details about their +interests, skills, and goals. +During this step, they also acknowledge and accept the community’s Code of Conduct. + +### Completing Onboarding: + +Once all steps are completed, the user is fully onboarded and they can now start contributing to +projects, participating in discussions, and exploring community initiatives. + +## Tech + +Open source contributions primarily happen over Github. Our tech system allows us to connect +accounts across Discord (our community management platform) & GitHub. To be able to link both the +platforms together for a particular user we have built the onboarding flow. + +![C4GT User Onboarding flow](../.assets/C4GT-Onboarding.jpg) +[Source](https://drive.google.com/file/d/1hzB6voh36gB87t9LrPLWLlBboRl2bziM/view?usp=sharing) diff --git a/docs/initiatives/website.md b/docs/initiatives/website.md new file mode 100644 index 0000000..e2d61b2 --- /dev/null +++ b/docs/initiatives/website.md @@ -0,0 +1,21 @@ +--- +title: Website +--- + + + C4GT - Website + + +## Goal +The C4GT website is designed to enable C4GT as an initiative, fostering community-driven innovation and collaboration. + + +## Product + +Using the website, users can: +1. Learn about the initiative's purpose, vision, and impact. +2. Join the C4GT community of contributors and mentors +3. Discover and explore a curated list of projects, categorized by domains, ownership, difficulty levels, and points. +4. Track their progress and engagement through a leaderboard, showcasing contributor and mentor rankings within the community. + +## Tech diff --git a/docs/intro/cli.md b/docs/intro/cli.md deleted file mode 100644 index 0ad12e8..0000000 --- a/docs/intro/cli.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: Installing Dependencies -sidebar_label: Dependencies Installation ---- - - - - - How to Install The Project Dependencies - - - -Description... - - - -## Install Dependencies - -Before proceeding, make sure your computer has [Node.js](../reference/glossary.md#node) installed. See [these instructions](environment.md) to set up an environment for Ionic. - -Install the Dependencies CLI with npm: - -```shell -installation command -``` - -If there was a previous installation of the Ionic CLI, it will need to be uninstalled due to a change in package name. - -```shell -$ installation command - - -``` - -:::note -add your note here, if there are any -::: - - -## Run the App - - - -```shell -$ cd myApp -$ your run command -``` - -There are a number of other ways to run an app, it's recommended to start with this workflow. diff --git a/docs/intro/environment.md b/docs/intro/environment.md deleted file mode 100644 index 41af588..0000000 --- a/docs/intro/environment.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: Environment Setup ---- - - - Environment Setup | Node & NPM Environment for Ionic App Setup - - - -To get started with Ionic Framework, the only requirement is a [Node & npm](#node--npm) environment. - -Of course, a code editor is also required. [Visual Studio Code](https://code.visualstudio.com/) is recommended. Visual Studio Code is a free, batteries-included text editor made by Microsoft. - -## Terminal - - -In general, we recommend using the built-in terminals. Many third-party terminals work well with Ionic, but may not be supported. - -- For Windows, **Command Prompt** and **PowerShell** are supported. WSL is known to work with Ionic, but may not be supported. -- For macOS, the built-in **Terminal** app is supported. - -Git Bash (from git-scm.com) does not support TTY interactivity and is **not supported** by Ionic. - -## Node & npm - -Almost all tooling for modern JavaScript projects is based in [Node.js](../reference/glossary.md#node). The [download page](https://nodejs.org/en/download/) has prebuilt installation packages for all platforms. We recommend selecting the LTS version to ensure best compatibility. - -Node is bundled with [npm](../reference/glossary.md#npm), the package manager for JavaScript. - -To verify the installation, open a new terminal window and run: - -```shell -$ node --version -$ npm --version -``` - - - -## Git - - -Git is often accompanied by a Git Host, such as [GitHub](https://github.com/), in which case additional setup is required. Follow the tutorial from the Git Host's documentation to set up Git: - -- GitHub: [Set up Git](https://help.github.com/en/articles/set-up-git) -- GitLab: [Installing Git](https://docs.gitlab.com/ee/topics/git/how_to_install_git) -- Bitbucket: [Install Git](https://www.atlassian.com/git/tutorials/install-git) - -Otherwise, follow the [official installation instructions](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git). The command-line utility can be downloaded from the [download page](https://git-scm.com/downloads). - -To verify the installation, open a new terminal window and run: - -```shell -git --version -``` - -### Git GUI - -Git is a command-line utility, but there are many [GUI clients](https://git-scm.com/downloads/guis/) available. [GitHub Desktop](https://desktop.github.com/) is recommended, and works well with GitHub. diff --git a/docs/reference/glossary.md b/docs/reference/glossary.md deleted file mode 100644 index c579ce6..0000000 --- a/docs/reference/glossary.md +++ /dev/null @@ -1,552 +0,0 @@ ---- -title: Glossary ---- - - - API Glossary: Terminology and Definitions | Ionic Framework - - - -
- -
- -

Android SDK

-
-

- The{' '} - - Android SDK - {' '} - is a software development kit built for developers building for Google's Android Platform. It includes tools for - building, testing, and debugging Android applications. -

-
- -
- -

Android Studio

-
-

- - Android Studio - {' '} - is the official Integrated Development Environment (IDE) for Native Android app development. -

-
- -
- -

Autoprefixer

-
-

- - Autoprefixer - {' '} - is a tool that adds vendor-specific-prefixes to hand-written Sass/CSS code. This ensures that standardized CSS rules - you write will be applied across all supporting browsers. For example, instead of having to know every flexbox - syntax used by various browsers, autoprefixer allows you to just write display: flex; and it'll - automatically plug in the correct CSS. -

-
- -
- -

Bundling

-
-

- Bundling is the process of taking an app's dependencies (code you've written plus any npm modules installed) and - compiling/transpiling them down to one single file. -

-
- -
- -

Capacitor

-
-

- - Capacitor - {' '} - is an open source cross-platform app runtime that allows web-based apps to run natively on iOS, Android, Electron, - and the web. It's helpful to refer to these apps "Native Progressive Web Apps" and they represent the next evolution - beyond the traditional Hybrid app mentality. Capacitor was created and is actively developed/supported by Ionic, the - company. -

-
- -
- -

CLI

-
-

- A CLI, or Command-Line Interface, is a text-based interface for - interacting with a program. The common command-line app for a Mac user is the Terminal app, and Windows users often - use Command Prompt. The Ionic community often uses this term to refer to{' '} - Ionic's CLI. Ionic's CLI can be used for a number of things, - such as creating production builds of an app, running the development server, and accessing{' '} - - Ionic commercial services - - . -

-
- -
- -

CommonJS

-
-

- - CommonJS - {' '} - is a group that defines standard formats for JavaScript APIs. They have defined standards for JavaScript modules and - packages. -

-
- -
- -

Cordova

-
-

- - Apache Cordova - {' '} - is an open source mobile application development framework that transforms standard HTML/CSS/JS into full-fledged - native apps. It provides a JavaScript API for accessing native device functionality, such as the camera or - accelerometer. Cordova contains the necessary build tools for packaging webapps for iOS, Android, and Windows Phone. -

-
- -
- -

CORS

-
-

- - CORS - {' '} - (Cross-Origin Resource Sharing) is a mechanism for servers to control client access to web assets. See the{' '} - CORS FAQs for more information. -

-
- -
- -

CSS Variables

-
-

- You may be familiar with variables from Sass.{' '} - - CSS Variables - {' '} - enable the same functionality but are built into the browser. CSS Variables are available in all evergreen browsers. -

-
- -
- -

Decorators

-
-

- Decorators are expressions that return a function. They allow you to take an existing function, and extend its - behavior. With TypeScript, you can also decorate classes and parameters. When you decorate a{' '} - class, you are wrapping and extending the behavior of its constructor. In other words, the - decorator will add some functionality when the constructor is called, and will then return the original constructor. - When you decorate a parameter, you are wrapping the argument that gets passed in for that - parameter. The decorator will add functionality when an argument is passed to the method, and then return the - original argument. -

-
- -
- -

ES5

-
-

- ES5 refers to EcmaScript 5th Edition. A simple way to put it is that ES5 is the version of JavaScript which - developers are most familiar with today. -

-
- -
- -

ES2015/ES6

-
-

- A wide range of new features were introduced in this version of JavaScript, including classes, modules, iterators, - and promises. Evergreen browsers (Chrome, Safari, Firefox and Edge) have full support for ES6, but to use ES6 - features in older browsers, tools such as Babel and TypeScript have - to transpile ES6 code down to ES5. -

-
- -
- -

ES2016/ES7

-
-

- This version of JavaScript added a number of new features to the language, including Array.includes and - the exponentiation operator. This version of JavaScript is fully supported by all evergreen browsers (Chrome, - Safari, Firefox and Edge) -

-
- -
- -

ES2017/ES8

-
-

- This version of JavaScript is the latest standard. It is currently in the final stage before becoming the new - official standard. This spec includes Async/Await (already in all evergreen browsers) and shared memory/atomics. -

-
- -
- -

Genymotion

-
-

- Genymotion is a third-party Android emulator. It is extremely fast, and is useful for quickly testing your app on - Android. Check out our resource section on Genymotion for - more info. -

-
- -
- -

Git

-
-

- - Git - {' '} - is a distributed version control system for managing code. It allows development teams to contribute code to the - same project without causing code conflicts. -

-
- -
- -

Gulp

-
-

- - Gulp - {' '} - is a tool for running tasks which can be used to build your app. Common build tasks include transpiling{' '} - ES6 to ES5, turning Sass into CSS, minifying code, - and concatenating files. -

-
- -
- -

ES Modules

-
-

- - ES Modules - {' '} - brings the concept of modules natively to JavaScript. With modules, classes and variables are no longer in the - global scope and have to be explicitly imported into your project to be used. This makes it much easier to - understand where your code is coming from and increases modularity and compartmentalization of functionality. -

-
- -
- -

Ionicons

-
-

- - Ionicons - {' '} - is an open-source icon set used and created by Ionic. It includes 1:1 iOS and Material Design icons, as well as - commonly used social/application icons. Ionicons is included by default in Ionic distributions, but they can also be - used in any project. -

-
- -
- -

Karma

-
-

- - Karma - {' '} - is a test runner that will run an app's test inside a real browser. It executes test cases, written in any testing - framework, in a real browser. Karma was originally written for use with Angular 1. -

-
- -
- -

Module

-
-

- Modules in JavaScript are small, independent, and reusable pieces or code that are isolated from one another and the - Global scope. -

-
- -
- -

Monorepo

-
-

- A monorepo is a single git repository with multiple projects. Advantages include simpler - organization, shared tooling and dependencies, and better collaboration with teammates. -

-
- -
- -

Live Reload

-
-

- Live Reload (or live-reload) is a tool that automatically reloads the browser or{' '} - Web View when it detects changes in your app. In some cases, it can replace - parts of your app without having to reload the entire window. See the{' '} - Live Reload docs for more information. -

-
- -
- -

Node

-
-

- - Node - {' '} - is a runtime environment that allows JavaScript to be written on the server-side. In addition to being used for web - services, node is often used to build developer tools, such as the Ionic CLI. -

-
- -
- -

npm

-
-

- - npm - {' '} - is the package manager for node. It allows developers to install, share, and package node - modules. Ionic can be installed with npm, along with a number of its dependencies. -

-
- -
- -

Observable

-
-

- An observable is an object that emits events (or notifications). An observer is an object that listens for these - events, and does something when an event is received. Together, they create a pattern that can be used for - programming asynchronously. -

-
- -
- -

Package ID

-
-

- Referred to by Apple as Bundle ID and by Android as Application ID, the{' '} - Package ID is used for identifying apps published to the App Store/Play Store. It is a string - formatted in{' '} - - reverse-DNS notation - - . -

-
- -
- -

Polyfill

-
-

- A{' '} - - polyfill - {' '} - is a bit of code that adds functionality to the browser and normalizes browser differences. This is similar to a{' '} - shim, but where a shim has it's own API, a polyfill let's the expect API of the browser be used. -

-
- -
- -

Protractor

-
-

- - Protractor - {' '} - is a testing framework written for and by the Angular team. Protractor can be used with test runners, like Karma, - for end-to-end testing. Test runners allow you to quickly and programmatically verify code quality. -

-
- -
- -

Sass

-
-

- Sass is a stylesheet language that compiles to CSS and is used by Ionic. Sass is like CSS, but with extra features - such as{' '} - - variables - - , - mixins - , and - loops - . -

-
- -
- -

Scoped Encapsulation

-
-

- A component that uses scoped encapsulation will automatically scope its CSS by appending each of the styles with a - data attribute at run time. Overriding scoped selectors in CSS requires a{' '} - - higher specificity - {' '} - selector. Scoped components can also be styled using{' '} - - CSS Custom Properties - - . -

-
- -
- -

Shadow DOM

-
-

- - Shadow DOM - {' '} - is a native browser solution for DOM and style encapsulation of a component. It shields the component from its - surrounding environment. To externally style internal elements of a Shadow DOM component you must use{' '} - - CSS Custom Properties - {' '} - or{' '} - - CSS Shadow Parts - - . -

-
- -
- -

Shim

-
-

- A shim is a piece of code that normalizes an APIs across browsers. A shim can have it's own API that hides the - browser specific implementation from the end user. -

-
- -
- -

Transpiler

-
-

- Transpilation is the process of converting code from one language to another language prior to execution. Typically, - a transpiler will convert a high-level language to another high-level language. The most common type of{' '} - transpilation in Ionic Framework is converting ES2015/ES6 ( - TypeScript) to ES5 (traditional JavaScript). -

-
- -
- -

TypeScript

-
-

- - TypeScript - {' '} - is a superset of JavaScript, which means it gives you JavaScript, along with a number of extra features such as{' '} - - type declarations - {' '} - and{' '} - - interfaces - - . Although Ionic is built with TypeScript, using it to build an Ionic app is completely optional. -

-
- -
- -

Unit Tests

-
-

- Unit Tests and unit testing are a way to test small pieces of code to see if they behave as expected. Unit testing - frameworks include Jasmine, Mocha, QUnit, and many others. -

-
- -
- -

Webpack

-
-

- - Webpack - {' '} - bundles together JavaScript modules and other assets. It can be used to create single or multiple "chunks" that are - only loaded when needed. Webpack can be used to take many files and dependencies and bundle them into one file, or - other types. -

-
- -
- -

Web Standards

-
-

- The{' '} - - World Wide Web Consortium - {' '} - (W3C) is the standards organization for the Web. Together, industry leaders and the public work together to develop{' '} - - web standards - - , which are a set of protocols, specifications, and technologies that define the Web Platform. -

-
- -
- -

Xcode

-
-

- - Xcode - {' '} - is an Apple IDE (integrated development environment) for software development on Apple operating systems (macOS, - iOS, watchOS and tvOS), with extensions available for other languages and platforms. -

-
- -
\ No newline at end of file diff --git a/docs/updating/4-0.md b/docs/updating/4-0.md deleted file mode 100644 index db354f1..0000000 --- a/docs/updating/4-0.md +++ /dev/null @@ -1,282 +0,0 @@ ---- -title: Updating to v4 ---- - -# Updating to Ionic 4 - -## Updating from Ionic 3 to 4 - -:::note -This guide assumes that you have already updated your app to the latest version of Ionic 3. If you are using Ionic 1 or 2, Make sure to follow the [Updating from Ionic 1 to 4 Guide](#updating-from-ionic-1-to-4) instead. -::: - -:::info Breaking Changes -For a **complete list of breaking changes** from Ionic 3 to Ionic 4, please refer to [the breaking changes document](https://github.com/ionic-team/ionic-framework/blob/main/BREAKING_ARCHIVE/v4.md) in the Ionic Framework repository. -::: - -We suggest the following general process when migrating an existing application from Ionic 3 to 4: - -1. Generate a new project using the `blank` starter (see [Starting an App](../developing/starting.md)) -1. Copy any Angular services from `src/providers` to `src/app/services` - - Services should include `{ providedIn: 'root' }` in the `@Injectable()` decorator. For details, please see Angular [provider docs](https://angular.io/guide/providers). -1. Copy the app's other root-level items (pipes, components, etc) keeping in mind that the directory structure changes from `src/components` to `src/app/components`, etc. -1. Copy global Sass styling from `src/app/app.scss` to `src/global.scss` -1. Copy the rest of the application, page by page or feature by feature, keeping the following items in mind: - - Emulated Shadow DOM is turned on by default - - Page/component Sass should no longer be wrapped in the page/component tag and should use Angular's [`styleUrls`](https://angular.io/api/core/Component#styleUrls) option of the `@Component` decorator - - RxJS has been updated from v5 to v6 (see [RxJS Changes](#rxjs-changes)) - - Certain lifecycle hooks should be replaced by Angular's hooks (see [Lifecycle Events](#lifecycle-events)) - - Markup changes may be required (migration tool available, see [Markup Changes](#markup-changes)) - -In many cases, using the Ionic CLI to generate a new object and then copying the code also works very well. For example: `ionic g service weather` will create a shell `Weather` service and test. The code can then be copied from the older project with minor modifications as needed. This helps to ensure the proper structure is followed. This also generates shells for unit tests. - -### Changes in Package Name - -In Ionic 4, the package name is `@ionic/angular`. Uninstall Ionic 3 and install Ionic 4 using the new package name: - -```shell -$ npm uninstall ionic-angular -$ npm install @ionic/angular@v4-lts -``` - -While migrating an app, update the imports from `ionic-angular` to `@ionic/angular`. - -### Project structure - -One of the major changes between an Ionic 3 app and an Ionic 4 app is the overall project layout and structure. In v3, Ionic apps had a custom convention for how an app should be set up and what that folder structure should look like. In v4, this has been changed to follow the recommended setup of each supported framework. - -For example, if an app is using Angular, that project structure will be exactly what an Angular CLI app would be. This change, while not too difficult to accommodate, helps to keep common patterns and documentation consistent. - -````mdx-code-block - - - -```bash -src/ -├── app/ -│   ├── about/ -│   ├── home/ -│   ├── app-routing.module.ts -│   ├── app.component.html -│   ├── app.component.spec.ts -│   ├── app.component.ts -│   └── app.module.ts -├── assets/ -├── environments/ -├── theme/ -├── global.scss -├── index.html -├── karma.conf.js -├── main.ts -├── polyfills.ts -├── test.ts -├── tsconfig.app.json -└── tsconfig.spec.json -.gitignore -angular.json -ionic.config.json -package.json -tsconfig.json -tslint.json -``` - - - - -```bash -src/ -├── app/ -│   ├── app.component.html -│   ├── app.html -│   ├── app.module.ts -│   ├── app.scss -│   └── main.ts -├── assets/ -├── pages/ -│   ├── about/ -│   ├── home/ -├── theme/ -├── index.html -├── manifest.json -└── service-worker.js -.gitignore -ionic.config.json -package.json -tsconfig.json -tslint.json -``` - - - -```` - -The above comparison is an example of a v4 app's project structure. For developers with experience in a vanilla Angular project, this should feel really familiar. - -There is a `src/` directory that acts as the home for the app. This includes the `index.html`, any assets, environment configuration, and any app-specific config files. - -While migrating an app to take advantage of this new layout, it is suggested that a new project "base" is made with the CLI. Then, with the new project layout, migrate the features of the app piece by piece. Pages/components/etc. should be moved into the `src/app/` folder. - -Ensure your Ionic configuration file has the appropriate `type`. The project type for v3 is `ionic-angular`. The project type for v4 is `angular`. If this value is incorrect, the CLI may invoke the incorrect build scripts. - -See the following `ionic.config.json` as an example: - -```json -{ - "name": "my-app", - "type": "angular" -} -``` - -### RxJS Changes - -Between V3 and V4, RxJS was updated to version 6. This changes many of the import paths of operators and core RxJS functions. Please see the RxJS Migration Guide for details. - -### Lifecycle Events - -With V4, we're now able to utilize the typical events provided by [Angular](https://angular.io/guide/lifecycle-hooks). But for certain cases, you might want to have access to the events fired when a component has finished animating during its route change. In this case, the `ionViewWillEnter`, `ionViewDidEnter`, `ionViewWillLeave`, and `ionViewDidLeave` have been ported over from V3. Use these events to coordinate actions with Ionic's own animations system. - -Older events like `ionViewDidLoad`, `ionViewCanLeave`, and `ionViewCanEnter` have been removed, and the proper Angular alternatives should be used. - -For more details, check out the [router-outlet docs](../api/router-outlet.md) - -### Overlay Components - -In prior versions of Ionic, overlay components such as Loading, Toast, or Alert were created synchronously. In Ionic v4, these components are all created asynchronously. As a result of this, the API is now promise-based. - -```tsx -// v3 -showAlert() { - const alert = this.alertCtrl.create({ - message: "Hello There", - subHeader: "I'm a subheader" - }); - - alert.present(); -} -``` - -In v4, promises are used: - -```tsx -showAlert() { - this.alertCtrl.create({ - message: "Hello There", - subHeader: "I'm a subheader" - }).then(alert => alert.present()); -} - -// Or using async/await - -async showAlert() { - const alert = await this.alertCtrl.create({ - message: "Hello There", - subHeader: "I'm a subheader" - }); - - await alert.present(); -} -``` - -### Navigation - -In V4, navigation received the most changes. Now, instead of using Ionic's own `NavController`, we integrate with the official Angular Router. This not only provides a consistent routing experience across apps, but is much more dependable. The Angular team has an excellent guide on their docs site that covers the Router in great detail. - -To provide the platform-specific animations that users are used to, we have created `ion-router-outlet` for Angular Apps. This behaves in a similar manner to Angular's `router-outlet` but provides a stack-based navigation (tabs) and animations. - -For a detailed explanation in navigation works in a V4 project, check out the [Angular navigation guide](../angular/navigation.md). - -### Lazy Loading - -Since Navigation has changed, the mechanism for lazy loading has also changed in V4. - -In v3, a typical lazy loading setup worked like this: - -```tsx -// home.page.ts -@IonicPage({ - segment: 'home' -}) -@Component({ ... }) -export class HomePage {} - -// home.module.ts -@NgModule({ - declarations: [HomePage], - imports: [IonicPageModule.forChild(HomePage)] -}) -export class HomePageModule {} -``` - -However, in v4, lazy loading is done via the `loadChildren` method of the Angular router: - -```tsx -// home.module.ts -@NgModule({ - imports: [IonicModule, RouterModule.forChild([{ path: '', component: HomePage }])], - declarations: [HomePage], -}) -export class HomePageModule {} - -// app.module.ts -@NgModule({ - declarations: [AppComponent], - imports: [ - BrowserModule, - IonicModule.forRoot(), - RouterModule.forRoot([ - { path: 'home', loadChildren: './pages/home/home.module#HomePageModule' }, - { path: '', redirectTo: 'home', pathMatch: 'full' }, - ]), - ], - bootstrap: [AppComponent], -}) -export class AppModule {} -``` - -For a detailed explanation of lazy loading in V4 project, check out the [Angular navigation guide](../angular/navigation.md#lazy-loading-routes). - -### Markup Changes - -Since v4 moved to Custom Elements, there's been a significant change to the markup for each component. These changes have all been made to follow the Custom Elements spec, and have been documented in a dedicated file on GitHub. - -To help with these markup changes, we've released a TSLint-based Migration Tool, which detects issues and can even fix some of them automatically. - -## Updating from Ionic 1 to 4 - -### Ionic 1 to Ionic 4: What’s Involved? - -Migrating from Ionic 1 to Ionic 4 involves moving from AngularJS (aka Angular 1) to Angular 7+. There are many architectural differences between these versions, so some of the app code will have to be rewritten. The amount of work involved depends on the complexity and size of your app. - -One upside is that for the most part, the Ionic UI components you know and love from V1 haven’t changed much. - -Here are some considerations to review before beginning the upgrade: - -- **App complexity**: Naturally, the larger and more complex the app is, the longer it will take to migrate. -- **Framework support**: In 2019, Ionic will release full support for React. You can also use Ionic Framework components [without a framework](../intro/cdn.md). Since these are not production-ready yet, we recommend sticking with Angular or waiting until the other framework support is available. -- **Budget and team makeup**: The length of a migration project will vary based on the size of your team, the complexity of the app, and the amount of time allotted to make the transition. - -### Suggested Strategy - -Once your development team has identified a good time frame for beginning the migration, Ionic recommends feature-freezing the Ionic 1 application and getting the code in order: Fix any major bugs, eliminate tech debt, and reorganize as you see fit. Then, identify which features to migrate over and which to abandon. - -Once the Ionic 1 app is stable, create a new Ionic 4 project. The majority of the dev team’s attention should be given to the new project; only bugs should be fixed in the Ionic 1 app to ensure that the transition happens as quickly and smoothly as possible. - -Once the team is comfortable that the Ionic 4 app has become stable and has fulfilled a core set of features, you can then shut down the Ionic 1 app. - -### Moving From AngularJS to Angular - -Please reference official [Angular upgrade guide](https://angular.io/guide/upgrade) information. - -### Ionic Changes - -Our Ionic 3 to Ionic 4 migration sections above may prove to be a useful reference. Generate a new Ionic 4 project using the blank starter (see [Starting an App](../developing/starting.md)). Spend time getting familiar with Ionic 4 components. Happy building! - -### Need Assistance? - -If your team would like assistance with the migration, please [reach out to us](https://ionicframework.com/enterprise-engine)! Ionic offers Advisory Services, which includes Ionic 4 training, architecture reviews, and migration assistance. diff --git a/docs/updating/5-0.md b/docs/updating/5-0.md deleted file mode 100644 index 6a5f621..0000000 --- a/docs/updating/5-0.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: Updating to v5 ---- - -# Updating from Ionic 4 to 5 - -Migrating an app from Ionic 4 to 5 requires a few updates to the API properties, CSS utilities, and the installed package dependencies. - -:::note -This guide assumes that you have already updated your app to the latest version of Ionic 4. Make sure you have followed the [Updating to Ionic 4 Guide](./4-0) before starting this guide. -::: - -:::info Breaking Changes -For a **complete list of breaking changes** from Ionic 4 to Ionic 5, please refer to [the breaking changes document](https://github.com/ionic-team/ionic-framework/blob/main/BREAKING_ARCHIVE/v5.md) in the Ionic Framework repository. -::: - -### Packages and Dependencies - -For Angular based projects, you can simply run: - -```shell -npm install @ionic/angular@v5-lts @ionic/angular-toolkit@4.0.0 --save -``` - -For React projects, you can run: - -```shell -npm install @ionic/react@v5-lts @ionic/react-router@v5-lts ionicons@5.5.3 -``` - -For Stencil / vanilla JS projects, you can run: - -```shell -npm i @ionic/core@v5-lts --save -``` - -If you would like a fresh project starter, a new project base can be created from the CLI and an existing app can be migrated over manually. diff --git a/docs/updating/6-0.md b/docs/updating/6-0.md deleted file mode 100644 index 321daf2..0000000 --- a/docs/updating/6-0.md +++ /dev/null @@ -1,478 +0,0 @@ ---- -title: Updating to v6 ---- - -# Updating from Ionic 5 to 6 - -:::note -This guide assumes that you have already updated your app to the latest version of Ionic 5. Make sure you have followed the [Updating to Ionic 5 Guide](./5-0) before starting this guide. -::: - -:::info Breaking Changes -For a **complete list of breaking changes** from Ionic 5 to Ionic 6, please refer to [the breaking changes document](https://github.com/ionic-team/ionic-framework/blob/main/BREAKING.md) in the Ionic Framework repository. -::: - -## Getting Started - -### Angular - -1. Ionic 6 supports Angular 12+. Update to the latest version of Angular by following the [Angular Update Guide](https://update.angular.io/). -2. Update to the latest version of Ionic 6: - -```shell -npm install @ionic/angular@6 -``` - -If you are using Ionic Angular Server, be sure to update that as well: - -```shell -npm install @ionic/angular@6 @ionic/angular-server@6 -``` - -3. Remove any usage of `Config.set()`. Instead, set your config in `IonicModule.forRoot()`. See the [Angular Config Documentation](../developing/config) for more examples. -4. Remove any usage of the `setupConfig` function previously exported from `@ionic/angular`. Set your config in `IonicModule.forRoot()` instead. - -### React - -1. Ionic 6 supports React 17+. Update to the latest version of React: - -```shell -npm install react@latest react-dom@latest -``` - -2. Update to the latest version of Ionic 6: - -```shell -npm install @ionic/react@6 @ionic/react-router@6 -``` - -3. Update the `test` field in the `scripts` object of your `package.json` to include `transformIgnorePatterns`: - -```json -"scripts": { - "test": "react-scripts test --transformIgnorePatterns 'node_modules/(?!(@ionic/react|@ionic/react-router|@ionic/core|@stencil/core|ionicons)/)'", - ... -} -``` - -4. Import and call `setupIonicReact` in your `App` component file. If you are also using `setupConfig`, pass your config to `setupIonicReact` instead: - -**Before** - -```tsx title="App.tsx" -import { setupConfig } from '@ionic/react'; - -... - -setupConfig({ - mode: 'md' -}); -``` - -**After** - -```tsx title="App.tsx" -import { setupIonicReact } from '@ionic/react'; - -... - -setupIonicReact({ - mode: 'md' -}); -``` - -:::note -Developers must import and call `setupIonicReact` even if they are not setting custom config. -::: - -See the [React Config Documentation](../developing/config) for more examples. - -5. Update all controller imports from `@ionic/core` to `@ionic/core/components`. As an example, here is a migration for `menuController`: - -**Before** - -```tsx -import { menuController } from '@ionic/core'; -``` - -**After** - -```tsx -import { menuController } from '@ionic/core/components'; -``` - -### Vue - -1. Ionic 6 supports Vue 3.0.6+. Update to the latest version of Vue: - -```shell -npm install vue@3 vue-router@4 -``` - -2. For apps that use the Vue CLI, install Vue CLI 5: - -```shell -npm install -g @vue/cli@next -``` - -Then, upgrade all Vue CLI plugins: - -```shell -vue upgrade --next -``` - -3. Update to the latest version of Ionic 6: - -```shell -npm install @ionic/vue@6 @ionic/vue-router@6 -``` - -4. Add the following `transformIgnorePatterns` to either `jest.config.js` or the `jest` field in `package.json`: - -```js title="jest.config.js" -module.exports = { - ... - transformIgnorePatterns: ['/node_modules/(?!@ionic/vue|@ionic/vue-router|@ionic/core|@stencil/core|ionicons)'] -} -``` - -```json title="package.json" - { - ... - "jest": { - "transformIgnorePatterns": ["/node_modules/(?!@ionic/vue|@ionic/vue-router|@ionic/core|@stencil/core|ionicons)"] - } - } -``` - -See the [Testing section below](#testing) for more information. - -5. Remove any usage of the `setupConfig` function previously exported from `@ionic/vue`. Set your config when installing the `IonicVue` plugin instead. See the [Vue Config Documentation](../developing/config) for more examples. - -6. Rename the `IonRouter` type for `useIonRouter` to `UseIonRouterResult`. - -7. Rename the `IonKeyboardRef` type for `useKeyboard` to `UseKeyboardResult`. - -8. Rename any overlay event listeners to use the new format: - -**Before** - -```html - - ... - -``` - -**After** - -```html - - ... - -``` - -:::note -This applies to `ion-action-sheet`, `ion-alert`, `ion-loading`, `ion-modal`, `ion-picker`, `ion-popover`, and `ion-toast`. -::: - -9. Pass in an `ion-router-outlet` into any `ion-tabs` that are being used: - -**Before** - -```html - - ... - - - -``` - -**After** - -```html - - - ... - - - -``` - -10. Additional routes inside of tabs should be re-written as sibling routes instead of child routes: - -**Before** - -```ts -const routes: Array = [ - { - path: '/', - redirect: '/tabs/tab1' - }, - { - path: '/tabs/', - component: Tabs, - children: [ - { - path: '', - redirect: 'tab1' - }, - { - path: 'tab1', - component: () => import('@/views/Tab1.vue'), - children: { - { - path: 'view', - component: () => import('@/views/Tab1View.vue') - } - } - }, - { - path: 'tab2', - component: () => import('@/views/Tab2.vue') - }, - { - path: 'tab3', - component: () => import('@/views/Tab3.vue') - } - ] - } -] -``` - -**After** - -```ts -const routes: Array = [ - { - path: '/', - redirect: '/tabs/tab1', - }, - { - path: '/tabs/', - component: Tabs, - children: [ - { - path: '', - redirect: 'tab1', - }, - { - path: 'tab1', - component: () => import('@/views/Tab1.vue'), - }, - { - path: 'tab1/view', - component: () => import('@/views/Tab1View.vue'), - }, - { - path: 'tab2', - component: () => import('@/views/Tab2.vue'), - }, - { - path: 'tab3', - component: () => import('@/views/Tab3.vue'), - }, - ], - }, -]; -``` - -### Core - -1. Update to the latest version of Ionic 6: - -```shell -npm install @ionic/core@6 -``` - -## Updating Your Code - -### Datetime - -1. Remove any usages of the `placeholder`, `pickerOptions`, `pickerFormat`, `monthNames`, `monthShortNames`, `dayNames`, and `dayShortNames` properties. `ion-datetime` now automatically formats the month names, day names, and time displayed inside of the component according to the language and region set on the device. See the [ion-datetime Localization Documentation](../api/datetime#localization) for more information. - -2. Remove any usages of the `text` and `placeholder` CSS Shadow Parts. - -3. Remove any usages of the `--padding-bottom`, `--padding-end`, `--padding-start`, `--padding-top`, and `--placeholder-color` CSS Variables. To customize the padding on `ion-datetime`, you can use any of the `padding` CSS properties. - -4. Remove any usage of the `open` method. To present the datetime in an overlay, place it inside of an `ion-modal` or an `ion-popover` component. See the [ion-datetime Usage Examples](../api/datetime#usage) for more information. - -5. Remove any usage of the `displayFormat` or `displayTimezone` properties. To parse the UTC string provided in the payload of the `ionChange` event, we recommend using [date-fns](https://date-fns.org/). See the [ion-datetime Parsing Dates Documentation](../api/datetime#parsing-dates) for examples. - -:::note -See the [Datetime Migration Sample Application](https://github.com/ionic-team/datetime-migration-samples) for more migration examples. -::: - -### Icon - -Ionic 6 now ships with Ionicons 6. Review the [Ionicons 6 Breaking Changes Guide](https://github.com/ionic-team/ionicons/releases/tag/v6.0.0) and make any necessary changes. - -### Input - -Ensure `null` is not passed in as a value to the `placeholder` property. We recommend using `undefined` instead. - -### Modal - -`ion-modal` now uses the Shadow DOM. Update any styles targeting the internals of `ion-modal` to use either the [ion-modal CSS Variables](../api/modal#css-custom-properties) or the [ion-modal CSS Shadow Parts](../api/modal#css-shadow-parts): - -**Before** - -```css -ion-modal .modal-wrapper { - /* Any custom styles here */ -} - -ion-modal ion-backdrop { - /* Any custom styles here */ -} -``` - -**After** - -```css -ion-modal::part(content) { - /* Any custom styles here */ -} - -ion-modal::part(backdrop) { - /* Any custom styles here */ -} -``` - -### Popover - -`ion-popover` now uses the Shadow DOM. Update any styles targeting the internals of `ion-popover` to use either [ion-popover CSS Variables](../api/popover#css-custom-properties) or the [ion-popover CSS Shadow Parts](../api/popover#css-shadow-parts): - -**Before** - -```css -ion-popover .popover-arrow { - /* Any custom styles here */ -} - -ion-popover ion-backdrop { - /* Any custom styles here */ -} - -ion-popover .popover-content { - /* Any custom styles here */ -} -``` - -**After** - -```css -ion-popover::part(arrow) { - /* Any custom styles here */ -} - -ion-popover::part(backdrop) { - /* Any custom styles here */ -} - -ion-popover::part(content) { - /* Any custom styles here */ -} -``` - -### Radio - -Remove any usage of the `RadioChangeEventDetail` interface. - -### Select - -Ensure `null` is not passed in as a value to the `placeholder` property. We recommend using `undefined` instead. - -### Textarea - -Ensure `null` is not passed in as a value to the `placeholder` property. We recommend using `undefined` instead. - -### Browser Support - -The list of browsers that Ionic supports has changed. Review the [Browser Support Guide](../reference/browser-support) to ensure you are deploying apps to supported browsers. - -If you have a `browserslist` or `.browserslistrc` file, update it with the following content: - -``` -Chrome >=60 -Firefox >=63 -Edge >=79 -Safari >=13 -iOS >=13 -``` - -### Testing - -Ionic 6 now ships as ES Modules. ES Modules are supported in all major browsers and bring developer experience and code maintenance improvements. Developers testing with Jest will need to update their Jest configuration as Jest does not have full support for ES Modules as of Jest 27. - -This update involves using Babel to compile Ionic's ES Modules down to the CommonJS (CJS) format, a format that Jest can understand. Once Jest ships support for ES Modules, this change will no longer be necessary. See https://github.com/facebook/jest/issues/9430 for updates on ES Modules support in Jest. - -If you are starting fresh with a new Ionic app, this configuration is done for you in our starter applications. For those with existing Ionic apps, follow the steps below to get Jest working with Ionic 6: - -1. Add a `transformIgnorePatterns` field to your Jest config that includes the relevant Ionic packages. This is typically found in `jest.config.js` or the `jest` field in `package.json`: - -```js title="jest.config.js" -module.exports = { - ... - transformIgnorePatterns: ['/node_modules/(?!@ionic/core|@stencil/core|ionicons)'] -} -``` - -```json title="package.json" - { - ... - "jest": { - "transformIgnorePatterns": ["/node_modules/(?!@ionic/core|@stencil/core|ionicons)"] - } - } -``` - -:::note -If you are using Ionic React or Ionic Vue, be sure to add the appropriate packages to the `transformIgnorePatterns` array. For Ionic React this includes `@ionic/react` and `@ionic/react-router`. For Ionic Vue this includes `@ionic/vue` and `@ionic/vue-router`. -::: - -For developers using Create React App (CRA), there is currently no way to update the `transformIgnorePatterns` in a Jest config file. This is a CRA restriction and not something Ionic has control over. We can, however, pass the `transformIgnorePatterns` directly into the `react-scripts test` command: - -```json title="package.json" -"scripts": { - "test": "react-scripts test --transformIgnorePatterns 'node_modules/(?!(@ionic/react|@ionic/react-router|@ionic/core|@stencil/core|ionicons)/)'", - ... -} -``` - -If you are still running into issues, here are a couple things to try: - -1. Verify that `@babel/preset-env` is included in your [project-wide configuration](https://babeljs.io/docs/en/config-files#project-wide-configuration) instead of your [file-relative configuration](https://babeljs.io/docs/en/config-files#file-relative-configuration). This typically means defining the Babel configuration in `/babel.config.json`. - -2. If you have a `browserslist/test` field in `package.json` file, make sure it is set to `current node`. - -## Need Help Upgrading? - -Be sure to look at the [Ionic 6 Breaking Changes Guide](https://github.com/ionic-team/ionic-framework/blob/main/BREAKING.md). There were several changes to default property and CSS Variable values that developers may need to be aware of. Only the breaking changes that required user action are listed on this page. - -If you need help upgrading, please post a thread on the [Ionic Forum](https://forum.ionicframework.com/). diff --git a/docs/updating/7-0.md b/docs/updating/7-0.md deleted file mode 100644 index b2301a2..0000000 --- a/docs/updating/7-0.md +++ /dev/null @@ -1,155 +0,0 @@ ---- -title: Updating to v7 ---- - -# Updating from Ionic 6 to 7 - -:::note -This guide assumes that you have already updated your app to the latest version of Ionic 6. Make sure you have followed the [Upgrading to Ionic 6 Guide](./6-0) before starting this guide. -::: - -:::info Breaking Changes -For a **complete list of breaking changes** from Ionic 6 to Ionic 7, please refer to [the breaking changes document](https://github.com/ionic-team/ionic-framework/blob/main/BREAKING.md#version-7x) in the Ionic Framework repository. -::: - -## Getting Started - -### Angular - -1. Ionic 7 supports Angular 14+. Update to the latest version of Angular by following the [Angular Update Guide](https://update.angular.io/). -2. If your project is using rxjs, Ionic 7 requires a minimum rxjs version of 7.5.0: - -```shell -npm install rxjs@7.5.0 -``` - -3. Update to the latest version of Ionic 7: - -```shell -npm install @ionic/angular@7 -``` - -If you are using Ionic Angular Server and Ionic Angular Toolkit, be sure to update those as well: - -```shell -npm install @ionic/angular@7 @ionic/angular-server@7 @ionic/angular-toolkit@9 -``` - -> Note: `@ionic/angular-toolkit@9` requires a minimum of Angular 15. If you are still on Angular 14, then you can skip updating to `@ionic/angular-toolkit@9`. - -### React - -1. Ionic 7 supports React 17+. Update to the latest version of React: - -```shell -npm install react@latest react-dom@latest -``` - -2. Update to the latest version of Ionic 7: - -```shell -npm install @ionic/react@7 @ionic/react-router@7 -``` - -### Vue - -1. Ionic 7 supports Vue 3.0.6+. Update to the latest version of Vue: - -```shell -npm install vue@latest vue-router@latest -``` - -3. Update to the latest version of Ionic 7: - -```shell -npm install @ionic/vue@7 @ionic/vue-router@7 -``` - -### Core - -1. Update to the latest version of Ionic 7: - -```shell -npm install @ionic/core@7 -``` - -## Updating Your Code - -### Browser Support - -The list of browsers that Ionic supports has changed. Review the [Browser Support Guide](../reference/browser-support) to ensure you are deploying apps to supported browsers. - -If you have a `browserslist` or `.browserslistrc` file, update it with the following content: - -``` -Chrome >=79 -ChromeAndroid >=79 -Firefox >=70 -Edge >=79 -Safari >=14 -iOS >=14 -``` - -### Types - -1. `ActionSheetAttributes`, `AlertAttributes`, `AlertTextareaAttributes`, `AlertInputAttributes`, `LoadingAttributes`, `ModalAttributes`, `PickerAttributes`, `PopoverAttributes`, and `ToastAttributes` have been removed. Developers should use `{ [key: string]: any }` instead. - -### Checkbox - -1. Rename any usages of the `--background` and `--background-checked` CSS Variables to `--checkbox-background` and `--checkbox-background-checked`, respectively. - -### Datetime - -1. Remove any code that sets the `value` property to the empty string (`''`). -2. Remove any code that accesses the time zone information on the `value` property. Datetime does not manage time zones, so any time zone information provided is ignored. - -### Input - -1. Update any code that accesses the `detail` payload for the `ionInput` event from `event.detail` to `event.detail.value` as the detail payload is now an object containing a value and an event. - -### Modal - -1. Remove any usage of the `swipeToClose` property. Card modals are swipeable by default, so you can remove `swipeToClose` if you want your card modal to remain swipeable. Use the [canDismiss](https://ionicframework.com/docs/api/modal#preventing-a-modal-from-dismissing) property if you want to prevent a modal from dismissing. -2. Remove any code that sets the `canDismiss` property to `undefined`. The `canDismiss` property now defaults to `true`, so this code is no longer needed. - -### Picker - -1. Remove any code that accesses `refresh` on `ion-picker-column`. Developers should use the `columns` property on `ion-picker` to refresh the view instead. - -### Searchbar - -1. Update any code that accesses the `detail` payload for the `ionInput` event from `event.detail` to `event.detail.value` as the detail payload is now an object containing a value and an event. - -### Segment - -1. Remove any code that sets the `value` property to `null`. Developers should use either `''` or `undefined` instead. - -### Slides - -1. Remove `ion-slides`, `ion-slide`, and any associated types. These components have been removed in favor of using Swiper.js directly. The guides below contain more information about this migration: - -[Angular Migration Guide](https://ionicframework.com/docs/angular/slides)
-[React Migration Guide](https://ionicframework.com/docs/react/slides)
-[Vue Migration Guide](https://ionicframework.com/docs/vue/slides) - -### Textarea - -1. Update any code that accesses the `detail` payload for the `ionInput` event from `event.detail` to `event.detail.value` as the detail payload is now an object containing a value and an event. - -### Toggle - -1. Rename any usages of the `--background` and `--background-checked` CSS Variables to `--track-background` and `--track-background-checked`, respectively. - -### Virtual Scroll - -1. Remove `ion-virtual-scroll` and any associated types. This component has been removed in favor of using virtual scroll solutions provided by JavaScript Frameworks. The guides below contain more information about this migration: - -[Angular Migration Guide](https://ionicframework.com/docs/angular/virtual-scroll)
-[React Migration Guide](https://ionicframework.com/docs/react/virtual-scroll)
-[Vue Migration Guide](https://ionicframework.com/docs/vue/virtual-scroll) - -## Need Help Upgrading? - -Be sure to look at the [Ionic 7 Breaking Changes Guide](https://github.com/ionic-team/ionic-framework/blob/main/BREAKING.md#version-7x). There were several changes to default property and CSS Variable values that developers may need to be aware of. Only the breaking changes that require user action are listed on this page. - -If you need help upgrading, please post a thread on the [Ionic Forum](https://forum.ionicframework.com/). diff --git a/sidebars.js b/sidebars.js index f1a85ef..94647f3 100644 --- a/sidebars.js +++ b/sidebars.js @@ -1,18 +1,16 @@ module.exports = { docs: [ - { - type: 'category', - label: 'Getting Started', - collapsed: false, - items: ['index', 'intro/environment', 'intro/cli'], - }, - + 'index', + { + type: 'category', + label: 'Initiatives', + collapsed: false, + items: [ + 'initiatives/onboarding', + 'initiatives/community', + 'initiatives/dmp', + 'initiatives/website', + ], + }, ], - - // api: [{ - // type: 'category', - // label: 'Getting Started', - // collapsed: false, - // items: ['components'], - // }], };