From dd6e649205f06ef45f17c78537472bc39a4eae70 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marcus=20P=C3=B6hls?= Date: Mon, 13 Jun 2022 09:48:06 +0200 Subject: [PATCH] introduction to overview --- Sessions.md | 6 ++++++ application.md | 2 +- configuration.md | 2 +- controllers.md | 2 +- craft-console.md | 2 +- csrf-protection.md | 2 +- database.md | 2 +- decorations.md | 2 +- deployment.md | 2 +- directory-structure.md | 2 +- encryption.md | 2 +- events.md | 2 +- frontend-assets.md | 2 +- handlebars-helpers.md | 2 +- handlebars.md | 2 +- hashing.md | 2 +- http-context.md | 2 +- http-tests.md | 2 +- logger.md | 2 +- logger.org.md | 2 +- mailer.md | 2 +- middleware.md | 2 +- middleware.org.md | 2 +- pagination.md | 2 +- plugins.md | 2 +- queues.md | 2 +- request-lifecycle.md | 2 +- requests.md | 2 +- requests.org.md | 2 +- responses.md | 2 +- routing.md | 2 +- routing.org.md | 2 +- service-container.md | 2 +- service-providers.md | 2 +- session.md | 2 +- views.md | 2 +- 36 files changed, 41 insertions(+), 35 deletions(-) create mode 100644 Sessions.md diff --git a/Sessions.md b/Sessions.md new file mode 100644 index 0000000..7773d30 --- /dev/null +++ b/Sessions.md @@ -0,0 +1,6 @@ +# HTTP Sessions + + +## Overview +Tba. + diff --git a/application.md b/application.md index 617f710..eee8d9a 100644 --- a/application.md +++ b/application.md @@ -1,7 +1,7 @@ # Application -## Introduction +## Overview Every Supercharge application (HTTP and console) relies on an `Application`. The `Application` instance in Supercharge is the central place holding your app together. Each app requires a “base path” defining the app’s root directory path. This base path tells the framework from where to boot your Supercharge app. You’ll find bootstrapping files for HTTP and console applications inside of the `bootstrap` directory. Both bootstrapping files are used by the `server.ts` and `craft.ts` files (they are in the root of your app directory). Both files then start one of the following apps: diff --git a/configuration.md b/configuration.md index 67ddf29..14b6c65 100644 --- a/configuration.md +++ b/configuration.md @@ -1,7 +1,7 @@ # Configuration and Environment -## Introduction +## Overview All your Supercharge configuration files are stored in the `config` directory. Your Supercharge application and the framework core follow these configuration files. You can adjust and tweak the app’s behavior using different values for individual options. diff --git a/controllers.md b/controllers.md index 5c17d6b..ce2d71b 100644 --- a/controllers.md +++ b/controllers.md @@ -1,5 +1,5 @@ # HTTP Controllers -## Introduction +## Overview tba. diff --git a/craft-console.md b/craft-console.md index 0c956f7..af24dec 100644 --- a/craft-console.md +++ b/craft-console.md @@ -1,5 +1,5 @@ # Craft Console -## Introduction +## Overview Tba. diff --git a/csrf-protection.md b/csrf-protection.md index 2819500..2a1b00e 100644 --- a/csrf-protection.md +++ b/csrf-protection.md @@ -1,7 +1,7 @@ # CSRF Protection -## Introduction +## Overview Supercharge has support for [cross-site request forgery](https://en.wikipedia.org/wiki/Cross-site_request_forgery) (CSRF) protection. A cross-site request forgery is a malicious exploit where unauthorized commands are transmitted on behalf of an authenticated user. Supercharge ships with CSRF protection out-of-the-box. It generates a “CSRF token” for active user sessions. To use CSRF protection, you must register the session [bootstrapper](/docs/{{version}}/bootstrappers). diff --git a/database.md b/database.md index ec77786..3b3775e 100644 --- a/database.md +++ b/database.md @@ -1,5 +1,5 @@ # Database -## Introduction +## Overview tba. diff --git a/decorations.md b/decorations.md index 7c957f4..ad293fe 100644 --- a/decorations.md +++ b/decorations.md @@ -1,7 +1,7 @@ # Decorations -## Introduction +## Overview Decorations in Supercharge describe custom functionality extending the HTTP core. You’re essentially adding your own properties or methods to the core. It’s a controlled and safe way to extend three core objects in your application: - `server`: the HTTP server instance diff --git a/deployment.md b/deployment.md index 11a6c97..20341d1 100644 --- a/deployment.md +++ b/deployment.md @@ -1,7 +1,7 @@ # Deployment -## Introduction +## Overview At some point you want to deploy your Supercharge application to production. You want to serve your application as best as possible to your audience when going live. This documentation page will point you to different deployment ideas. diff --git a/directory-structure.md b/directory-structure.md index 1ff42c1..ce5d29a 100644 --- a/directory-structure.md +++ b/directory-structure.md @@ -1,7 +1,7 @@ # Directory Structure -## Introduction +## Overview Supercharge gives you a default directory structure that should work well for small and large applications. The Supercharge framework tightly integrates with the given application structure by loading files from directories in your `app` folder. Of course, you’re free to modify the application structure. Make sure to update the corresponding Node.js imports when renaming folders or moving files. diff --git a/encryption.md b/encryption.md index 930fdb5..5eea5ca 100644 --- a/encryption.md +++ b/encryption.md @@ -1,5 +1,5 @@ # Encryption -## Introduction +## Overview Encryption is not yet available in Supercharge v2. diff --git a/events.md b/events.md index aa377e4..b027391 100644 --- a/events.md +++ b/events.md @@ -1,7 +1,7 @@ # Events -## Introduction +## Overview Supercharge provides you a handy event dispatcher implementing a publish/subscribe model for events occuring in your application. Events are a great way to decouple logic in your application, for example from route handlers. For example, a user registers for your application and you want to send a welcome mail. The route handler shouldn’t wait for the mailer to send the mail. Instead, you can dispatch a `UserRegistered` event to kick off a listener sending the mail. diff --git a/frontend-assets.md b/frontend-assets.md index 1762735..1796cbb 100644 --- a/frontend-assets.md +++ b/frontend-assets.md @@ -1,7 +1,7 @@ # Frontend Assets -## Introduction +## Overview A new Supercharge applications ships with routes to serve assets. All asset-related routes are located in the `app/routes/assets.js` file. The routes defined in the `app/routes/assets.js` file have static references to the `public` directory to serve these assets publicly. The Supercharge application boilerplate has predefined folders and files to make it as seamless as possible for you to add your public assets. diff --git a/handlebars-helpers.md b/handlebars-helpers.md index 0940a51..81046ca 100644 --- a/handlebars-helpers.md +++ b/handlebars-helpers.md @@ -1,7 +1,7 @@ # Handlebars Helpers -## Introduction +## Overview The Supercharge frameworks ships with built-in [support for view rendering using Handebars templates](/docs/{{version}}/handlebars). Also, Supercharge provides you a handful of convenient helpers which are automatically registered when starting your application. You can use all helpers in your Handlebars templates without extra configuration. diff --git a/handlebars.md b/handlebars.md index 904d0f3..ff89791 100644 --- a/handlebars.md +++ b/handlebars.md @@ -1,7 +1,7 @@ # Handlebars -## Introduction +## Overview Supercharge uses the [Handlebars](https://handlebarsjs.com/) template rendering engine to translate your views into HTML. Handlebars is extensible by default allows you to build complex layouts. Starting from a base layout, you may add partial views to ultimately compose the final HTML. Supercharge supports Handlbars files using the `.hbs` file extension and automatically picks up all the view files located in the `resources/views` directory. diff --git a/hashing.md b/hashing.md index d9ea096..90438fe 100644 --- a/hashing.md +++ b/hashing.md @@ -1,5 +1,5 @@ # Hashing -## Introduction +## Overview Hashing is not yet available in Supercharge v2. diff --git a/http-context.md b/http-context.md index 466e49e..6b1885f 100644 --- a/http-context.md +++ b/http-context.md @@ -1,7 +1,7 @@ # HTTP Context -## Introduction +## Overview The HTTP context is a request-related object holding the `request` and `response` instances. You’ve access to the HTTP context in HTTP controllers (or route handler functions), middleware, and the error handler. diff --git a/http-tests.md b/http-tests.md index a1841f3..b98180f 100644 --- a/http-tests.md +++ b/http-tests.md @@ -1,7 +1,7 @@ # HTTP Tests -## Introduction +## Overview Supercharge’s `base-test` utility provides a convenient interface to inject HTTP requests to your application. Each injected request returns a response object for further evaluation. Injecting HTTP requests is a great way to run integration tests in your application. The following code snippet outlines a basic HTTP test: diff --git a/logger.md b/logger.md index 2d33f1c..db061c9 100644 --- a/logger.md +++ b/logger.md @@ -1,7 +1,7 @@ # Logging -## Introduction +## Overview Logging allows you to provide transparency in your application. If you want to learn more about the processing and details of your application parts, logging is a good way. Supercharge provides a solid logger using the [Winston](https://github.com/winstonjs/winston) logging library. Supercharge comes with a built-in logger. The logger is configurable making it seamless for you logging to different destinations, like the console or a log file. diff --git a/logger.org.md b/logger.org.md index f1303c9..0e4692d 100644 --- a/logger.org.md +++ b/logger.org.md @@ -1,7 +1,7 @@ # Logging -## Introduction +## Overview Logging allows you to provide transparency in your application. If you want to learn more about the processing and details of your application parts, logging is a good way. Supercharge provides a solid logger using the [Winston](https://github.com/winstonjs/winston) logging library. The logging utility coming with Supercharge is configurable to make it seamless for you to log to different destinations, like the console or a log file. diff --git a/mailer.md b/mailer.md index a78f61f..2f7f9cf 100644 --- a/mailer.md +++ b/mailer.md @@ -1,5 +1,5 @@ # Mailer -## Introduction +## Overview Mailing is not yet available in Supercharge v2. diff --git a/middleware.md b/middleware.md index 1b174dd..f405750 100644 --- a/middleware.md +++ b/middleware.md @@ -1,7 +1,7 @@ # Middleware -## Introduction +## Overview Tba. diff --git a/middleware.org.md b/middleware.org.md index 812b0be..75d325d 100644 --- a/middleware.org.md +++ b/middleware.org.md @@ -1,7 +1,7 @@ # Middleware -## Introduction +## Overview Middlewares are an essential mechanism in your application to filter HTTP requests. A common example is an authentication middleware letting requests proceed the request lifecycle which meet the authentication requirements. In contrast, a request that is unauthenticated will be redirected to the login screen. Based on certain conditions, requests may proceed or terminate early in the request lifecycle. diff --git a/pagination.md b/pagination.md index 2ce47a5..f1ee4eb 100644 --- a/pagination.md +++ b/pagination.md @@ -1,5 +1,5 @@ # Pagination -## Introduction +## Overview Pagination is not yet available in Supercharge v2. diff --git a/plugins.md b/plugins.md index d825e97..08e7c98 100644 --- a/plugins.md +++ b/plugins.md @@ -1,7 +1,7 @@ # Plugins -## Introduction +## Overview Supercharge supports [hapi’s](https://hapijs.com/tutorials/plugins) powerful plugin system. A plugin isolates functionality into a reusable utility. A plugin provides access to the HTTP server instance. Make use of plugins if you want to extend the HTTP server. Plugins in Supercharge are located in the `app/plugins` directory. This directory already exists in a default app installation. diff --git a/queues.md b/queues.md index 5b7466e..8f75487 100644 --- a/queues.md +++ b/queues.md @@ -1,5 +1,5 @@ # Queues -## Introduction +## Overview Queues are not yet available in Supercharge v2. diff --git a/request-lifecycle.md b/request-lifecycle.md index 2da7442..0e5c64f 100644 --- a/request-lifecycle.md +++ b/request-lifecycle.md @@ -1,7 +1,7 @@ # Request Lifecycle -## Introduction +## Overview Starting a Supercharge application via the `server.js` file serves an HTTP server. This HTTP server handles web requests. Each HTTP request to your application goes through a predefined lifecycle. It’s important to understand the request lifecycle. Supercharge uses the [hapi](https://hapijs.com) Node.js framework as its HTTP layer. A benefit of using hapi: a granular request lifecycle with extension points at individual lifecycle steps. diff --git a/requests.md b/requests.md index a1a350f..07edb0a 100644 --- a/requests.md +++ b/requests.md @@ -1,6 +1,6 @@ # HTTP Requests -## Introduction +## Overview Tba. diff --git a/requests.org.md b/requests.org.md index 28af9a3..c891721 100644 --- a/requests.org.md +++ b/requests.org.md @@ -1,7 +1,7 @@ # HTTP Requests -## Introduction +## Overview Supercharge uses the [hapi web framework](https://hapijs.com) as the core for routing and request handling. Hapi comes with a solid HTTP core and the handy feature of decorating the request object. Decorations allow you to add your own properties or functions on the `request` object. Supercharge comes with dozens of request utilities provided by the [`hapi-request-utilities`](https://github.com/futurestudio/hapi-request-utilities) package. This package is available for everyone on GitHub and NPM. Feel free to install it in your app: diff --git a/responses.md b/responses.md index ed928d7..a10a2ea 100644 --- a/responses.md +++ b/responses.md @@ -1,6 +1,6 @@ # HTTP Responses -## Introduction +## Overview Tba. diff --git a/routing.md b/routing.md index 0219bc0..0390c40 100644 --- a/routing.md +++ b/routing.md @@ -1,7 +1,7 @@ # Routing -## Introduction +## Overview Routing is an essential part of your web applictions. Each route requires a URI and route handler. The simplest way to create a route in Supercharge is to use the `Route` facade and providing the route URI and a closure function as the route handler: ```ts diff --git a/routing.org.md b/routing.org.md index 8e78d4c..79b6bbf 100644 --- a/routing.org.md +++ b/routing.org.md @@ -1,7 +1,7 @@ # Routing -## Introduction +## Overview Routes in Supercharge are JavaScript objects consisting of three basic elements: 1. the HTTP `method` diff --git a/service-container.md b/service-container.md index 0753cc7..06d050d 100644 --- a/service-container.md +++ b/service-container.md @@ -1,7 +1,7 @@ # Service Container (IoC Container) -## Introduction +## Overview Supercharge uses a service container to manage dependencies. The container allows you to register dependencies and retrieve them when needed. This setup supports dependency injection in your application. Well, dependency injection is a funky term that basically describes “injecting” dependencies into a class (or function). Injecting dependencies instead of letting classes resolve them on their own has the benefit of controlling the dependencies. Controlling dependencies is especially helpful during testing because you can inject mock objects or fake data and run assertions on them. diff --git a/service-providers.md b/service-providers.md index 2e301dc..ac66db0 100644 --- a/service-providers.md +++ b/service-providers.md @@ -1,7 +1,7 @@ # Service Providers -## Introduction +## Overview Service providers are essential when bootstrapping your application. The Supercharge framework uses service providers to load core functionalities and your application should use them as well. You may ask what “bootstrapping” actually means? In the context of a Supercharge application, it means composing your application: registering services into the container, loading routes and binding controllers, loading events and binding listeners. Service providers are a central place for your application. diff --git a/session.md b/session.md index e2de198..5be9672 100644 --- a/session.md +++ b/session.md @@ -1,5 +1,5 @@ # HTTP Sessions -## Introduction +## Overview Sessions are not yet available in Supercharge v2. diff --git a/views.md b/views.md index 1d83436..614a90c 100644 --- a/views.md +++ b/views.md @@ -1,7 +1,7 @@ # Views -## Introduction +## Overview Views separate the presentation logic from application logic and represent the web views. In your application, views are served as HTML by your server to the browser. In Supercharge, all views are located in the `resources/views` directory and its subfolders. Supercharge uses the [@hapi/vision](https://github.com/hapijs/vision) library to support template rendering. The framework is configured to use [Handlebars](/docs/{{version}}/handlebars) as the view rendering engine. Find more details on Handlebars in the linked documentation.