Implement and migrate to a shortcode-controlled, tabbed interface (fl…

…utter#10793) Introduces new `{% tabs "save-key" %}` and `{% tab "name" %}` 11ty/Liquid paired shortcodes to add tabs to the site and switches the various tab methods across the site (`codesample` and raw HTML) to use them. The `save-key` parameter is optional and allows syncing of tabs across the site to the same tab. For example, the `darwin-language` key is used to switch all tabs with the same key to either `Swift` or `Objective-C`. The `name` parameter tab is not optional. Both `save-key` and `name` must be in quotes or refer to a Liquid/11ty variable that is a string. The `{% endtab %}` and `{% endtabs %}` closing shortcodes are required to close a tab and a tab menu respectively. **Example:** ````liquid {% tabs "darwin-language" %} {% tab "Swift" %} Some words about the following Swift snippet... ```swift let flutterViewController = FlutterViewController( project: nil, initialRoute: "/onboarding", nibName: nil, bundle: nil) ``` {% endtab %} {% tab "Objective-C" %} Some words about the following Objective-C snippet... ```objc FlutterViewController* flutterViewController = [[FlutterViewController alloc] initWithProject:nil initialRoute:@"/onboarding" nibName:nil bundle:nil]; ``` {% endtab %} {% endtabs %} ```` Resolves flutter#8926 Contributes to flutter#8889 Contributes to flutter#8030
atsansone · Jun 27, 2024 · 452e5f7 · 452e5f7
1 parent 6dc7bb9
commit 452e5f7
Show file tree

Hide file tree

Showing 38 changed files with 505 additions and 810 deletions.
diff --git a/eleventy.config.js b/eleventy.config.js
@@ -3,6 +3,7 @@
 // plugins and customization that live in `/src/_11ty`.
 
 import { registerFilters } from './src/_11ty/filters.js';
+import { registerShortcodes } from './src/_11ty/shortcodes.js';
 import { markdown } from './src/_11ty/plugins/markdown.js';
 import { configureHighlighting } from './src/_11ty/plugins/highlight.js';
 
@@ -43,50 +44,8 @@ export default function (eleventyConfig) {
 
   eleventyConfig.addPlugin(EleventyRenderPlugin);
 
-  let _currentTabsTitle = '';
-  let _currentTabIsActive = false;
-
-  // TODO(parlough): Replace samplecode with something easier.
-  eleventyConfig.addShortcode('samplecode', function(tabsTitle, tabsString) {
-    _currentTabsTitle = tabsTitle.toLowerCase();
-    let tabMarkup = `<ul class="nav nav-tabs sample-code-tabs" id="${_currentTabsTitle}-language" role="tablist">`;
-
-    let activeTab = true;
-    _currentTabIsActive = true;
-
-    const tabs = tabsString.split(',').map((tab) => tab.trim());
-    tabs.forEach((tabName) => {
-      const tabId = `${_currentTabsTitle}-${tabName.toLowerCase().replaceAll("+", "-plus")}`;
-      tabMarkup += `<li class="nav-item">
-  <a class="nav-link ${activeTab ? "active" : ""}" id="${tabId}-tab" href="#${tabId}" role="tab" aria-controls="${tabId}" aria-selected="true">${tabName}</a>
-</li>`;
-      activeTab = false;
-    });
-
-    tabMarkup += `</ul><div class="tab-content">
-`;
-    return tabMarkup;
-  });
-
-  eleventyConfig.addShortcode('endsamplecode', function() {
-    return `</div>`
-  });
-
-  eleventyConfig.addPairedShortcode('sample', function(content, tabName) {
-    const tabId = `${_currentTabsTitle}-${tabName.toLowerCase().replaceAll("+", "-plus")}`;
-    const tabContent = `<div class="tab-pane ${_currentTabIsActive ? "active" : ""}" id="${tabId}" role="tabpanel" aria-labelledby="${tabId}-tab">
-
-${content}
-
-</div>
-`;
-
-    _currentTabIsActive = false;
-
-    return tabContent;
-  });
-
   registerFilters(eleventyConfig);
+  registerShortcodes(eleventyConfig);
 
   eleventyConfig.addTemplateFormats('scss');
   eleventyConfig.addWatchTarget('src/_sass');

diff --git a/src/_11ty/shortcodes.js b/src/_11ty/shortcodes.js
@@ -0,0 +1,59 @@
+import {slugify} from './utils/slugify.js';
+
+export function registerShortcodes(eleventyConfig) {
+  _setupTabs(eleventyConfig);
+}
+
+function _setupTabs(eleventyConfig) {
+  // Variable shared between all tabs to ensure each has a unique ID.
+  let currentTabId = 0;
+
+  // Variables that are shared between the tabs within a tabs shortcode,
+  // and should be reset before returning from tabs.
+  let tabs = [];
+  let markTabAsActive = true;
+
+  eleventyConfig.addPairedShortcode('tabs', function (content, saveKey) {
+    let tabMarkup = `<div class="tabs-wrapper" ${saveKey ? `data-tab-save-key="${slugify(saveKey)}"` : ''}><ul class="nav nav-tabs" role="tablist">`;
+    let activeTab = true;
+
+    tabs.forEach((tab) => {
+      const tabName = tab.name;
+      const tabSaveId = slugify(tabName);
+      const tabId = `${tab.id}-tab`;
+      const tabPanelId = `${tabId}-panel`;
+      tabMarkup += `<li class="nav-item">
+  <a class="nav-link ${activeTab ? "active" : ""}" data-tab-save-id="${tabSaveId}" id="${tabId}" href="#${tabPanelId}" role="tab" aria-controls="${tabPanelId}" aria-selected="${activeTab ? "true" : "false"}">${tabName}</a>
+</li>`;
+      activeTab = false;
+    });
+
+    tabMarkup += '</ul><div class="tab-content">\n';
+    tabMarkup += content;
+    tabMarkup += '\n</div></div>';
+
+    // Reset shared variables.
+    tabs = [];
+    markTabAsActive = true;
+
+    return tabMarkup;
+  });
+
+  eleventyConfig.addPairedShortcode('tab', function (content, tabName) {
+    const tabIdNumber = currentTabId++;
+    tabs.push({name: tabName, id: tabIdNumber});
+    const tabId = `${tabIdNumber}-tab`;
+    const tabPanelId = `${tabId}-panel`;
+    const tabContent = `<div class="tab-pane ${markTabAsActive ? "active" : ""}" id="${tabPanelId}" role="tabpanel" aria-labelledby="${tabId}">
+
+${content}
+
+</div>
+`;
+
+    // No other tabs should be marked as active.
+    markTabAsActive = false;
+
+    return tabContent;
+  });
+}
diff --git a/src/_includes/docs/add-to-app/android-initial-route-cached-engine.md b/src/_includes/docs/add-to-app/android-initial-route-cached-engine.md
@@ -12,8 +12,8 @@ with a custom initial route can configure their cached
 executing the Dart entrypoint. The following example
 demonstrates the use of an initial route with a cached engine:
 
-{% samplecode "cached-engine-with-initial-route", "Kotlin,Java" %}
-{% sample "Kotlin" %}
+{% tabs "android-language" %}
+{% tab "Kotlin" %}
 
 ```kotlin title="MyApplication.kt"
 class MyApplication : Application() {
@@ -36,8 +36,8 @@ class MyApplication : Application() {
 }
 ```
 
-{% endsample %}
-{% sample "Java" %}
+{% endtab %}
+{% tab "Java" %}
 
 ```java title="MyApplication.java"
 public class MyApplication extends Application {
@@ -60,8 +60,8 @@ public class MyApplication extends Application {
 }
 ```
 
-{% endsample %}
-{% endsamplecode %}
+{% endtab %}
+{% endtabs %}
 
 By setting the initial route of the navigation channel, the associated
 `FlutterEngine` displays the desired route upon initial execution of the

diff --git a/src/_includes/docs/community/china/download-urls.md b/src/_includes/docs/community/china/download-urls.md
@@ -14,11 +14,6 @@
 {% endif %}
 {% capture filepath -%}{{mainpath | replace: "opsys", plat}}{{file-format}} {% endcapture -%}
 
-
-<div id="{{id}}-dl" class="tab-pane
-  {%- if id == 'windows' %} active {% endif %}"
-  role="tabpanel" aria-labelledby="{{id}}-dl-tab">
-
 To download the {{include.ref-os}} 3.13 version of the Flutter SDK,
 you would change the original URL from:
 
@@ -31,5 +26,3 @@ to the mirror URL:
 ```console
 https://storage.flutter-io.cn/{{filepath}}
 ```
-
-</div>
diff --git a/src/_includes/docs/community/china/os-settings.md b/src/_includes/docs/community/china/os-settings.md
@@ -48,10 +48,6 @@ EOT
       {%- assign file-format = 'tar.xz' %}
 {% endcase %}
 
-<div id="{{id}}" class="tab-pane
-  {%- if id == 'windows' %} active {% endif %}"
-  role="tabpanel" aria-labelledby="{{id}}-tab">
-
 This procedure requires using {{shell}}.
 
 1. Open a new window in {{shell}} to prepare running scripts.
@@ -120,5 +116,3 @@ file that your preferred shell uses. This would resemble the following:
 ```console
 {{permaddexample}} 
 ```
-
-</div>
diff --git a/src/_includes/docs/community/china/pub-settings.md b/src/_includes/docs/community/china/pub-settings.md
@@ -1,10 +1,6 @@
 
 {% assign id =  include.os | downcase -%}
 
-<div id="{{id}}-pub" class="tab-pane
-  {%- if id == 'windows' %} active {% endif %}"
-  role="tabpanel" aria-labelledby="{{id}}-tab">
-
 1. Configure a proxy.
    To configure a proxy, check out the
    [Dart documentation on proxies]({{site.dart-site}}/tools/pub/troubleshoot#pub-get-fails-from-behind-a-corporate-firewall).
@@ -41,5 +37,3 @@
    ```
 
    {% endif %}
-
-</div>
diff --git a/src/_includes/docs/debug/debug-flow-android.md b/src/_includes/docs/debug/debug-flow-android.md
@@ -21,20 +21,9 @@ Running Gradle task 'bundleDebug'...                               27.1s
 ✓ Built build/app/outputs/bundle/debug/app-debug.aab.
 ```
 
-{% comment %} Nav tabs {% endcomment -%}
-<ul class="nav nav-tabs" id="vscode-to-android-studio-setup" role="tablist">
-    <li class="nav-item">
-        <a class="nav-link active" id="from-vscode-to-android-studio-tab" href="#from-vscode-to-android-studio" role="tab" aria-controls="from-vscode-to-android-studio" aria-selected="true">Start from VS Code</a>
-    </li>
-    <li class="nav-item">
-        <a class="nav-link" id="from-android-studio-to-vscode-tab" href="#from-android-studio-to-vscode" role="tab" aria-controls="from-android-studio-to-vscode" aria-selected="false">Start from Android Studio</a>
-    </li>
-</ul>
 
-{% comment %} Tab panes {% endcomment -%}
-<div class="tab-content">
-
-<div class="tab-pane active" id="from-vscode-to-android-studio" role="tabpanel" aria-labelledby="from-vscode-to-android-studio-tab">
+{% tabs %}
+{% tab "Start from VS Code" %}
 
 #### Start debugging with VS Code first {:#from-vscode-to-android-studio}
 
@@ -46,9 +35,8 @@ If you use VS Code to debug most of your code, start with this section.
 
 {% include docs/debug/debug-android-attach-process.md %}
 
-</div>
-
-<div class="tab-pane" id="from-android-studio-to-vscode" role="tabpanel" aria-labelledby="from-android-studio-to-vscode-tab">
+{% endtab %}
+{% tab "Start from Android Studio" %}
 
 #### Start debugging with Android Studio first {:#from-android-studio}
 
@@ -58,6 +46,5 @@ If you use Android Studio to debug most of your code, start with this section.
 
 {% include docs/debug/debug-android-attach-process.md %}
 
-</div>
-</div>
-{% comment %} End: Tab panes. {% endcomment -%}
+{% endtab %}
+{% endtabs %}
diff --git a/src/_includes/docs/debug/debug-flow-ios.md b/src/_includes/docs/debug/debug-flow-ios.md
@@ -12,20 +12,8 @@ Warning: Building for device with codesigning disabled. You will have to manuall
 Building com.example.myApp for device (ios)...
 ```
 
-{% comment %} Nav tabs {% endcomment -%}
-<ul class="nav nav-tabs" id="vscode-to-xcode-ios-setup" role="tablist">
-    <li class="nav-item">
-        <a class="nav-link active" id="from-vscode-to-xcode-ios-tab" href="#from-vscode-to-xcode-ios" role="tab" aria-controls="from-vscode-to-xcode-ios" aria-selected="true">Start from VS Code</a>
-    </li>
-    <li class="nav-item">
-        <a class="nav-link" id="from-xcode-ios-tab" href="#from-xcode-ios" role="tab" aria-controls="from-xcode-ios" aria-selected="false">Start from Xcode</a>
-    </li>
-</ul>
-
-{% comment %} Tab panes {% endcomment -%}
-<div class="tab-content">
-
-<div class="tab-pane active" id="from-vscode-to-xcode-ios" role="tabpanel" aria-labelledby="from-vscode-to-xcode-ios-tab">
+{% tabs "darwin-debug-flow" %}
+{% tab "Start from VS Code" %}
 
 #### Start debugging with VS Code first {:#vscode-ios}
 
@@ -45,9 +33,8 @@ To attach to the Flutter app in Xcode:
 1. Select **Runner**. It should be at the top of the
    **Attach to Process** menu under the **Likely Targets** heading.
 
-</div>
-
-<div class="tab-pane" id="from-xcode-ios" role="tabpanel" aria-labelledby="from-xcode-ios-tab">
+{% endtab %}
+{% tab "Start from Xcode" %}
 
 #### Start debugging with Xcode first {:#xcode-ios}
 
@@ -115,6 +102,5 @@ If you use Xcode to debug most of your code, start with this section.
     ![Alt text](/assets/images/docs/testing/debugging/vscode-ui/screens/vscode-add-attach-uri-filled.png)
 {% endcomment %}
 
-</div>
-</div>
-{% comment %} End: Tab panes. {% endcomment -%}
+{% endtab %}
+{% endtabs %}
diff --git a/src/_includes/docs/debug/debug-flow-macos.md b/src/_includes/docs/debug/debug-flow-macos.md
@@ -11,20 +11,8 @@ flutter build macos --debug
 Building macOS application...
 ```
 
-{% comment %} Nav tabs {% endcomment -%}
-<ul class="nav nav-tabs" id="vscode-to-xcode-macos-setup" role="tablist">
-    <li class="nav-item">
-        <a class="nav-link active" id="from-vscode-to-xcode-macos-tab" href="#from-vscode-to-xcode-macos" role="tab" aria-controls="from-vscode-to-xcode-macos" aria-selected="true">Start from VS Code</a>
-    </li>
-    <li class="nav-item">
-        <a class="nav-link" id="from-xcode-macos-tab" href="#from-xcode-macos" role="tab" aria-controls="from-xcode-macos" aria-selected="false">Start from Xcode</a>
-    </li>
-</ul>
-
-{% comment %} Tab panes {% endcomment -%}
-<div class="tab-content">
-
-<div class="tab-pane active" id="from-vscode-to-xcode-macos" role="tabpanel" aria-labelledby="from-vscode-to-xcode-macos-tab">
+{% tabs "darwin-debug-flow" %}
+{% tab "Start from VS Code" %}
 
 #### Start debugging with VS Code first {:#vscode-macos}
 
@@ -42,9 +30,8 @@ Building macOS application...
    **Runner** should be at the top of the **Attach to Process** menu
    under the **Likely Targets** heading.
 
-</div>
-
-<div class="tab-pane" id="from-xcode-macos" role="tabpanel" aria-labelledby="from-xcode-macos-tab">
+{% endtab %}
+{% tab "Start from Xcode" %}
 
 #### Start debugging with Xcode first {:#xcode-macos}
 
@@ -95,6 +82,5 @@ Building macOS application...
    ![Alt text](/assets/images/docs/testing/debugging/vscode-ui/screens/vscode-add-attach-uri-filled.png)
 {% endcomment %}
 
-</div>
-</div>
-{% comment %} End: Tab panes. {% endcomment -%}
+{% endtab %}
+{% endtabs %}
diff --git a/src/_includes/docs/debug/debug-flow-windows.md b/src/_includes/docs/debug/debug-flow-windows.md
@@ -12,20 +12,8 @@ Building Windows application...                                    31.4s
 √  Built build\windows\runner\Debug\my_app.exe.
 ```
 
-{% comment %} Nav tabs {% endcomment -%}
-<ul class="nav nav-tabs" id="vscode-to-vs-setup" role="tablist">
-    <li class="nav-item">
-        <a class="nav-link active" id="from-vscode-to-vs-tab" href="#from-vscode-to-vs" role="tab" aria-controls="from-vscode-to-vs" aria-selected="true">Start from VS Code</a>
-    </li>
-    <li class="nav-item">
-        <a class="nav-link" id="from-vs-to-vscode-tab" href="#from-vs-to-vscode" role="tab" aria-controls="from-vs-to-vscode" aria-selected="false">Start from Visual Studio</a>
-    </li>
-</ul>
-
-{% comment %} Tab panes {% endcomment -%}
-<div class="tab-content">
-
-<div class="tab-pane active" id="from-vscode-to-vs" role="tabpanel" aria-labelledby="from-vscode-to-vs-tab">
+{% tabs %}
+{% tab "Start from VS Code" %}
 
 #### Start debugging with VS Code first {:#vscode-windows}
 
@@ -81,9 +69,8 @@ If you use VS Code to debug most of your code, start with this section.
    ![Visual Studio debugger running and monitoring the Flutter app](/assets/images/docs/testing/debugging/native/visual-studio/debugger-active.png){:width="100%"}
 {% endcomment %}
 
-</div>
-
-<div class="tab-pane" id="from-vs-to-vscode" role="tabpanel" aria-labelledby="from-vs-to-vscode-tab">
+{% endtab %}
+{% tab "Start from Visual Studio" %}
 
 #### Start debugging with Visual Studio first
 
@@ -150,6 +137,5 @@ If you use Visual Studio to debug most of your code, start with this section.
    ![Alt text](/assets/images/docs/testing/debugging/vscode-ui/screens/vscode-add-attach-uri-filled.png)
 {% endcomment %}
 
-</div>
-</div>
-{% comment %} End: Tab panes. {% endcomment -%}
+{% endtab %}
+{% endtabs %}