examples: Improve webpage generation in various ways, add thumbnails, etc.

build-scripts/build-web-examples.pl

@@ -71,17 +71,41 @@ sub build_latest {
     }
 }
 
+sub get_category_description {
+    my $category = shift;
+    my $retval = ucfirst($category);
+
+    if (open(my $fh, '<', "$examples_dir/$category/description.txt")) {
+        $retval = <$fh>;
+        chomp($retval);
+        close($fh);
+    }
+
+    return $retval;
+}
+
 sub get_categories {
     my @categories = ();
 
-    opendir(my $dh, $examples_dir) or die("Couldn't opendir '$examples_dir': $!\n");
-    foreach my $dir (sort readdir $dh) {
-        next if ($dir eq '.') || ($dir eq '..');  # obviously skip current and parent entries.
-        next if not -d "$examples_dir/$dir";   # only care about subdirectories.
-
-        push @categories, $dir;
+    if (open(my $fh, '<', "$examples_dir/categories.txt")) {
+        while (<$fh>) {
+            chomp;
+            s/\A\s+//;
+            s/\s+\Z//;
+            next if $_ eq '';
+            next if /\A\#/;
+            push @categories, $_;
+        }
+        close($fh);
+    } else {
+        opendir(my $dh, $examples_dir) or die("Couldn't opendir '$examples_dir': $!\n");
+        foreach my $dir (sort readdir $dh) {
+            next if ($dir eq '.') || ($dir eq '..');  # obviously skip current and parent entries.
+            next if not -d "$examples_dir/$dir";   # only care about subdirectories.
+            push @categories, $dir;
+        }
+        closedir($dh);
     }
-    closedir($dh);
 
     return @categories;
 }
@@ -131,10 +155,16 @@ sub handle_example_dir {
     $basefname = "$category-$basefname";
     my $jsfname = "$basefname.js";
     my $wasmfname = "$basefname.wasm";
+    my $thumbnailfname = 'thumbnail.png';
+    my $onmouseoverfname = 'onmouseover.webp';
     my $jssrc = "$compile_dir/examples/$jsfname";
     my $wasmsrc = "$compile_dir/examples/$wasmfname";
+    my $thumbnailsrc = "$examples_dir/$category/$example/$thumbnailfname";
+    my $onmouseoversrc = "$examples_dir/$category/$example/$onmouseoverfname";
     my $jsdst = "$dst/$jsfname";
     my $wasmdst = "$dst/$wasmfname";
+    my $thumbnaildst = "$dst/$thumbnailfname";
+    my $onmouseoverdst = "$dst/$onmouseoverfname";
 
     my $description = '';
     if (open(my $readmetxth, '<', "$examples_dir/$category/$example/README.txt")) {
@@ -150,6 +180,8 @@ sub handle_example_dir {
     do_mkdir($dst);
     do_copy($jssrc, $jsdst);
     do_copy($wasmsrc, $wasmdst);
+    do_copy($thumbnailsrc, $thumbnaildst) if ( -f $thumbnailsrc );
+    do_copy($onmouseoversrc, $onmouseoverdst) if ( -f $onmouseoversrc );
 
     my $highlight_cmd = "highlight '--outdir=$dst' --style-outfile=highlight.css --fragment --enclose-pre --stdout --syntax=c '--plug-in=$examples_dir/highlight-plugin.lua'";
     print("$highlight_cmd\n");
@@ -184,11 +216,14 @@ sub handle_example_dir {
     }
     $other_examples_html .= "</ul>";
 
+    my $category_description = get_category_description($category);
+
     my $html = '';
     open my $htmltemplate, '<', "$examples_dir/template.html" or die("Couldn't open '$examples_dir/template.html': $!\n");
     while (<$htmltemplate>) {
         s/\@project_name\@/$project/g;
         s/\@category_name\@/$category/g;
+        s/\@category_description\@/$category_description/g;
         s/\@example_name\@/$example/g;
         s/\@javascript_file\@/$jsfname/g;
         s/\@htmlified_source_code\@/$htmlified_source_code/g;
@@ -203,6 +238,51 @@ sub handle_example_dir {
     close($htmloutput);
 }
 
+sub generate_example_thumbnail {
+    my $project = shift;
+    my $category = shift;
+    my $example = shift;
+
+    my $example_no_num = "$example";
+    $example_no_num =~ s/\A\d+\-//;
+
+    my $example_image_url;
+    if ( -f "$examples_dir/$category/$example/thumbnail.png" ) {
+        $example_image_url = "/$project/$category/$example/thumbnail.png";
+    } elsif ( -f "$examples_dir/$category/thumbnail.png" ) {
+        $example_image_url = "/$project/$category/thumbnail.png";
+    } else {
+        $example_image_url = "/$project/thumbnail.png";
+    }
+
+    my $example_mouseover_html = '';
+    if ( -f "$examples_dir/$category/$example/onmouseover.webp" ) {
+        $example_mouseover_html = "onmouseover=\"this.src='/$project/$category/$example/onmouseover.webp'\" onmouseout=\"this.src='$example_image_url'\";";
+    } elsif ( -f "$examples_dir/$category/onmouseover.webp" ) {
+        $example_mouseover_html = "onmouseover=\"this.src='/$project/$category/onmouseover.webp'\" onmouseout=\"this.src='$example_image_url'\";";
+    }
+
+    return "
+        <a href='/$project/$category/$example'>
+          <div>
+            <img src='$example_image_url' $example_mouseover_html />
+            <div>$example_no_num</div>
+          </div>
+        </a>"
+    ;
+}
+
+sub generate_example_thumbnails_for_category {
+    my $project = shift;
+    my $category = shift;
+    my @examples = get_examples_for_category($category);
+    my $retval = '';
+    foreach my $example (@examples) {
+        $retval .= generate_example_thumbnail($project, $category, $example);
+    }
+    return $retval;
+}
+
 sub handle_category_dir {
     my $category = shift;
 
@@ -220,26 +300,22 @@ sub handle_category_dir {
 
     closedir($dh);
 
-    my $examples_list_html = "";
-    foreach my $example (get_examples_for_category($category)) {
-        # !!! FIXME: image
-        my $example_image_url = "/$project/placeholder.png";
-        $examples_list_html .= "
-        <a href='/$project/$category/$example'>
-          <div>
-            <img src='$example_image_url' />
-            <div>$category/$example</div>
-          </div>
-        </a>";
-    }
+    my $examples_list_html = generate_example_thumbnails_for_category($project, $category);
 
-    # write category page
     my $dst = "$output_dir/$category";
+
+    do_copy("$examples_dir/$category/thumbnail.png", "$dst/thumbnail.png") if ( -f "$examples_dir/$category/thumbnail.png" );
+    do_copy("$examples_dir/$category/onmouseover.webp", "$dst/onmouseover.webp") if ( -f "$examples_dir/$category/onmouseover.webp" );
+
+    my $category_description = get_category_description($category);
+
+    # write category page
     my $html = '';
     open my $htmltemplate, '<', "$examples_dir/template-category.html" or die("Couldn't open '$examples_dir/template-category.html': $!\n");
     while (<$htmltemplate>) {
         s/\@project_name\@/$project/g;
         s/\@category_name\@/$category/g;
+        s/\@category_description\@/$category_description/g;
         s/\@examples_list_html\@/$examples_list_html/g;
         $html .= $_;
     }
@@ -276,7 +352,7 @@ do_mkdir($output_dir);
 build_latest();
 
 do_copy("$examples_dir/template.css", "$output_dir/examples.css");
-do_copy("$examples_dir/template-placeholder.png", "$output_dir/placeholder.png");
+do_copy("$examples_dir/template-placeholder.png", "$output_dir/thumbnail.png");
 
 opendir(my $dh, $examples_dir) or die("Couldn't opendir '$examples_dir': $!\n");
 
@@ -292,19 +368,10 @@ closedir($dh);
 # write homepage
 my $homepage_list_html = "";
 foreach my $category (get_categories()) {
-    $homepage_list_html .= "<h2>$category</h2>";
+    my $category_description = get_category_description($category);
+    $homepage_list_html .= "<h2>$category_description</h2>";
     $homepage_list_html .= "<div class='list'>";
-    foreach my $example (get_examples_for_category($category)) {
-        # !!! FIXME: image
-        my $example_image_url = "/$project/placeholder.png";
-        $homepage_list_html .= "
-            <a href='/$project/$category/$example'>
-            <div>
-                <img src='$example_image_url' />
-                <div>$category/$example</div>
-            </div>
-            </a>";
-    }
+    $homepage_list_html .= generate_example_thumbnails_for_category($project, $category);
     $homepage_list_html .= "</div>";
 }
 

examples/asyncio/description.txt

@@ -0,0 +1 @@
+Asynchronous I/O

examples/categories.txt

@@ -0,0 +1,13 @@
+# Blank lines and lines that start with '#' in this file are ignored.
+
+# Categories, by directory name, go in here, in the order they should be
+# listed on the main page. If this file is missing, it'll assume any
+# subdirectory is a category and sort them alphabetically.
+
+renderer
+input
+audio
+camera
+asyncio
+pen
+demo

examples/demo/description.txt

@@ -0,0 +1 @@
+Full game and app demos

examples/template-category.html

@@ -4,7 +4,7 @@
     <meta charset="utf-8" />
     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>@project_name@ Examples: @category_name@</title>
+    <title>@project_name@ Examples: @category_description@</title>
     <link
       rel="stylesheet"
       type="text/css"
@@ -18,7 +18,7 @@
   </head>
   <body>
     <header>
-      <a href="/">SDL Examples</a>
+      <a href="/">@project_name@ Examples</a>
     </header>
     <main>
       <nav class="breadcrumb">
@@ -27,7 +27,7 @@
           <li><a href="/@project_name@/@category_name@">@category_name@</a></li>
         </ul>
       </nav>
-      <h1>@project_name@ examples: @category_name@</h1>
+      <h1>@project_name@ examples: @category_description@</h1>
       <div class="list">@examples_list_html@</div>
     </main>
   </body>

examples/template-homepage.html

@@ -28,8 +28,6 @@
       </nav>
       <h1>@project_name@ examples</h1>
 
-      <p>Check out the @project_name@ examples here!</p>
-
       @homepage_list_html@
     </main>
   </body>