diff --git a/docs/core-concepts/fundamentals.md b/docs/core-concepts/fundamentals.md index a409e57bc0b..512824fc8fd 100644 --- a/docs/core-concepts/fundamentals.md +++ b/docs/core-concepts/fundamentals.md @@ -51,3 +51,29 @@ At the core, Ionic Framework is built using Primary Button +``` + +The `color` property is a reactive property that configures how the button appears. If you change the `color` value after the initial render, the button will update to reflect the new value. + +### Virtual Properties + +Virtual properties are designed for one-time configuration during component initialization. They do not trigger re-renders when updated. + +```html +iOS Style Button Material Design Button +``` + +The `mode` property is a virtual property that determines which platform styles to use for a component. It can be set at the component level or globally through the app configuration. In both cases, it's set once during initialization and doesn't change during the component's lifecycle. + +For more information on Ionic modes, read the [Platform Styles documentation](/docs/theming/platform-styles). diff --git a/plugins/docusaurus-plugin-ionic-component-api/index.js b/plugins/docusaurus-plugin-ionic-component-api/index.js index 90e59ee09f3..e3784c6df67 100644 --- a/plugins/docusaurus-plugin-ionic-component-api/index.js +++ b/plugins/docusaurus-plugin-ionic-component-api/index.js @@ -134,18 +134,41 @@ function formatType(attr, type) { return type.replace(/\|/g, '\uff5c'); } -function renderProperties({ props: properties }) { +function renderProperties({ props: properties, docsTags }) { if (properties.length === 0) { return 'No properties available for this component.'; } + // Extract virtual property names from component-level docsTags + const virtualPropNames = []; + if (docsTags) { + docsTags.forEach((tag) => { + if (tag.name === 'virtualProp') { + // Check if any property name exists in the virtualProp tag text + // and add it to the virtualPropNames array + properties.forEach((prop) => { + if (tag.text.includes(prop.name)) { + virtualPropNames.push(prop.name); + } + }); + } + }); + } + // NOTE: replaces | with U+FF5C since MDX renders \| in tables incorrectly return ` ${properties .map((prop) => { const isDeprecated = prop.deprecation !== undefined; + const isVirtual = virtualPropNames.includes(prop.name); - const docs = isDeprecated ? `${prop.docs}\n\n**_Deprecated_** — ${prop.deprecation}` : prop.docs; + let docs = prop.docs; + if (isVirtual) { + docs = `${docs}\n\nThis is a [virtual property](/docs/core-concepts/fundamentals#virtual-properties) that is set once during initialization and will not update if you change its value after the initial render.`; + } + if (isDeprecated) { + docs = `${docs}\n\n**_Deprecated_** — ${prop.deprecation}`; + } return ` ### ${prop.name} ${isDeprecated ? '(deprecated)' : ''} diff --git a/versioned_docs/version-v5/core-concepts/fundamentals.md b/versioned_docs/version-v5/core-concepts/fundamentals.md index 23d8f728e8c..23e9713a88b 100644 --- a/versioned_docs/version-v5/core-concepts/fundamentals.md +++ b/versioned_docs/version-v5/core-concepts/fundamentals.md @@ -38,3 +38,35 @@ Projects such as CapacitorCSS which allows us to take advantage of the flexibility that CSS properties (variables) provide. This makes it incredibly easy to design an app that looks great while following the web standard. We provide a set of colors so developers can have some great defaults, but we encourage overriding them to create designs that match a brand, company or a desired color palette. Everything from the background color of an application to the text color is fully customizable. More information on app theming can be found in [Theming](../theming/basics.md). + +## Events + +Many Ionic components use [CustomEvent](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent) to inform developers of important state changes in the components. For example, an `ion-datetime` component will emit `ionChange` whenever the selected date has changed. + +Developers can use standard events such as `click` as they normally would. However, many events emitted within a component's [shadow root](../reference/glossary.md#shadow) will be [retargeted](https://dom.spec.whatwg.org/#retarget) to the host element. This may result in multiple `click` handlers executing even if the user only clicked once. As a result, developers should rely on Ionic's events to be properly informed of state changes on Ionic components. Ionic's events are prefixed with `ion` to avoid collisions with standard events. Each component's documentation page has a list of available events that developers can listen for in their applications. + +## Properties + +Properties are JavaScript properties that can be set on Ionic components to configure their behavior and appearance. Properties are defined in each component's [API documentation](/docs/api) page. + +### Reactive Properties + +Reactive properties automatically update the component when their values change. These are the most common type of property in Ionic components. + +```html +Primary Button +``` + +The `color` property is a reactive property that configures how the button appears. If you change the `color` value after the initial render, the button will update to reflect the new value. + +### Virtual Properties + +Virtual properties are designed for one-time configuration during component initialization. They do not trigger re-renders when updated. + +```html +iOS Style Button Material Design Button +``` + +The `mode` property is a virtual property that determines which platform styles to use for a component. It can be set at the component level or globally through the app configuration. In both cases, it's set once during initialization and doesn't change during the component's lifecycle. + +For more information on Ionic modes, read the [Platform Styles documentation](/docs/theming/platform-styles). diff --git a/versioned_docs/version-v6/core-concepts/fundamentals.md b/versioned_docs/version-v6/core-concepts/fundamentals.md index 97a09499934..512824fc8fd 100644 --- a/versioned_docs/version-v6/core-concepts/fundamentals.md +++ b/versioned_docs/version-v6/core-concepts/fundamentals.md @@ -45,3 +45,35 @@ Projects such as CapacitorCSS which allows us to take advantage of the flexibility that CSS properties (variables) provide. This makes it incredibly easy to design an app that looks great while following the web standard. We provide a set of colors so developers can have some great defaults, but we encourage overriding them to create designs that match a brand, company or a desired color palette. Everything from the background color of an application to the text color is fully customizable. More information on app theming can be found in [Theming](../theming/basics.md). + +## Events + +Many Ionic components use [CustomEvent](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent) to inform developers of important state changes in the components. For example, an `ion-datetime` component will emit `ionChange` whenever the selected date has changed. + +Developers can use standard events such as `click` as they normally would. However, many events emitted within a component's [shadow root](../reference/glossary.md#shadow) will be [retargeted](https://dom.spec.whatwg.org/#retarget) to the host element. This may result in multiple `click` handlers executing even if the user only clicked once. As a result, developers should rely on Ionic's events to be properly informed of state changes on Ionic components. Ionic's events are prefixed with `ion` to avoid collisions with standard events. Each component's documentation page has a list of available events that developers can listen for in their applications. + +## Properties + +Properties are JavaScript properties that can be set on Ionic components to configure their behavior and appearance. Properties are defined in each component's [API documentation](/docs/api) page. + +### Reactive Properties + +Reactive properties automatically update the component when their values change. These are the most common type of property in Ionic components. + +```html +Primary Button +``` + +The `color` property is a reactive property that configures how the button appears. If you change the `color` value after the initial render, the button will update to reflect the new value. + +### Virtual Properties + +Virtual properties are designed for one-time configuration during component initialization. They do not trigger re-renders when updated. + +```html +iOS Style Button Material Design Button +``` + +The `mode` property is a virtual property that determines which platform styles to use for a component. It can be set at the component level or globally through the app configuration. In both cases, it's set once during initialization and doesn't change during the component's lifecycle. + +For more information on Ionic modes, read the [Platform Styles documentation](/docs/theming/platform-styles). diff --git a/versioned_docs/version-v7/core-concepts/fundamentals.md b/versioned_docs/version-v7/core-concepts/fundamentals.md index a409e57bc0b..512824fc8fd 100644 --- a/versioned_docs/version-v7/core-concepts/fundamentals.md +++ b/versioned_docs/version-v7/core-concepts/fundamentals.md @@ -51,3 +51,29 @@ At the core, Ionic Framework is built using Primary Button +``` + +The `color` property is a reactive property that configures how the button appears. If you change the `color` value after the initial render, the button will update to reflect the new value. + +### Virtual Properties + +Virtual properties are designed for one-time configuration during component initialization. They do not trigger re-renders when updated. + +```html +iOS Style Button Material Design Button +``` + +The `mode` property is a virtual property that determines which platform styles to use for a component. It can be set at the component level or globally through the app configuration. In both cases, it's set once during initialization and doesn't change during the component's lifecycle. + +For more information on Ionic modes, read the [Platform Styles documentation](/docs/theming/platform-styles).