diff --git a/doc/workbook/basics/basics.md b/doc/workbook/basics/basics.md index f5706441..15ec333f 100644 --- a/doc/workbook/basics/basics.md +++ b/doc/workbook/basics/basics.md @@ -1,4 +1,4 @@ -Nav: [Workbook](../workbook.md) | [Handling Requests: Form/Query Parameter](/doc/workbook/handling_request/form.md) +Nav: [Workbook](../workbook.md) | [Handling Requests: Form/Query Parameter](../handling_request/form.md) ## EWF basic service @@ -11,14 +11,14 @@ Nav: [Workbook](../workbook.md) | [Handling Requests: Form/Query Parameter](/doc - [Source code](#source_2) - + ## EWF service structure The following code describes the basic structure of an EWF basic service that handles HTTP requests. We will need to define a Service Launcher and a Request Execution implementation. ```eiffel class - APPLICACTION + APPLICATION inherit WSF_DEFAULT_SERVICE [APPLICATION_EXECUTION] @@ -91,11 +91,11 @@ The **WSF_RESPONSE** provides features to define the response with information s **APPLICATION** is the root class of our example, it launches the application, using the corresponding connector, Which connector? this depends how you want to run it cgi, fcgi,nino or standalone. For development is recommended to use a standalone web server written in Eiffel, and run the execution within the EiffelStudio debugger. For production fcgi (or cgi) using Apache or another popular web server. -![Launcher Hierarchy](/doc/workbook/basics/Launcher Hierarchy.png "Launcher Hierarchy") +![Launcher Hierarchy](Launcher Hierarchy.png "Launcher Hierarchy") -**WS_LAUNCHABLE_SERVICE** inherit from **WS_SERVICE** class, which is a marker interface in EWF. And also provides a way to launch our application using different kind of connectors. The class **WSF_DEFAULT_SERVICE_I**, inherit from **WS_LAUNCHABLE_SERVICE** and has a formal generic that should conform to **WSF_SERVICE_LAUNCHER [WSF_EXECUTION]**. Below a [BON diagram] (http://www.bon-method.com/index_normal.htm) showing one of the possible options. +**WS_LAUNCHABLE_SERVICE** inherit from **WS_SERVICE** class, which is a marker interface in EWF. And also provides a way to launch our application using different kind of connectors. The class **WSF_DEFAULT_SERVICE_I**, inherit from **WS_LAUNCHABLE_SERVICE** and has a formal generic that should conform to **WSF_SERVICE_LAUNCHER [WSF_EXECUTION]**. Below a [BON diagram](http://www.bon-method.com/index_normal.htm) showing one of the possible options. -![Standalone Launcher](/doc/workbook/basics/WSF_SERVICE_LAUNCHER_STANDALONE.png "Standalone Hierarchy") +![Standalone Launcher](WSF_SERVICE_LAUNCHER_STANDALONE.png "Standalone Hierarchy") Other connectors: **WSF_STANDALONE_SERVICE_LAUNCHER** @@ -109,11 +109,11 @@ The **APPLICATION_EXECUTION** class inherits from **WSF_EXECUTION** interface, In the **APPLICATION_EXECUTION** class class you will need to implement implement the **execute** feature, get data from the request *req* and write the response in *res*. -![Execution Hierarchy](/doc/workbook/basics/APPLICATION_EXECUTION.png "Application Execution ") +![Execution Hierarchy](APPLICATION_EXECUTION.png "Application Execution ") The WSF_EXECUTION instance, in this case ```APPLICATION_EXECUTION``` is created per request, with two main attributes request: ```WSF_REQUEST``` and response: ```WSF_RESPONSE```. - + ## A simple Service to Generate Plain Text. Before to continue, it is recommended to review the getting started guided. In the example we will only shows the implementation of the WSF_EXECUTION interface. @@ -147,7 +147,7 @@ The source code is available on Github. You can get it by running the command: ```git clone https://github.com/EiffelWebFramework/ewf.git``` -The example of simple service that generate plain text response is located in the directory $PATH/ewd/doc/workbook/basics/simple, where $PATH is where you run ```git clone``` . Just double click on the simple.ecf file and select the simple_nino target or if you prefer the command line, run the command: +The example of simple service that generate plain text response is located in the directory $PATH/ewf/doc/workbook/basics/simple, where $PATH is where you run ```git clone``` . Just double click on the simple.ecf file and select the simple_nino target or if you prefer the command line, run the command: ```estudio -config simple.ecf -target simple_nino``` @@ -202,5 +202,5 @@ The example of the service that generates HTML is located in the directory $PATH ```estudio -config simple_html.ecf -target simple_html_nino``` -Nav: [Workbook](../workbook.md) | [Handling Requests: Form/Query Parameter](/doc/workbook/handling_request/form.md) +Nav: [Workbook](../workbook.md) | [Handling Requests: Form/Query Parameter](../handling_request/form.md) diff --git a/doc/workbook/basics/simple_html/simple_html.rc b/doc/workbook/basics/simple_html/simple_html.rc deleted file mode 100644 index b0ec159c..00000000 --- a/doc/workbook/basics/simple_html/simple_html.rc +++ /dev/null @@ -1,6 +0,0 @@ -#include - -STRINGTABLE -BEGIN - 1 "This Program was made using EiffelStudio using Visual Studio C++" -END diff --git a/doc/workbook/deployment.md b/doc/workbook/deployment.md index 3f86da95..c128e288 100644 --- a/doc/workbook/deployment.md +++ b/doc/workbook/deployment.md @@ -1,3 +1,5 @@ +Nav: [Workbook](./workbook.md) + EWF Deployment ============== @@ -158,6 +160,4 @@ Copy the app.exe and the folder "www" into a folder served by apache2, for exam Replace $service with the name of your executable $service, for example app_service.exe You will need to create an service.ews file, this file will be located at the same place where you copy your app service executable. - - - +Nav: [Workbook](./workbook.md) diff --git a/doc/workbook/generating_response/generating_response.md b/doc/workbook/generating_response/generating_response.md index 4d63cdfd..78e806d2 100644 --- a/doc/workbook/generating_response/generating_response.md +++ b/doc/workbook/generating_response/generating_response.md @@ -1,5 +1,5 @@ -Nav: [Workbook](../workbook.md) | [Handling Requests: Header Fields](/doc/workbook/handling_request/headers.md) | [Handling Cookies](/doc/workbook/handling_cookies/handling_cookies.md) +Nav: [Workbook](../workbook.md) | [Handling Requests: Header Fields](../handling_request/headers.md) | [Handling Cookies](../handling_cookies/handling_cookies.md) ## EWF Generating Response @@ -14,7 +14,7 @@ Nav: [Workbook](../workbook.md) | [Handling Requests: Header Fields](/doc/workbo - [Response Header Fields](#header_fields) - + ## Format of the HTTP response As we saw in the previous documents, a request from a user-agent (browser or other client) consists of an HTTP command (usually GET or POST), zero or more request headers (one or more in HTTP 1.1, since Host is required), a blank line, and only in the case of POST/PUT requests, payload data. A typical request looks like the following. @@ -49,7 +49,7 @@ looks like this: The status line consists of the HTTP version (HTTP/1.1 in the preceding example), a status code (an integer 200 in the example), and a very short message corresponding to the status code (OK in the example). In most cases, the headers are optional except for Content-Type, which specifies the MIME type of the document that follows. Although most responses contain a document, some don’t. For example, responses to HEAD requests should never include a document, and various status codes essentially indicate failure or redirection (and thus either don’t include a document or include only a short error-message document). - + ## How to set the status code If you need to set an arbitrary status code, you can use the ```WSF_RESPONSE.put_header``` feature or the ```WSF_RESPONSE.set_status_code``` feature. An status code of 200 is a default value. See below examples using the mentioned features. @@ -94,7 +94,7 @@ Example ``` Both features takes an INTEGER (the status code) as an formal argument, you can use 200, 300, 500 etc directly, but instead of using explicit numbers, it's recommended to use the constants defined in the class [HTTP_STATUS_CODE](). The name of each constant is based from the standard [HTTP 1.1](https://httpwg.github.io/). - + ## How to redirect to a particular location. To redirect the response to a new location, we need to send a 302 status code, to do that we use ```{HTTP_STATUS_CODE}.found``` @@ -145,7 +145,7 @@ The ```WSF_RESPONSE.redirect_now``` feature use the status code ```{HTTP_STATUS_ Using a similar approach we can build features to answer a bad request (400), internal server error (500), etc. We will build a simple example showing the most common HTTP status codes. - + ## [HTTP 1.1 Status Codes](https://httpwg.github.io/specs/rfc7231.html#status.codes) The status-code element is a three-digit integer code giving the result of the attempt to understand and satisfy the request. The first digit of the status-code defines the class of response. @@ -159,7 +159,7 @@ General categories: Note: use ```res.set_status_code({HTTP_STATUS_CODE}.bad_request)``` rather than ```res.set_status_code(400)```. - + ### Example Staus Codes Basic Service that builds a simple web page to show the most common status codes ```eiffel @@ -298,7 +298,7 @@ end - + ### Example Generic Search Engine The following example shows a basic EWF service that builds a generic front end for the most used search engines. This example shows how redirection works, and we will use a tools to play with the API to show differents responses. @@ -585,7 +585,7 @@ Connection: close ``` - + ## [Response Header Fields](https://httpwg.github.io/specs/rfc7231.html#response.header.fields) The response header fields allow the server to pass additional information about the response beyond what is placed in the status-line. These header fields give information about the server, about further access to the target resource, or about related resources. We can specify cookies, page modification date (for caching), reload a page after a designated period of time, size of the document. @@ -996,4 +996,4 @@ There are four categories for response header fields: -Nav: [Workbook](../workbook.md) | [Handling Requests: Header Fields](/doc/workbook/handling_request/headers.md) | [Handling Cookies](/doc/workbook/handling_cookies/handling_cookies.md) +Nav: [Workbook](../workbook.md) | [Handling Requests: Header Fields](../handling_request/headers.md) | [Handling Cookies](../handling_cookies/handling_cookies.md) diff --git a/doc/workbook/handling_cookies/handling_cookies.md b/doc/workbook/handling_cookies/handling_cookies.md index f1de9bdc..824f6cfd 100644 --- a/doc/workbook/handling_cookies/handling_cookies.md +++ b/doc/workbook/handling_cookies/handling_cookies.md @@ -1,4 +1,4 @@ -Nav: [Workbook](../workbook.md) | [Generating Responses](/doc/workbook/generating_response/generating_response.md) +Nav: [Workbook](../workbook.md) | [Generating Responses](../generating_response/generating_response.md) # Handling Cookies @@ -9,9 +9,9 @@ Nav: [Workbook](../workbook.md) | [Generating Responses](/doc/workbook/generatin - [How to read a cookie](#read_cookie) - [Examples](#examples) - -## [Cookie](http://httpwg.github.io/specs/rfc6265.html) -A cookie is a piece of data that can be stored in a browser's cache. If you visit a web site and then revisit it, the cookie data can be used to identify you as a return visitor. Cookies enable state information, such as an online shopping cart, to be remembered. A cookie can be short term, holding data for a single web session, that is, until you close the browser, or a cookie can be longer term, holding data for a week or a year. + +## Cookie +A [cookie](http://httpwg.github.io/specs/rfc6265.html) is a piece of data that can be stored in a browser's cache. If you visit a web site and then revisit it, the cookie data can be used to identify you as a return visitor. Cookies enable state information, such as an online shopping cart, to be remembered. A cookie can be short term, holding data for a single web session, that is, until you close the browser, or a cookie can be longer term, holding data for a week or a year. Cookies are used a lot in web client-server communication. @@ -30,7 +30,7 @@ Client send cookies to server - + ### Cookie properties - Comment: describe the purpose of the cookie. Note that server doesn’t receive this information when client sends cookie in request header. @@ -43,7 +43,7 @@ Client send cookies to server - HttpOnly: Checks whether this Cookie has been marked as HttpOnly. - Version: - + ## Write and Read Cookies. To send a cookie to the client we should use the [HTTP_HEADER] class, and call ```h.put_cookie``` feature or @@ -67,7 +67,7 @@ WSF_REQUEST.cookie (a_name: READABLE_STRING_GENERAL): detachable WSF_VALUE feature. - + ### How to set Cookies Here we have the feature definitions to set cookies @@ -111,7 +111,7 @@ Example of use: res.put_string (web_page) end ``` - + ### How to read Cookies Reading a particular cookie @@ -130,7 +130,7 @@ Reading all the cookies ``` - + ### Example The following EWF service shows a basic use of cookies. 1. It display a message to first-time visitors. @@ -285,4 +285,4 @@ end ``` -Nav: [Workbook](../workbook.md) | [Generating Responses](/doc/workbook/generating_response/generating_response.md) +Nav: [Workbook](../workbook.md) | [Generating Responses](../generating_response/generating_response.md) diff --git a/doc/workbook/handling_request/form.md b/doc/workbook/handling_request/form.md index c72772b6..b982f911 100644 --- a/doc/workbook/handling_request/form.md +++ b/doc/workbook/handling_request/form.md @@ -1,4 +1,4 @@ -Nav: [Workbook](../workbook.md) | [Basic Concepts] (/doc/workbook/basics/basics.md) | [Handling Requests: Header Fields](/doc/workbook/handling_request/headers.md) +Nav: [Workbook](../workbook.md) | [Basic Concepts](../basics/basics.md) | [Handling Requests: Header Fields](./headers.md) #Handling Requests: Form/Query Data @@ -7,7 +7,7 @@ Nav: [Workbook](../workbook.md) | [Basic Concepts] (/doc/workbook/basics/basics. ##### Table of Contents - [Reading Form Data](#read) - [Query Parameters](#query) - - [Form Parameters](#form) + - [Form Parameters](#form_parameters) - [Uniform Read](#uniform) - [Reading Parameters and Values](#reading_pv) - [How to read all parameters names](#all_names) @@ -34,11 +34,11 @@ Here we will show you how to read input submitted by a user using a Form (GET an * client side validattion, server side validations, set default if it's a valid option. * How to populate Eiffel objects from the request data. - + ## Reading Form Data EWF [WSF_REQUEST]() class, provides features to handling this form parsing automatically. - + ### Query Parameters WSF_REQUEST.query_parameters: ITERABLE [WSF_VALUE] @@ -46,7 +46,7 @@ EWF [WSF_REQUEST]() class, provides features to handling this form parsing autom WSF_REQUEST.query_parameter (a_name: READABLE_STRING_GENERAL): detachable WSF_VALUE -- Query parameter for name `a_name'. - + ### Form Parameters WSF_REQUEST.form_parameters: ITERABLE [WSF_VALUE] @@ -57,7 +57,7 @@ EWF [WSF_REQUEST]() class, provides features to handling this form parsing autom The values supplied to form_parameter and query_parameter are case sensitive. - + ### Read Data The previous features, let you read the data one way for GET request and a different way for POST request. WSF_REQUEST provide a feature to read all the data in a uniform way. @@ -70,7 +70,7 @@ So, you use **WSF_REQUEST.item** feature exactly the same way for GET and POST r >Note: if a query parameter has the same name as a form paramenter req.item will retrieve the form paramenter. Remember the precedence: form > query > path - + ## Reading Parameters and Values Suppose we have the following HTML5 form using Method POST. This HTML5 form has client side form validation using the new HTML5 attribute, you can do the same using Javascript. So in this case if the user does not fill the fields as expected the form will not be submitted to the server. @@ -111,7 +111,7 @@ Suppose we have the following HTML5 form using Method POST. This HTML5 form has ``` - + ### How to read all parameter names To read all the parameters names we simple call WSF_REQUEST.form_parameters. @@ -119,7 +119,7 @@ To read all the parameters names we simple call WSF_REQUEST.form_parameters. req: WSF_REQUEST across req.form_parameters as ic loop show_parameter_name (ic.item.key) end ``` - + ### How to read single values To read a particular parameter, a single value, for example `given-name', we simple call WSF_REQUEST.form_parameter (a_name) and we check if it's attached to WSF_STRING (represents a String parameter) ``` @@ -131,7 +131,7 @@ To read a particular parameter, a single value, for example `given-name', we sim -- Value missing, check the name against the HTML form end ``` - + ### How to read multiple values To read multiple values, for example in the case of `languages', we simple call WSF_REQUEST.form_parameter (a_name) and we check if it's attached to WSF_MULTIPLE_STRING (represents a String parameter) @@ -155,7 +155,7 @@ To read multiple values, for example in the case of `languages', we simple call ``` In this case we are handling strings values, but in some cases you will need to do a conversion, betweend the strings that came from the request to map them to your domain model. - + ### How to read table values This is particularly useful when you have a request with the following format @@ -183,7 +183,7 @@ if attached {WSF_TABLE} req.query_parameter ("tab") as l_tab then end ``` - + ## Reading Raw Data You can also access the data in raw format, it means you will need to parse and url-decode it, and also you will not be able to use the previous features, by default, to enable that you need to call `req.set_raw_input_data_recorded (True)'. This feature (reading raw data) is useful if you are reading POST data with JSON or XML formats, but it's not convinient for HTML forms. @@ -199,7 +199,7 @@ To read raw data you need to do this > given-name=testr&family-name=test&dob=1976-08-26&email=test%40gmail.com&url=http%3A%2F%2Fwww.eiffelroom.com&phone=455555555555&languages=Spanish&languages=English - + ## Upload Files How can we read data when the date come from an uploaded file/s?. HTML supports a form element ``` ``` to upload a single file and ``` ``` to upload multiple files. @@ -290,7 +290,7 @@ The source code is available on Github. You can get it by running the command: The example is located in the directory $PATH/ewf/doc/workbook/upload_file where $PATH is where you run git clone. - + ## Examples The source code is available on Github. You can get it by running the command: @@ -303,5 +303,4 @@ The GET example is located in the directory $PATH/ewf/doc/workbook/form/get, and >Note: replace and with the corresponding values. -Nav: [Workbook](../workbook.md) | [Basic Concepts] (/doc/workbook/basics/basics.md) | [Handling Requests: Header Fields](/doc/workbook/handling_request/headers.md) - +Nav: [Workbook](../workbook.md) | [Basic Concepts](../basics/basics.md) | [Handling Requests: Header Fields](./headers.md) diff --git a/doc/workbook/handling_request/headers.md b/doc/workbook/handling_request/headers.md index bba056ed..304fabbe 100644 --- a/doc/workbook/handling_request/headers.md +++ b/doc/workbook/handling_request/headers.md @@ -1,4 +1,4 @@ -Nav: [Workbook](../workbook.md) | [Handling Requests: Form/Query parameters] (/doc/workbook/handling_request/form.md) | [Generating Responses](/doc/workbook/generating_response/generating_response.md) +Nav: [Workbook](../workbook.md) | [Handling Requests: Form/Query parameters](./form.md) | [Generating Responses](../generating_response/generating_response.md) #Handling Requests: Headers @@ -170,7 +170,7 @@ included in the Referer header when the browser requests Web page B. #### Building a Table of All Request Headers -The following [EWF service](/doc/workbook/handling_request/headers/header_fields/application.e) code simply uses an ```html_template``` to fill a table (names and values) with all the headers fields it receives. +The following [EWF service](./headers/header_fields/application.e) code simply uses an ```html_template``` to fill a table (names and values) with all the headers fields it receives. The service accomplishes this task by calling ```req.meta_variables``` feature to get an ```ITERABLE [WSF_STRING]```, an structure that can be iterated over using ```across...loop...end```, then it checks if the name has the prefix ```HTTP_``` and if it is true, put the header name and value in a row. (the name in the left cell, the value in the right cell). @@ -284,7 +284,7 @@ To be completed. #### Detecting Browser Types -The User-Agent header identifies the specific browser/client that is sending the request. The following code shows a [EWF service](/doc/workbook/handling_request/headers/browser_name/application.e) that sends browser-specific responses. +The User-Agent header identifies the specific browser/client that is sending the request. The following code shows a [EWF service](./headers/browser_name/application.e) that sends browser-specific responses. The examples uses the ideas based on the [Browser detection using the user agent](https://developer.mozilla.org/en-US/docs/Browser_detection_using_the_user_agent) article. Basically the code check if the header user_agent exist and then call the ```browser_name (a_user_agent: READABLE_STRING_8): READABLE_STRING_32``` @@ -429,10 +429,8 @@ As an exercise, try to write a similar service to retrieve the OS family using t * [SERVER_SOFTWARE](https://tools.ietf.org/html/rfc3875#section-4.1.16) **Example** -An [EWF service](/doc/workbook/handling_request/headers/cgi_variables/application.e) that shows the CGI variables, creates a table showing the values of all the CGI variables. - - -Nav: [Workbook](../workbook.md) | [Handling Requests: Form/Query parameters] (/doc/workbook/handling_request/form.md) | [Generating Responses](/doc/workbook/generating_response/generating_response.md) +An [EWF service](./cgi_variables/application.e) that shows the CGI variables, creates a table showing the values of all the CGI variables. +Nav: [Workbook](../workbook.md) | [Handling Requests: Form/Query parameters](./form.md) | [Generating Responses](../generating_response/generating_response.md) diff --git a/doc/workbook/readme.md b/doc/workbook/readme.md index be7f9965..5274bf87 100644 --- a/doc/workbook/readme.md +++ b/doc/workbook/readme.md @@ -1,4 +1,4 @@ -The [Workbook](/doc/workbook/workbook.md) lets you discover the EiffelWeb framework. +The [Workbook](./workbook.md) lets you discover the EiffelWeb framework. -[Enter the documentation](/doc/workbook/workbook.md) +[Enter the documentation](./workbook.md) diff --git a/doc/workbook/workbook.md b/doc/workbook/workbook.md index 07ddc2fc..5b019c2c 100644 --- a/doc/workbook/workbook.md +++ b/doc/workbook/workbook.md @@ -12,6 +12,7 @@ # EWF Core Before reading (or walking throught) the workbook, to get a quick overview of EWF, it is recommended to read the following articles: + * [Getting Started with EWF](http://eiffelwebframework.github.io/EWF/getting-started/) * [EWF Documentation](http://eiffelwebframework.github.io/EWF/wiki/Documentation/) * [EWF Application Lifecyle](https://github.com/EiffelWebFramework/ewf_examples/wiki/Application-Lifecycle) @@ -19,24 +20,24 @@ Before reading (or walking throught) the workbook, to get a quick overview of EW ## Introduction -[Basic Concepts] (/doc/workbook/basics/basics.md). +[Basic Concepts](./basics/basics.md). ## Handling Requests: Form/Query Parameter -[Handling Requests: Form/Query Parameter] (/doc/workbook/handling_request/form.md). +[Handling Requests: Form/Query Parameter](./handling_request/form.md). ## Handling Requests: Header Fields -[Handling Requests: Header Fields](/doc/workbook/handling_request/headers.md). +[Handling Requests: Header Fields](./handling_request/headers.md). ## Generating Response -[Generating Responses](/doc/workbook/generating_response/generating_response.md) +[Generating Responses](./generating_response/generating_response.md) ## Handling Cookies -[Handling Cookies](/doc/workbook/handling_cookies/handling_cookies.md) +[Handling Cookies](./handling_cookies/handling_cookies.md) - + ## EWF Deployment -[EWF Deployment](/doc/workbook/deployment.md) +[EWF Deployment](./deployment.md)