WiFiManagerParameter API Changes

[dmadison]

This PR makes some small API changes to the WiFiManagerParameter class to improve clarity, usability, and encapsulation:

Length to Max Length

• All length arguments have been changed to maxLength
• getValueLength() has been changed to getValueMaxLength()

When used as an argument, this refers to the max length of the form and the size of the internal buffer, not the length of the string passed as an argument as expected.

Similarly, the value returned is the max length of the form and the size of the internal buffer, not the length of the value stored.

The internal name (_length) has not been changed to maintain compatibility with user code, as it's exposed as a protected value. This should be changed in the next major version.

ID to Name

• getID() has been changed to getName()

In HTML forms, names and IDs are two different attributes. Although this value is applied to both, when submitted the form data corresponds to the name, not the ID. This causes confusion if we want the name and ID to differ, since we are currently calling the name the ID internally.

The internal name (_id) has not been changed to maintain compatibility with user code, as it's exposed as a protected value. This should be changed in the next major version.

Value Received Function

• Created a setValueReceived() function to receive data from the server

Currently the user can set the parameter value and max length via the setValue(const char *defaultValue, int maxLength) function, and in WiFiManager::doParamSave() the server sets the value directly to the buffer pointer using the existing max length.

This function provides a standardized way for the server (and any user code) to set a new value while respecting the existing max length value. This is also virtual, so derived parameter classes can intercept the received value and perform additional logic or sanitization if necessary.

WiFiManager friendship removed

There is no reason for the WiFiManager class to have a friendship with the parameter class. The internal calls have been replaced with the corresponding public functions and the friendship has been removed.

Incidental Bugfixes

• setValue() now checks if a max length argument is negative
• WiFiManagerParameter's destructor is now virtual

---

Although PR contains API changes there should be no breaking changes. The few items marked deprecated should be removed on the next major release.

If this is merged, here are the changes to make on the next major release:

• WiFiManagerParameter::_length should be refactored to _maxLength
• WiFiManagerParameter::getValueLength() const should be removed
• WiFiManagerParameter::_id should be refactored to _name
• WiFiManagerParameter::getID() const should be removed

This is a reworked version of PR #1772 that will serve as a basis for other WiFiManagerParameter related PRs.

[tablatronix]

Seems there are 2 PRs for this ?

2 points I can think of real quick, havent touched the code in months..

changing id to name, only issue I have is this breaks child classes that expect to getId() wont it? also these are used as keys in both html, js and c++, so will have to make sure they are unique and allowed characters.
id is the param ID we just use it for the form field names also, not sure I see the desired change here

This causes confusion if we want the name and ID to differ, is this the only use case? How are users to change the name ?

Also names are unique to forms, ids are unique to DOM, and not sure how this effects radio/checkbox groups

[dmadison]

Seems there are 2 PRs for this ?

There is 1 PR for these changes. The other two PRs (#1774 and #1775) also modify the parameter class, and thus have to include the API change commits. The two other PRs do not work without at least some of these API changes.

changing id to name, only issue I have is this breaks child classes that expect to getId() wont it?

It shouldn't. This PR should contain no changes that break the API.

The function getID() is not virtual so child classes cannot override it. That function has also has not been removed, although it has been marked @deprecated. The name for the internal value (_id) has similarly not been changed since it is exposed as protected.

If this is merged, it is recommended to remove both the deprecated function and change the internal name with the next major release.

This causes confusion if we want the name and ID to differ, is this the only use case?

Being able to change the name and ID separately is the impetus for the change, yes. But it's also good for consistency and ease of use since it would make the HTML attribute 'name' the same as the 'name' in the library API.

In the current implementation name (HTML attribute) needs to be matched using getID() (API) on form submission in order to store the received value. This PR makes it so that name (HTML attribute) is matched using getName() (API), and 'id' can be treated separately.

How are users to change the name

This PR changes 'id' to 'name' going forward in the API. Users set the 'name' in the same way they previously set the 'id', by the first argument to the class constructor.

Also names are unique to forms, ids are unique to DOM, and not sure how this effects radio/checkbox groups

Names being unique to forms is significant though, because by their nature all parameters are part of the form.

This affects radio groups because in the current implementation 'names' and 'ids' are treated the same. In a radio group, all items must share the same name attribute so they can be mutually exclusive, but should not share the same id (because then you have multiple DOM elements with a single id, which is a no-no).