diff --git a/README.md b/README.md index 97a7e9c..8052c4f 100644 --- a/README.md +++ b/README.md @@ -72,10 +72,12 @@ The [Branded Portal](examples/BrandedPortal/) example includes a static SVG, acc | Goal | Guide | | --- | --- | -| Brand the portal or add structured built-in content | [Portal UI](docs/PORTAL_UI.md) | +| Brand the built-in portal | [Portal UI](docs/PORTAL_UI.md) | +| Add application settings, status, or home cards | [Structured portal content](docs/PORTAL_UI.md#structured-portal-content) | | Configure primary/fallback station profiles | [Station profiles](docs/STATION_PROFILES.md) | | Understand the JSON APIs and station-connect handoff | [Portal API](docs/PORTAL_API.md) | | Build or flash a complete example | [Examples](examples/README.md) | +| Run documentation and board-free compile checks | [Testing](docs/TESTING.md) | | Contribute to this fork or prepare a release | [Development](docs/DEVELOPMENT.md) | ## Install diff --git a/docs/GETTING_STARTED.md b/docs/GETTING_STARTED.md index 5d23109..1e360d1 100644 --- a/docs/GETTING_STARTED.md +++ b/docs/GETTING_STARTED.md @@ -10,7 +10,7 @@ WiFiManager wifi; void setup() { Serial.begin(115200); - wifi.setConfigPortalTimeout(180); + wifi.setConfigPortalTimeout(180); // Stop the portal after three minutes. wifi.autoConnect("Example Setup", "change-me"); } @@ -20,7 +20,7 @@ void loop() { } ``` -`autoConnect()` first tries stored station credentials. If that cannot connect, it starts the AP and portal with the supplied name and password, then returns `false`; call `process()` from `loop()` so that portal can run. Use a Wi-Fi-valid AP password. +`autoConnect()` first tries stored station credentials. If that cannot connect, it starts the AP and portal with the supplied name and password, then returns `false`; call `process()` from `loop()` so that portal can run. `setConfigPortalTimeout(180)` limits that portal to three minutes; pass `0` (the default) to leave it open. Use a Wi-Fi-valid AP password. ## PlatformIO dependency diff --git a/docs/PORTAL_UI.md b/docs/PORTAL_UI.md index a370564..5c750f2 100644 --- a/docs/PORTAL_UI.md +++ b/docs/PORTAL_UI.md @@ -68,6 +68,14 @@ Leave a text or colour value empty, or a radius at `0`, to retain the built-in s Theme values accept only simple semantic CSS value syntax and are emitted once into a small `#wm-portal-theme` block. This is deliberately not a raw CSS or JavaScript injection API. An SVG is a trusted compiled firmware asset, never form, MQTT, or network input. +## Structured portal content + +`portalAddParameter()` adds an editable application value. `portalAddInfoSection()` renders labelled read-only values, and `portalAddHomeCard()` adds a text, callout, or key/value card to the overview. + +Register content before opening the portal. A `WiFiManagerParameter` remains application-owned and must outlive the portal; info sections and home cards are copied when registered. Handle a saved value in `setSaveParamsCallback()`, then validate and persist it in your application. + +The buildable [Custom Portal Content](../examples/CustomPortalContent/) example uses all three without replacing the built-in portal shell. + ## Built-in portal capabilities Presentation uses one configuration route: `setPortalConfig()`. Existing structured portal capabilities remain separate: `portalAddParameter()`, `portalAddInfoSection()`, `portalAddHomeCard()`, page visibility, and portal behavior configure documented built-in functionality rather than private markup. See [Portal API](PORTAL_API.md) and [Station profiles](STATION_PROFILES.md). diff --git a/docs/README.md b/docs/README.md index 7aca98c..4a3c899 100644 --- a/docs/README.md +++ b/docs/README.md @@ -3,9 +3,11 @@ | I want to… | Read | | --- | --- | | Start a basic portal or install a released dependency | [Getting started](GETTING_STARTED.md) | -| Brand the portal or add structured built-in content | [Portal UI](PORTAL_UI.md) | +| Brand the built-in portal | [Portal UI](PORTAL_UI.md) | +| Add application settings, status, or home cards | [Structured portal content](PORTAL_UI.md#structured-portal-content) | | Configure primary/fallback station profiles or their portal workflow | [Station profiles](STATION_PROFILES.md) | | Consume JSON endpoints or station-connect status | [Portal API](PORTAL_API.md) | +| Run documentation and board-free compile checks | [Testing](TESTING.md) | | Build or flash a complete example | [Examples](../examples/README.md) | | Work on this fork or make a release | [Development and releases](DEVELOPMENT.md) | diff --git a/examples/CustomPortalContent/CustomPortalContent.ino b/examples/CustomPortalContent/CustomPortalContent.ino index 30676eb..9246fa6 100644 --- a/examples/CustomPortalContent/CustomPortalContent.ino +++ b/examples/CustomPortalContent/CustomPortalContent.ino @@ -8,14 +8,24 @@ void setup() { Serial.begin(115200); portal.portalAddParameter(&brokerHost); - portal.portalAddInfoSection({ - "device", "Example device", - {{"firmware", "Firmware", "1.0.0"}, {"sensor", "Sensor", "Ready"}}, - }); - portal.portalAddHomeCard({ - "hint", "What this example adds", PortalHomeCardKind::Callout, - "A normal text setting, a status section, and a home-page callout.", {}, - }); + + // WiFiManager copies this read-only status section when it is registered. + PortalInfoSection deviceInfo; + deviceInfo.id = "device"; + deviceInfo.title = "Example device"; + deviceInfo.items = { + {"firmware", "Firmware", "1.0.0"}, + {"sensor", "Sensor", "Ready"}, + }; + portal.portalAddInfoSection(deviceInfo); + + // This callout appears on the built-in portal overview. + PortalHomeCard hint; + hint.id = "hint"; + hint.title = "What this example adds"; + hint.kind = PortalHomeCardKind::Callout; + hint.text = "A normal text setting, a status section, and a home-page callout."; + portal.portalAddHomeCard(hint); portal.setSaveParamsCallback([](WiFiManager::WiFiManagerRequestArgs) { Serial.print("MQTT broker selected: "); diff --git a/examples/CustomPortalContent/README.md b/examples/CustomPortalContent/README.md index 5874078..a811f08 100644 --- a/examples/CustomPortalContent/README.md +++ b/examples/CustomPortalContent/README.md @@ -10,4 +10,4 @@ It opens **WiFiManager Content** with password **example-pass** until it has wor The parameter object is global because WiFiManager reads it for the lifetime of the portal. In a real application, copy the value into that application’s own validated persistent configuration inside the save callback. -See [Portal UI](../../docs/PORTAL_UI.md) and the shared [example guide](../README.md). +See [structured portal content](../../docs/PORTAL_UI.md#structured-portal-content) and the shared [example guide](../README.md). diff --git a/examples/README.md b/examples/README.md index f9c9888..48e0d7a 100644 --- a/examples/README.md +++ b/examples/README.md @@ -17,6 +17,13 @@ Choose `esp32` for an ESP32 development board. The examples use the checked-out | [Branded Portal](BrandedPortal/) | change the portal’s identity, logo, and semantic visual theme | | [Station Profiles](StationProfiles/) | remember a primary Wi-Fi network and one fallback in application-owned EEPROM storage | -The portal examples intentionally begin with no station credentials. On first boot, connect to the access point printed on serial and open `http://192.168.4.1/`. +The portal examples intentionally begin with no station credentials. On first boot, connect to the matching setup network and open `http://192.168.4.1/`. + +| Example | Setup network | Password | +| --- | --- | --- | +| Basic Portal | WiFiManager Basic | example-pass | +| Custom Portal Content | WiFiManager Content | example-pass | +| Branded Portal | Temperature Monitor | none | +| Station Profiles | WiFiManager Profiles | example-pass | Back to the [project overview](../README.md).