<commit_before>Foxx {#UserManualFoxx}
======================

@NAVIGATE_UserManualFoxx
@EMBEDTOC{UserManualFoxxTOC}

Foxx: Build APIs and simple web applications in ArangoDB{#UserManualFoxxIntro}
==============================================================================

Foxx is an easy way to create APIs and simple web applications from within ArangoDB. It is inspired by Sinatra, the classy Ruby web framework. If FoxxApplication is Sinatra, @ref UserManualActions are the corresponding `Rack`. They provide all the HTTP goodness.

If you just want to install an existiting application, please use the @ref UserManualFoxxManager. If you want to create your own application, please continue.

So let's get started, shall we?

Creating the application files
------------------------------

An application built with Foxx is written in JavaScript and deployed to ArangoDB directly. ArangoDB serves this application, you do not need a separate application server.

So given you want to build an application that sends a plain-text response "Worked!" for all requests to `/dev/meadow`.  How would you achieve that with Foxx?

First, create a directory `apps` somewhere in your filesystem. Let's assume from now on that the absolute path for this directory is `/home/user/apps`.

After that, create a sub-directory `my_app` in the `apps` directory and save the following content in a file named `app.js` there:

    var Foxx = require("org/arangodb/foxx");
    var app = new Foxx.Application(applicationContext);
    
    app.get("/meadow", function(req, res) {
      res.set("Content-Type", "text/plain");
      res.body = "Worked!"
    });

Beside the `app.js` we need a manifest file. In order to achieve that, we create a file called `manifest.json` in our `my_app` directory with the following content:

    {
      "name": "my_app",
      "version": "0.0.1",
      "author": "me and myself",
      "apps": {
        "/": "app.js"
      }
    }

You **must** specify a name and a version number for your application, otherwise it won't be loaded into ArangoDB.

You should now have the following files and directories with your application (starting at `/home/user` in our example):

    apps/
      my_app/
        manifest.json
        app.js

This is your application.

Testing the application
-----------------------

Now your application is ready to be tested. Start ArangoDB as follows:

    $ arangod --javascript.dev-app-path /home/user/apps /tmp/fancy_db

This will start the ArangoDB server in a **development mode** using the directory `/home/user/apps` as the workspace and `/tmp/fancy_db` as your database directory. Production application are installed using the Foxx manager and should not be changed. In development mode the server
automatically monitors the workspace and detects any change made to the files.

Replace `/home/user/apps` with the apps path that you initially created. This is the path that you created the `my_app` directory in. Replace `/tmp/fancy_db` with the directory your database is located in.

Now point your browser to `http://localhost:8529/dev/meadow` and you should see "Worked!". After this short overview, let's get into the details.


Handling Requests{#UserManualFoxxHandlingRequests}
==================================================

In development mode all available applications from the application directory `/home/user/apps` are visible under `http://localhost:8529/dev/DIRNAME` where `DIRNAME` is the name of the directory of your application.

When applications are installed in production mode, you can change the `/dev` prefix to whatever you like, see @ref UserManualFoxxManager.

If you do not redefine it, all requests that go to the root of your application will be redirected to `index.html`.


Details on FoxxApplication{#UserManualFoxxDetailsApplication}
=============================================================

@copydetails JSF_foxx_application_initializer

@CLEARPAGE
@copydetails JSF_foxx_application_createRepository

@CLEARPAGE
HTTP Methods
------------

@copydetails JSF_foxx_application_get

@CLEARPAGE
@copydetails JSF_foxx_application_head

@CLEARPAGE
@copydetails JSF_foxx_application_post

@CLEARPAGE
@copydetails JSF_foxx_application_put

@CLEARPAGE
@copydetails JSF_foxx_application_patch

@CLEARPAGE
@copydetails JSF_foxx_application_delete

@CLEARPAGE

Documenting and Constraining the Routes
---------------------------------------

If you define a route like described above, you have the option to match parts of the URL to variables. If you, for example, define a route `/animals/:animal` and the URL `animals/foxx` is requested it is matched by this rule. You can then get the value of this variable (in this case "foxx") by calling `request.params("animal")`.

Furthermore you can describe your API by chaining the following methods onto your path definition. With the provided information, Foxx will generate a nice documentation for you. Some of the methods additionally will check certain properties of the request.

@copydetails JSF_foxx_RequestContext_pathParam

@CLEARPAGE
@copydetails JSF_foxx_RequestContext_queryParam

@CLEARPAGE
@copydetails JSF_foxx_RequestContext_summary

@CLEARPAGE
@copydetails JSF_foxx_RequestContext_notes

@CLEARPAGE
@copydetails JSF_foxx_RequestContext_errorResponse

@CLEARPAGE

Before and After Hooks
----------------------

You can use the following two functions to do something before or respectively after the normal routing process is happening. You could use that for logging or to manipulate the request or response (translate it to a certain format for example).

@copydetails JSF_foxx_application_before

@CLEARPAGE
@copydetails JSF_foxx_application_after

@CLEARPAGE

The Request and Response Objects
--------------------------------

When you have created your FoxxApplication you can now define routes on it. You provide each with a function that will handle the request. It gets two arguments (four, to be honest. But the other two are not relevant for now):

* The `request` object
* The `response` object

These objects are provided by the underlying ArangoDB actions and enhanced by the `BaseMiddleware` provided by Foxx.
<commit_msg>Foxx: Documentation for the new Foxx Documentation Feature<commit_after>Foxx {#UserManualFoxx}
======================

@NAVIGATE_UserManualFoxx
@EMBEDTOC{UserManualFoxxTOC}

Foxx: Build APIs and simple web applications in ArangoDB{#UserManualFoxxIntro}
==============================================================================

Foxx is an easy way to create APIs and simple web applications from within ArangoDB. It is inspired by Sinatra, the classy Ruby web framework. If FoxxApplication is Sinatra, @ref UserManualActions are the corresponding `Rack`. They provide all the HTTP goodness.

If you just want to install an existiting application, please use the @ref UserManualFoxxManager. If you want to create your own application, please continue.

So let's get started, shall we?

Creating the application files
------------------------------

An application built with Foxx is written in JavaScript and deployed to ArangoDB directly. ArangoDB serves this application, you do not need a separate application server.

So given you want to build an application that sends a plain-text response "Worked!" for all requests to `/dev/meadow`.  How would you achieve that with Foxx?

First, create a directory `apps` somewhere in your filesystem. Let's assume from now on that the absolute path for this directory is `/home/user/apps`.

After that, create a sub-directory `my_app` in the `apps` directory and save the following content in a file named `app.js` there:

    var Foxx = require("org/arangodb/foxx");
    var app = new Foxx.Application(applicationContext);
    
    app.get("/meadow", function(req, res) {
      res.set("Content-Type", "text/plain");
      res.body = "Worked!"
    });

Beside the `app.js` we need a manifest file. In order to achieve that, we create a file called `manifest.json` in our `my_app` directory with the following content:

    {
      "name": "my_app",
      "version": "0.0.1",
      "author": "me and myself",
      "apps": {
        "/": "app.js"
      }
    }

You **must** specify a name and a version number for your application, otherwise it won't be loaded into ArangoDB.

You should now have the following files and directories with your application (starting at `/home/user` in our example):

    apps/
      my_app/
        manifest.json
        app.js

This is your application.

Testing the application
-----------------------

Now your application is ready to be tested. Start ArangoDB as follows:

    $ arangod --javascript.dev-app-path /home/user/apps /tmp/fancy_db

This will start the ArangoDB server in a **development mode** using the directory `/home/user/apps` as the workspace and `/tmp/fancy_db` as your database directory. Production application are installed using the Foxx manager and should not be changed. In development mode the server
automatically monitors the workspace and detects any change made to the files.

Replace `/home/user/apps` with the apps path that you initially created. This is the path that you created the `my_app` directory in. Replace `/tmp/fancy_db` with the directory your database is located in.

Now point your browser to `http://localhost:8529/dev/meadow` and you should see "Worked!". After this short overview, let's get into the details.


Handling Requests{#UserManualFoxxHandlingRequests}
==================================================

In development mode all available applications from the application directory `/home/user/apps` are visible under `http://localhost:8529/dev/DIRNAME` where `DIRNAME` is the name of the directory of your application.

When applications are installed in production mode, you can change the `/dev` prefix to whatever you like, see @ref UserManualFoxxManager.

If you do not redefine it, all requests that go to the root of your application will be redirected to `index.html`.


Details on FoxxApplication{#UserManualFoxxDetailsApplication}
=============================================================

@copydetails JSF_foxx_application_initializer

@CLEARPAGE
@copydetails JSF_foxx_application_createRepository

@CLEARPAGE
HTTP Methods
------------

@copydetails JSF_foxx_application_get

@CLEARPAGE
@copydetails JSF_foxx_application_head

@CLEARPAGE
@copydetails JSF_foxx_application_post

@CLEARPAGE
@copydetails JSF_foxx_application_put

@CLEARPAGE
@copydetails JSF_foxx_application_patch

@CLEARPAGE
@copydetails JSF_foxx_application_delete

@CLEARPAGE

Documenting and Constraining the Routes
---------------------------------------

If you now want to document your route, you can use JSDoc style comments (a multiline comment block with the first line starting with `/**` instead of `/*`) above your routes to do that:

    /** Get all Foxes
     * 
     * If you want to get all foxes, please use this
     * method to do that.
     */
    app.get("/foxes", function () {
      //...
    });

The first line will be treated as a summary (For optical reasons in the produced documentation, the summary is restricted to 60 characters). All following lines will be treated as additional notes shown in the detailed view of the route documentation. With the provided information, Foxx will generate a nice documentation for you. Furthermore you can describe your API by chaining the following methods onto your path definition:

@copydetails JSF_foxx_RequestContext_pathParam

@CLEARPAGE
@copydetails JSF_foxx_RequestContext_queryParam

@CLEARPAGE
@copydetails JSF_foxx_RequestContext_errorResponse

@CLEARPAGE

Before and After Hooks
----------------------

You can use the following two functions to do something before or respectively after the normal routing process is happening. You could use that for logging or to manipulate the request or response (translate it to a certain format for example).

@copydetails JSF_foxx_application_before

@CLEARPAGE
@copydetails JSF_foxx_application_after

@CLEARPAGE

The Request and Response Objects
--------------------------------

When you have created your FoxxApplication you can now define routes on it. You provide each with a function that will handle the request. It gets two arguments (four, to be honest. But the other two are not relevant for now):

* The `request` object
* The `response` object

These objects are provided by the underlying ArangoDB actions and enhanced by the `BaseMiddleware` provided by Foxx.

{'fraction_non_alphanumeric': 0.11492048269799408, 'fraction_numerical': 0.0019180052745145048, 'mean_word_length': 4.09113100081367, 'pattern_counts': {'":': 10, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2208184', 'n_tokens_mistral': 3340, 'n_tokens_neox': 3218, 'n_words': 1497}