mainpage.dox

/*! @mainpage WebFrame++ v3
@htmlonly
<link rel="stylesheet" href="./Doxygen-css/custom.css">
<link rel="stylesheet" href="./Doxygen-css/custom_dark_theme.css">

<h3 id="makeyourwebapplicationfasternow">Make your web application faster now!</h3>

<hr>

<h4 id="requirements">Requirements</h4>

<p>
  <table class="fieldtable">
    <tr><th class="fieldname">Compiler version</th><th class="fieldname">Minimum C++ standard required</th></tr>
    <tr><td class="fieldname">GCC, Clang, MinGW, MSVC   </td><td class="fieldname">-std=c++2a <i>-std=c++20</i></td></tr>
  </table>
</p>

<h1 id="testing">Testing</h1>

<h2 id="cppcheckstaticcodeanalysis">Cppcheck - static code analysis</h2>

<p>Check the static code analysis of the project <a href="https://webframe.github.io/Core/codeql_report/">here</a>.</p>

<h2 id="performance">Performance</h2>

<p>Check the performance check of the project <a href="https://webframe.github.io/Core/benchmark/">here</a>.</p>

<h2 id="codedocumentation">Code documentation</h2>

<p>Check the Doxygen documentation of the library <a href="https://webframe.github.io/Core/docs/">here</a>.</p>

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.6.0/styles/monokai-sublime.min.css">
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.6.0/styles/androidstudio.min.css">
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.6.0/highlight.min.js"></script>

<h1 id="howtouse">How to use</h1>

<ol>
<li><p>Make sure to include the library</p>

<pre><code class="cpp language-cpp">#include &lt;core/webframe.hpp&gt;
</code></pre></li>

<li><p>Initiate your Web application</p>

<pre><code class="cpp language-cpp">webframe::core::application app;
</code></pre>

<p></p></li>

<li><p>Set directories for your static files</p>

<pre><code class="cpp language-cpp">app.set_static(relative or absolute path/directory to the static files, web alias); 
</code></pre>

<p>Ex. the files are in <code>./example/Sample/static</code> and the route for them is <code>/static</code>:</p>

<pre><code class="cpp language-cpp">app.set_static("./example/Sample/static", "/static"); 
</code></pre>

<p><em><strong>NOTE:</strong> You can list multiple static folders</em></p>

<p><em><strong>NOTE:</strong> Relative paths depend on where you execute the executable from and not on where the source file is located.</em></p></li>

<li><p>Set Inja template folder</p>

<pre><code class="cpp language-cpp">app.set_templates(relative or absolute path/directory to the INJA templates); 
</code></pre>

<p>Ex. the Inja template files are in <code>./example/Sample/static/templates</code>:</p>

<pre><code class="cpp language-cpp">app.set_templates("./example/Sample/static/templates");
</code></pre>

<p><em><strong>NOTE:</strong> You can list multiple template folders</em></p>

<p><em><strong>NOTE:</strong> Relative paths depend on where you execute the executable from and not on where the source file is located.</em></p></li>

<li><p>Set up error handling</p>

<ul>
<li><p>Set the code of the error</p></li>

<li><p>Implement the responding function using lambda that takes 1 string as parameter</p>

<pre><code class="cpp language-cpp">app.handle("404", [](const std::string&amp; path) {
    return "Error 404: " + path + " was not found.";
});
app.handle("500", [](const std::string&amp; reason) {
    return "Error 500: Internal server error: " + reason + ".";
});
</code></pre></li></ul></li>

<li><p>Set up your routes</p>

<ul>
<li><p>Set up headers and status code yourself</p>

<pre><code class="cpp language-cpp">app.route ("/", []() {
    return webframe::core::response (webframe::core::status_line ("1.1", "200"), {{"Content-Type", "text/html; charset=utf-8"}}, "&lt;h1&gt;Hello, World!&lt;/h1&gt;");
});
</code></pre></li>

<li><p>or let WebFrame do it for you</p>

<pre><code class="cpp language-cpp">app.route ("/", []() {
    return "&lt;h1&gt;Hello, World!&lt;/h1&gt;";
});
</code></pre></li>

<li><p>To render your Jinja templates use <code>app.render(filename/file path, json with variables)</code></p></li>

<li><p>You can also use path/route variables </p>

<ul>
<li><p>using predefined regex</p>

<pre><code class="cpp language-cpp">app.route("/{text}", [&amp;app](const std::string&amp; user) {
    return app.render("template.html", {{"username", user}});
});
</code></pre>

<p>
<table class="fieldtable">
<tr><th class="fieldname">Predefined </th><th class="fieldname">Raw regex equivalent </th></tr>
<tr><td class="fieldname">string     </td><td class="fieldname">[A-Za-z_%0-9.-]+  </td></tr>
<tr><td class="fieldname">text       </td><td class="fieldname">[A-Za-z_%0-9.-]+ </td></tr>
<tr><td class="fieldname">char       </td><td class="fieldname">[A-Za-z_%0-9.-]   </td></tr>
<tr><td class="fieldname">symbol     </td><td class="fieldname">[A-Za-z_%0-9.-]  </td></tr>
<tr><td class="fieldname">digit      </td><td class="fieldname">[0-9]                </td></tr>
<tr><td class="fieldname">number     </td><td class="fieldname">[0-9.]+              </td></tr>
<tr><td class="fieldname">path       </td><td class="fieldname">[A-Za-z_%0-9.-\/]+   </td></tr>
</table>
</p></li>

<li><p>or using your own regex</p>
<pre><code class="cpp language-cpp">app.route("/{[a-z]+}", [&amp;app](const std::string&amp; user) {
    return app.render("template.html", {{"username", user}});
});
</code></pre></li></ul></li></ul></li>

<li><p>Make sure to run your app (async run)</p>

<pre><code class="cpp language-cpp">app.run(port, cores);
</code></pre></li>
</ol>

<h2 id="advancedusage">Advanced usage</h2>

<ol>
<li><p>Stack multiple setups</p>

<p>You can list different app setups consequently:</p>

<pre><code class="cpp language-cpp">app.set_static("./example/Sample/static", "/static")
    .set_templates("./example/Sample/static/templates")
    .handle("404", [](const std::string&amp; path) {
        return "Error 404: " + path + " was not found.";
    })
    .handle("500", [](const std::string&amp; reason) {
        return "Error 500: Internal server error: " + reason + ".";
    })
    .route ("/", []() {
        return webframe::core::response (webframe::core::status_line ("1.1", "200"), {{"Content-Type", "text/html; charset=utf-8"}}, "&lt;h1&gt;Hello, World!&lt;/h1&gt;");
    });
</code></pre></li>

<li><p>Multithreading</p>

<ul>
<li><p>Wait until the server starts accepting requests: (sync function)</p>

<pre><code class="cpp language-cpp">app.wait_start(port);
</code></pre>

<p>or</p>

<pre><code class="cpp language-cpp">app.run(port, cores).wait_start(port);
</code></pre></li>

<li><p>Wait until the server stops accepting requests: (sync function)</p>

<pre><code class="cpp language-cpp">app.wait_end(port);
</code></pre>

<p>or</p>

<pre><code class="cpp language-cpp">app.run(port, cores).wait_end(port);
</code></pre></li></ul></li>

<li><p>Set up custom loggers</p>

<ul>
<li><p>logger is the stream for standard logs from the server</p></li>

<li><p>error_logger is the stream for error messages</p></li>

<li><p>perfomancer is the stream for performance logs</p>

<pre><code class="cpp language-cpp">app.set_logger(ostream&amp;)
    .set_error_logger(ostream&amp;)
    .set_performancer(ostream&amp;);        
</code></pre></li></ul></li>

<li><p>Force server stop</p>

<pre><code class="cpp language-cpp">app.request_stop(port);
</code></pre>

<p><strong>Note:</strong> <em>port should be <code>const char*</code></em></p></li>

<li><p>Organize projects</p>

<ul>
<li><p>Create set of routes</p>

<pre><code class="cpp language-cpp">init_routes(home)
    .route("/home", []() {
        return "This is my home page";
    });
</code></pre>

<p>or if you need to use <code>webframe::core::application</code> functions</p>

<pre><code class="cpp language-cpp">webframe::core::application app;
...
init_routes(home)
    .route("/home", [&amp;app]() {
        return app.render("template.html", {{"username", user}});
    });
</code></pre></li>

<li><p>Import the set of routes to your app</p>

<pre><code class="cpp language-cpp">init_routes(home)
...
app.extend_with(home);
</code></pre>

<p>or if you want to add prefix to the set of routes</p>

<pre><code class="cpp language-cpp">init_routes(home)
...
app.extend_with(home, "/prefix");
</code></pre></li></ul></li>
</ol>

<p>Check <a href="https://github.com/WebFrame/Core/blob/master/example">example/</a> for more information.</p>

<h1 id="additionalinfo">Additional info</h1>

<ul>
<li>Currently working on setting up <img src="https://img.shields.io/badge/CMake-%23008FBA.svg?&amp;logo=cmake&amp;logoColor=while" alt="CMake" /></li>
</ul>

<h1 id="socials">Socials</h1>

<p><a href="https://www.linkedin.com/in/alex-tsvetanov/"><img src="https://img.shields.io/badge/linkedin-%230077B5.svg?logo=linkedin&amp;logoColor=white" alt="LinkedIn" /></a></p>

<script>
    document.addEventListener('DOMContentLoaded', (event) => {
      document.querySelectorAll('pre code').forEach((el) => {
        hljs.highlightElement(el);
      });
    });
</script>
@endhtmlonly
*/