Skip to content

[skip changelog] Document filter setting capability of Library/Boards Manager links #1958

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Oct 31, 2022
Merged

[skip changelog] Document filter setting capability of Library/Boards Manager links #1958

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 40 additions & 8 deletions docs/sketch-specification.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -140,28 +140,60 @@ no requirement to store sketches in the sketchbook folder.

## Library/Boards Manager links

A URI in a comment in the form `http://librarymanager#SEARCH_TERM` will open a search for SEARCH_TERM in
**(available in Arduino IDE >=1.6.9 <2.x || >=2.0.1)**

A URI in a comment in the form:

```text
http://librarymanager[/TYPE_FILTER[/TOPIC_FILTER]][#SEARCH_KEYWORDS]
```

will open a search in
[Library Manager](https://docs.arduino.cc/software/ide-v1/tutorials/installing-libraries#using-the-library-manager) when
clicked in the Arduino IDE.

A URI in a comment in the form `http://boardsmanager#SEARCH_TERM` will open a search for SEARCH_TERM in
[Boards Manager](https://docs.arduino.cc/learn/starting-guide/cores) when clicked in the Arduino IDE.
A URI in a comment in the form:

```text
http://boardsmanager[/TYPE_FILTER][#SEARCH_KEYWORDS]
```

will open a search in [Boards Manager](https://docs.arduino.cc/learn/starting-guide/cores) when clicked in the Arduino
IDE.

These links can be used to offer the user an easy way to install dependencies of the sketch.

This can be used to offer the user an easy way to install dependencies of the sketch.
The search field will be populated with the `SEARCH_KEYWORDS` fragment component of the URI. Any characters other than
`A`-`Z`, `a`-`z`, `0`-`9`, and `:` are treated as spaces by the search algorithm, which allows multiple keywords to be
specified via the URI.

---

**(available in Arduino IDE >=2.0.1)**

The "**Type**" filter will be set to the optional `TYPE_FILTER` path component of the URI.

The Library Manager "**Topic**" filter will be set to the optional `TOPIC_FILTER` path component of the URI.

Unlike the `SEARCH_KEYWORDS` fragment, spaces and reserved characters in these components must be
[percent-encoded](https://en.wikipedia.org/wiki/Percent-encoding) (e.g., `Signal%20Input%2FOutput`).

Although the filter setting is not supported by previous IDE versions, URIs containing these path components still
function in all other respects.

---

This feature is only available when using the Arduino IDE, so be sure to provide supplementary documentation to help the
users of other development software install the sketch dependencies.

This feature was added in Arduino IDE 1.6.9.

### Example

```c++
// install the Arduino SAMD Boards platform to add support for your MKR WiFi 1010 board
// if using the Arduino IDE, click here: http://boardsmanager#SAMD
// if using the Arduino IDE, click here: http://boardsmanager/Arduino#SAMD

// install the WiFiNINA library via Library Manager
// if using the Arduino IDE, click here: http://librarymanager#WiFiNINA
// if using the Arduino IDE, click here: http://librarymanager/Arduino/Communication#WiFiNINA
#include <WiFiNINA.h>
```

Expand Down