Merge pull request #451 from CrowCpp/webpage_tutorial

Webpage tutorial
CrowCpp · Jun 10, 2022 · 53a2921 · 53a2921
2 parents c37664f + 9b4e741
commit 53a2921
Show file tree

Hide file tree

Showing 8 changed files with 141 additions and 74 deletions.
diff --git a/docs/getting_started/a_simple_webpage.md b/docs/getting_started/a_simple_webpage.md
@@ -0,0 +1,129 @@
+Hello World is a good start, but what if you want something a bit more fancy.. Something like an HTML document saying "Hello World". If that's what you want, follow along:
+
+## Basic Webpage
+Let's start our webpage with.. well.. a webpage. But before we create a webpage we need to place it somewhere Crow recognizes, for now this directory is going to be called `templates`, but we can [change it later](../../guides/templating/#page).
+
+Once our `templates` folder is created, we can create our HTML document inside it, let's call it `fancypage.html`.
+
+After that we can just place something simple inside it like:
+``` html title="templates/fancypage.html"
+<!DOCTYPE html>
+<html>
+  <body>
+  <p>Hello World!</p>
+  </body>
+</html>
+```
+<br>
+Now that we have our HTML page ready, let's take our Hello World example from earlier:
+``` cpp linenums="1"
+#include "crow.h"
+//#include "crow_all.h"
+
+int main()
+{
+    crow::SimpleApp app; //define your crow application
+
+    //define your endpoint at the root directory
+    CROW_ROUTE(app, "/")([](){
+        return "Hello world";
+    });
+
+    //set the port, set the app to run on multiple threads, and run the app
+    app.port(18080).multithreaded().run();
+}
+```
+<br>
+
+And now let's modify it so that it returns our cool page:
+``` cpp title="/main.cpp" linenums="1" hl_lines="10 11"
+#include "crow.h"
+//#include "crow_all.h"
+
+int main()
+{
+    crow::SimpleApp app;
+
+    //define your endpoint at the root directory
+    CROW_ROUTE(app, "/")([](){
+        auto page = crow::mustache::load_text("fancypage.html");
+        return page;
+    });
+
+    app.port(18080).multithreaded().run();
+}
+```
+
+Your project should look something something like:
+```
+./
+ |-templates/
+ |          |-fancypage.html
+ |
+ |-main.cpp
+ |-crow_all.h
+```
+or
+```
+./
+ |-templates/
+ |          |-fancypage.html
+ |
+ |-crow/
+ |     |-include/...
+ |     |-crow.h
+ |-main.cpp
+```
+
+
+Once the code is done compiling, if we call `http://localhost:18080/` we get our Hello World in an HTML document rather than just plain text.
+
+!!! note
+
+    Compilation instructions are available for [Linux](../setup/linux#compiling-your-project), [MacOS](../setup/macos#compiling-using-a-compiler-directly), and [Windows](../setup/windows#getting-and-compiling-crow)
+
+
+## Template Webpage with a variable
+But we can make things even more exciting, we can greet a user by their name instead!!
+
+Let's start with our webpage, and modify it with a little bit of [mustache](../../guides/templating) syntax:
+``` html title="templates/fancypage.html" hl_lines="4"
+<!DOCTYPE html>
+<html>
+  <body>
+  <p>Hello {{person}}!</p> <!--(1)-->
+  </body>
+</html>
+```
+
+1. `{{}}` in mustache define a simple variable
+
+<br>
+Now let's modify our C++ code to use the variable we just added to our webpage (or template):
+``` cpp title="/main.cpp" linenums="1" hl_lines="9-12"
+#include "crow.h"
+//#include "crow_all.h"
+
+int main()
+{
+    crow::SimpleApp app;
+
+    //define your endpoint at the root directory
+    CROW_ROUTE(app, "/<string>")([](std::string name){ // (1)
+        auto page = crow::mustache::load("fancypage.html"); // (2)
+        crow::mustache::context ctx ({{"person", name}}); // (3)
+        return page.render(ctx); //(4)
+    });
+
+    app.port(18080).multithreaded().run();
+}
+```
+
+1. We are adding a `string` variable to the URL and a counterpart (`std::string name`) to our Route, this can be anything the user wants.
+2. We are using `load()` instead of `load_text()` since we have an actual variable now.
+3. We are creating a new [context](../../guides/templating/#context) containing the `person` variable from our template and the `name` we got from the URL.
+4. we are using `render(ctx)` to apply our context to the template.
+
+Now (after compiling the code and running the executable a second time) calling `http://localhost:18080/Bob` should return a webpage containing "Hello Bob!". **We did it!**
+
+For more details on templates and HTML pages in Crow please go [here](../../guides/templating/)
diff --git a/docs/getting_started/your_first_application.md b/docs/getting_started/your_first_application.md
@@ -38,7 +38,7 @@ Please note that the `port()` and `multithreaded()` methods aren't needed, Thoug
 
 Once you've followed all the steps above, your code should look similar to this
 
-``` cpp linenums="1"
+``` cpp title="main.cpp" linenums="1"
 #include "crow.h"
 //#include "crow_all.h"
 
@@ -55,4 +55,7 @@ int main()
     app.port(18080).multithreaded().run();
 }
 ```
-After building and running your .cpp file, you should be able to access your endpoint at [http://localhost:18080](http://localhost:18080). Opening this URL in your browser will show a white screen with "Hello world" typed on it.
+
+You then need to compile your code on your [Linux](../setup/linux#compiling-your-project), [MacOS](../setup/macos#compiling-using-a-compiler-directly), or [Windows](../setup/windows#getting-and-compiling-crow) machine
+
+After building your `.cpp` file and running the resulting executable, you should be able to access your endpoint at [http://localhost:18080](http://localhost:18080). Opening this URL in your browser will show a white screen with "Hello world" typed on it.
diff --git a/docs/overrides/partials/footer.html b/docs/overrides/partials/footer.html
@@ -94,7 +94,7 @@
     <div class="md-footer-meta__inner md-grid">
 
       <!-- Copyright and theme information -->
-      <div class="md-footer-copyright">
+      <div class="md-footer-copyright" style="flex: 1;display: flex;justify-content: left;">
         {% if config.copyright %}
           <div class="md-footer-copyright__highlight">
             {{ config.copyright }}
@@ -103,7 +103,7 @@
         {{ extracopyright }}
       </div>
 
-      <a style="margin: auto .6rem; font-size: .64rem;" href="/privacy_policy.html">Privacy Policy</a>
+      <a style="margin: auto .6rem; font-size: .64rem;text-align: center;flex: 1;display: flex;justify-content: center;" href="/privacy_policy.html">Privacy Policy</a>
 
       <!-- Social links -->
       {% include "partials/social.html" %}

diff --git a/docs/stylesheets/colors.css b/docs/stylesheets/colors.css
@@ -35,6 +35,8 @@
     --home-border-color: #ffffff20;
     --home-shadow-color: #00000040;
     --home-image-border: linear-gradient(90deg, rgba(255, 255, 255, 0) 0%, rgba(255, 255, 255, 0.3) 50%, rgba(255, 255, 255, 0) 100%);
+    --md-admonition-bg-color: #272a2b;
+    --md-code-hl-color: rgba(255, 255, 0, 0.18);
 
 }
 

diff --git a/examples/CMakeLists.txt b/examples/CMakeLists.txt
@@ -38,12 +38,6 @@ add_custom_target(example_ws_copy ALL DEPENDS ws.html)
 add_executable(basic_example example.cpp)
 add_warnings_optimizations(basic_example)
 target_link_libraries(basic_example PUBLIC Crow::Crow)
-add_custom_command(OUTPUT example_test.py
-  COMMAND ${CMAKE_COMMAND} -E
-  copy ${PROJECT_SOURCE_DIR}/example_test.py ${CMAKE_CURRENT_BINARY_DIR}/example_test.py
-  DEPENDS ${PROJECT_SOURCE_DIR}/example_test.py
-)
-add_custom_target(example_copy ALL DEPENDS example_test.py)
 
 if(CROW_AMALGAMATE)
   add_executable(example_with_all example_with_all.cpp)

diff --git a/examples/example.py b/examples/example.py
diff --git a/examples/example_test.py b/examples/example_test.py
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -11,7 +11,8 @@ theme:
   font: false
   language: 'en'
   features:
-    navigation.tabs
+    - navigation.tabs
+    - content.code.annotate
   favicon: 'assets/favicon.svg'
   logo: 'assets/favicon.svg'
   icon:
@@ -54,6 +55,7 @@ nav:
       - MacOS: getting_started/setup/macos.md
       - Windows: getting_started/setup/windows.md
     - Your First Application: getting_started/your_first_application.md
+    - A simple Webpage: getting_started/a_simple_webpage.md
   - Guides:
     - Different parts of Crow:
       - App: guides/app.md