Crow/docs/guides/static.md

<span class="tag">[:octicons-feed-tag-16: v0.2](https://github.com/CrowCpp/Crow/releases/0.2)</span>


A static file is any file that resides in the server's storage.

Crow supports returning static files as responses either implicitly or explicitly.

## Implicit
Crow implicitly returns any static files placed in a `static` directory and any subdirectories, as long as the user calls the endpoint `/static/path/to/file`.<br><br>
The static folder or endpoint can be changed by defining the macros `CROW_STATIC_DIRECTORY "alternative_directory/"` and `CROW_STATIC_ENDPOINT "/alternative_endpoint/<path>"`.<br>
static directory changes the directory in the server's file system, while the endpoint changes the URL that the client needs to access.

## Explicit
You can directly return a static file by using the `crow::response` method `#!cpp response.set_static_file_info("path/to/file");`. The path is relative to the working directory.

!!! Warning

    The path to the file is sanitized by default. it should be fine for most circumstances but if you know what you're doing and need the sanitizer off you can use `#!cpp response.set_static_file_info_unsafe("path/to/file")` instead.

!!! note

    Crow sets the `content-type` header automatically based on the file's extension, if an extension is unavailable or undefined,  Crow uses `text/plain`, if you'd like to explicitly set a `content-type`, use `#!cpp response.set_header("content-type", "mime/type");` **AFTER** calling `set_static_file_info`.

!!! note

    Please keep in mind that using the `set_static_file_info` method means any data already in your response body is ignored and not sent to the client.
improved "introduced in" statements 2022-05-12 21:49:52 +00:00			`<span class="tag">[:octicons-feed-tag-16: v0.2](https://github.com/CrowCpp/Crow/releases/0.2)</span>`


Changed documentation. a lot. Added mkdocs documentation. Altered doxygen generation (doxyfile and shell script) to work with mkdocs. Removed the whole html folder thing for docs, now the files reside in the root gh-pages branch. New readme. 2020-11-28 14:28:47 +00:00			`A static file is any file that resides in the server's storage.`

Fix capitalization and other minor errors 2023-05-29 06:02:05 +00:00			`Crow supports returning static files as responses either implicitly or explicitly.`
Changed documentation. a lot. Added mkdocs documentation. Altered doxygen generation (doxyfile and shell script) to work with mkdocs. Removed the whole html folder thing for docs, now the files reside in the root gh-pages branch. New readme. 2020-11-28 14:28:47 +00:00
multiple docs changes: Added meta tags for homepage Added meta description generator Removed usages of <h1> (mkdocs-material doesn't reconize more than 1) added space after # (markdown proper syntax) removed pip3 command from pull request CI 2021-11-06 08:54:29 +00:00			`## Implicit`
Changed documentation. a lot. Added mkdocs documentation. Altered doxygen generation (doxyfile and shell script) to work with mkdocs. Removed the whole html folder thing for docs, now the files reside in the root gh-pages branch. New readme. 2020-11-28 14:28:47 +00:00			Crow implicitly returns any static files placed in a `static` directory and any subdirectories, as long as the user calls the endpoint `/static/path/to/file`.<br><br>
fixed typos and added missing parts 2020-11-28 19:48:09 +00:00			The static folder or endpoint can be changed by defining the macros `CROW_STATIC_DIRECTORY "alternative_directory/"` and `CROW_STATIC_ENDPOINT "/alternative_endpoint/<path>"`.<br>
updated documentation in mkdocs and doxygen 2022-03-23 22:55:46 +00:00			`static directory changes the directory in the server's file system, while the endpoint changes the URL that the client needs to access.`
Changed documentation. a lot. Added mkdocs documentation. Altered doxygen generation (doxyfile and shell script) to work with mkdocs. Removed the whole html folder thing for docs, now the files reside in the root gh-pages branch. New readme. 2020-11-28 14:28:47 +00:00
multiple docs changes: Added meta tags for homepage Added meta description generator Removed usages of <h1> (mkdocs-material doesn't reconize more than 1) added space after # (markdown proper syntax) removed pip3 command from pull request CI 2021-11-06 08:54:29 +00:00			`## Explicit`
updated documentation in mkdocs and doxygen 2022-03-23 22:55:46 +00:00			You can directly return a static file by using the `crow::response` method `#!cpp response.set_static_file_info("path/to/file");`. The path is relative to the working directory.
Changed documentation. a lot. Added mkdocs documentation. Altered doxygen generation (doxyfile and shell script) to work with mkdocs. Removed the whole html folder thing for docs, now the files reside in the root gh-pages branch. New readme. 2020-11-28 14:28:47 +00:00
updated documentation in mkdocs and doxygen 2022-03-23 22:55:46 +00:00			`!!! Warning`

			The path to the file is sanitized by default. it should be fine for most circumstances but if you know what you're doing and need the sanitizer off you can use `#!cpp response.set_static_file_info_unsafe("path/to/file")` instead.

			`!!! note`

			Crow sets the `content-type` header automatically based on the file's extension, if an extension is unavailable or undefined, Crow uses `text/plain`, if you'd like to explicitly set a `content-type`, use `#!cpp response.set_header("content-type", "mime/type");` AFTER calling `set_static_file_info`.

			`!!! note`

			Please keep in mind that using the `set_static_file_info` method means any data already in your response body is ignored and not sent to the client.