App Documentation
(The documentation is being written) Here you will find useful information for the installation and configuration of Placido-Shop.
See the menu button below.
Operation of the public part of the program
See in this page :
Preamble
Empty GET request
GET request for a product
GET request for a category
GET request for cart page
GET request to the order report page
GET request for static pages
Preamble :
We will detail here how the public part of the program,
which runs on the client's browser, interacts with the private part of the application which runs on the server.
On the client side, the javaScript language is used.
We use the jQuery library which simplifies development.
Without entering into a debate, this is an assumed choice but which is not frozen in time.
On the server side, the PHP language is used for :
- Either return pages in .html format.
- Either return data to the client in .json format which will be processed by the client-side program.
- PHP also makes it possible to communicate with a database in .sql format to save data there or to repatriate it for the needs of the program.
To know :
- Server side,
only GET or POST type requests are allowed.
Empty GET request :
In the event that a client requests the home page of the site.
URL scheme : my-shop.com
the entry point is the index.php file located at the root of the program.
index.php :
-> Includes Mustache PHP, the templating engine.
It inserts the data passed as an array into the html templates :
require 'Mustache/Autoloader.php';
-> Register Mustache PHP : you can use it in all PHP code.
Mustache_Autoloader::register();
-> Register classes from API/ and PHP/ folders :
All classes in API and PHP folder will be available in all PHP code.
Note: with this system, file names must match class names.
spl_autoload_register( ... );
-> Define the constants for the application from the API/api.json file.
All keys in this file will be converted to constants available from anywhere in the code.
For back-in and front-end. :
api::init_settings();
-> Initializes a translation array to translate public and private interfaces,
according to the preference set in the API/api.json file.
Define the function parameter by
'front'
to fill the array with the translation of the public part of the site, 'back'
to translate the management part of the program. tr::init_tr( 'front' );
Note : you can access the translation class from anywhere in the PHP code.
This will return a translated string corresponding to its key in the array :
tr::$TR['my_translation_key'] = 'My key translated !'
-> Set time zone :
the constant TIMEZONE is defined by the api::init_settings(); method with the API/api.json file.
date_default_timezone_set( TIMEZONE );
-> Modules initialization - after translation :
It can add entries to the translation class tr::$TR[ ... ]
The module system can add functionality to the application.
It has its own documentation.
api::init_modules( $context='front' );
-> Start the controller,
it is this class that will manage all requests to the server.
It uses the class control from the PHP/control.php file.
control::start();
control::start();
This method first calls the control::router() method which handles GET requests.
If the request had been of the POST type, control::router() returns a string which can only be 'POST'.
If the request is of the GET type,
the process continues in the control::router() method which will terminate the process.
control::router();
↳ if( $request == '/' )
↳ program::get_home_page();
program::get_home_page();
The "program" class will fetch all the data necessary for the application, will store them and will create the html pages using the Mustache template engine.
The data needed by Mustache to create the html views and the data needed to be transmitted on the client side are all contained in an array
$ARR
At the end of the data processing done by the program::get_home_page(),
the
$ARR
array is converted to .json format and cached in a PHP session. The HTML view thus constructed is rendered to the client using the command
echo $m->render('base', $ARR);
Here we provide Mustache with the 'base' template: template/BASE/base.html and the application data table
$ARR
so that it can build the final html code. Note : The file that contains the base of the html document is the base.html file located in
templates/BASE/base.html.
The client will then load :
- The font(s).
- CSS code resources.
- The images visible in the viewport.
- JavaScript code resources.
Once the javaScript resources are loaded,
the JS/api_loader.js file immediately makes 2 POST requests to the server with the functions
get_templates();
and get_object_api();
The function
get_templates();
This function makes a POST request to the server by sending the key 'set' and the value 'get_templates'.
This request will be served by the control::start() method of the PHP/control.php file.
The query result is returned in .json format.
It contains an array of templates each with the "name" key and the "html" key.
{"templates":[{"html":"...","name":"..."},{,...}]}
These templates are added to the Mustache template engine which is also used on the client side in javaScript.
The function
get_object_api();
This function makes a POST request with the following parameters :
{set: 'get_obj', req: 'ajax'}
It will be served by the control::start(); method of the PHP/control.php file and receives a response in .json format which is converted into an object that extends the jQuery object.
The data received is the necessary data to the operation of the application.
This data is accessible everywhere in the javaScript code, it is public and you can display it at any time by entering
$.o
in a javaScript console. control::start();
control::start();
↳ control::router() -> return 'POST'
↳ if( $set == 'get_templates' )
↳ tools::get_templates();
tools::get_templates();
The get_templates(); method searches for all the .html templates in the templates/API folder and builds an array with a "name" key and an "html" key for each file.
The "html" key contains the .html code of a template.
When the templates array has been completed,
it is returned to the client in .json format.
@return : {"templates":[{"html":"...","name":"..."},{,...}]}
control::start();
↳ control::router() -> return 'POST'
↳ if( $set == 'get_obj' )
↳ program::get_home_page();
program::get_home_page();
When the
get_home_page();
method is called via a POST request and the 'req'='ajax'
parameter, it returns the previously cached application data on the first empty GET request from the client.
This data is returned in .json format and will be converted into a javaScript object that will extend the client-side jQuery object.
At any time you can consult this data by entering
$.o
in a javaScript console. The client receives the array of templates and prepares them for use by Mustache on the client side.
The client receives data from the application and converts it into an object that can be used globally in all JavaScript code.
At this stage the application is ready to be used.
This system allows for example to display a product page immediately because the template is available so that Mustache can insert the data of a product which are in the object
$.o.products
Mustache will then render the view immediately to the client.
Navigation through the pages of the site is almost instantaneous.
GET request for a product :
In case a customer requests a product page.
URL scheme : my-shop.com/{product_title}/product/{product_id}
control::start();
control::start();
↳ control::router();
↳ api::$REQ = array( 'prod_id' => $TAB_url[$c-1], 'url_request' => 'single_product' );
↳ program::get_home_page();
program::get_home_page();
here, depending on the product requested, we adjust the title of the page and its description.
We re-wrote the meta tags for social networks.
We take the template templates/API/single_product.html and insert the product data with Mustache.
/* see: PHP/program.php -> product_request( $prod_id, $ARR ); */ if( isset( api::$REQ['prod_id'] ) ){ $ARR = program::product_request( api::$REQ['prod_id'], $ARR ); }
Finally, we cache the application data in a session and then return the view of the product page to the visitor. We display the product page and as for the previous example the JS/api_loader.js file makes 2 POST requests to the server to ask :
1/ The templates necessary directly to the application.
2/ Application data cached during the GET request
↳ control::start();
↳ tools::get_templates();
↳ control::start();
↳ program::get_home_page();
All data and resources are loaded,
the application is ready to use.
GET request for a category :
In the case of a request to a category page.
URL scheme : my-shop.com/{category_title}/category/{category_id}
control::start();
control::start();
↳ control::router();
↳ api::$REQ = array( 'cat_id' => $TAB_url[$c-1], 'url_request' => 'cat' );
↳ program::get_home_page();
program::get_home_page();
Here, depending on the requested category, we are adjusting the page title and its description.
We re-wrote the meta tags for social networks.
We take the template templates/API/products_view.html or templates/API/products_view_inl.html if preferences are adjusted to display product thumbnails inline.
We sort the products based on the requested category and pass them to Mustache to insert the product data into the appropriate template.
/* see: PHP/program.php -> program::cat_request( $ARR ); */ if( isset( api::$REQ['cat_id'] ) ){ $ARR = program::cat_request($ARR); }
Finally, we cache the application data in a session, then we return the page of products sorted by category to the visitor. We display products page sorted by category and as for the previous example the JS/api_loader.js file makes 2 POST requests to the server to ask :
1/ The templates necessary directly to the application.
2/ Application data cached during the GET request
↳ control::start();
↳ tools::get_templates();
↳ control::start();
↳ program::get_home_page();
All data and resources are loaded,
the application is ready to use.
GET request for cart page :
In the case of a request to the basket page.
URL scheme : my-shop.com/cart/your-cart
control::start();
control::start();
↳ control::router();
↳ api::$REQ = array( 'page_api' => 'cart' );
↳ program::get_home_page();
program::get_home_page();
Here we check if the request concerns a special page of the application.
The special pages of the application are :
- The shopping cart page.
- The order reminder page.
- The login page to access the status of an order.
/* see: PHP/program.php -> program::page_api( $ARR ); */ if( isset( api::$REQ['page_api'] ) ){ $ARR = program::page_api($ARR); }
Since the page requested here is the shopping cart page,
we insert the partial template of shopping cart page,
templates/API/payment_form.html into the base html template templates/BASE/base.html, using Mustache.
Finally, we cache the application data in a session and we return the html view of the cart page.
JS/api_loader.js file makes 2 POST requests to the server to ask :
1/ The templates necessary directly to the application.
See : JS/api_loader.js -> get_templates();
2/ Application data cached during the GET request
See : JS/api_loader.js -> get_object_api();
↳ control::start();
↳ tools::get_templates();
This function returns the templates needed by the application in .json format to the function JS/api_loader.js -> get_templates(); of the public part. ↳ control::start();
↳ program::get_home_page();
This function returns the data that will be used to operate the application in .json format to the JS/api_loader.js -> get_object_api(); function of the public part. On the client side, the function
get_object_api();
JS/api_loader.js -> get_object_api(); tests the value of $.o.view.page_context
, which is defined in the data returned by the server. Here the context defined by the value of
$.o.view.page_context
is "cart", we then call the function
$.open_payment_form();
of JS/cart.js. This function will test if cart data has been cached on the client side using the "sessionStorage" module of javaScript.
If data has already been added,
it will be displayed again to the client using Mustache (javaScript),
even if he refreshes his page or reopens it, in accordance with the behavior of the "sessionStorage" module.
Thus, even if the customer refreshes the basket page or if he closes it and reopens it, he will find the products he has already selected in the basket.
Note: If the client has filled in fields such as his name or his address and he makes a request to the server which fails, for a field which has remained empty for example,
then the field data will in turn be cached as for the products already selected in the basket.
The process is complete.
GET request to the order report page :
This page is displayed if the sale is successful.
It displays the status of the sale:
- Paid/unpaid
- Being processed.
- Shipped.
URL scheme : my-shop.com/sale/{sale_id}/{sale_hash}
The customer has just made a sale and the function cart.js -> $.get_sale( sale_id, hash_customer ); displays the customer's order reminder page.
The page address is modified and corresponds to the following model:
my-shop.com/sale/{sale_id}/{sale_hash}.
sale_id
is the id as recorded in the new_sales table. sale_hash
corresponds to a random hash that will allow the customer to find his order. This sale is cached for a few minutes so that if the customer refreshes his page, he will find his sale.
The sale is still cached and the customer makes a request with the following URL:
my-shop.com/sale/{sale_id}/{sale_hash}.
↳ control::start();
control::start();
↳ control::router();
Here we detect that the request requests a special page of the application.
We retrieve the values of sale_id and hash_customer passed in the URL and we insert them into a global access table:
/* page_api=sale */ api::$REQ = array( 'page_api' => 'sale' , 'sale_id' => $TAB_url[$c-2], 'hash_customer' => $TAB_url[$c-1] );
We then call the function program::get_home_page();
program::get_home_page();
/* api page request */ if( isset( api::$REQ['page_api'] ) ){ $ARR = program::page_api($ARR); }
↳ program::page_api($ARR);
This function checks whether sales data is still cached (in a session). if yes, the order data is integrated into the table
$ARR
application data. Also, we indicate to Mustache that it will be necessary to insert in the base template, the template templates/API/render_sale.html with the order data.
If the order data is no longer or not cached,
we tell Mustache to insert the template of the order access request form into the base template.
templates/API/render_sale_login.html.
The server returns to the client:
- Either the order report page (case N°1).
- Either the connection page to an order (case N°2).
If the customer makes a request to this address and the cache duration is exceeded, the page displayed will then be a form which asks the customer to enter their e-mail address and order number.
By submitting the form, the client sends a POST request to the server using the cart.js -> $.get_sale_user( event ); function.
The server will return the page of its command to the client if the parameters provided are correct.
The parameters sent are:
email: {customer's email}
comm_number: {the order number}
set: get_sale_user
↳ control::start();
control::start();
↳ program::user_access_sale();
program::user_access_sale();
This function will verify that all the parameters provided are correct and return the order data to the customer, in .json format.
$tab = array( 'success' => true, 'SALE' => $SALE, 'hash_customer' => $hash_customer_server ); echo json_encode($tab, JSON_NUMERIC_CHECK); exit;
The cart.js -> $.get_sale_user(event); function retrieves the data returned by the server in .json format.
With these data the function creates a new global object
$.o.SALE = data.SALE;
which contains the data of the order as well as its status. We use Mustache on the client side to display the order to the client.
The process is complete.
GET request for static pages :
The application allows to create static pages.
These pages are directly accessible by URL.
All static page URLs end with .html.
Note: Static pages are rendered in the jQuery global object $.o.static_pages
By entering this command in a javaScript console you will display the object table of these pages.
The $.o.static_pages object is created when the site is initialized by the PHP function
PHP/program.php -> program::get_home_page();
Which in turn calls the function
PHP/process.php -> get_static_pages();
/* GET STATIC PAGES */ $ARR['static_pages'] = process::get_static_pages();
URL scheme : my-shop.com/{my-static-page}.html
From the public part of the site,
there are two ways to allow access to static pages to users :
1/ By placing a link in the html code of a page : (example)
<button onclick="$.open_static_page(event, '{{static_pages.my-static-page.url}}');" class="pointer" role="button" aria-label="{{static_pages.my-static-page.page_title}}"> <i class="fa-fw fa-hand-point-right far"></i> Translate this</button>
2/ By placing a button in the html code of a page : (example) <a onclick="$.open_static_page(event, '{{static_pages.my-static-page.url}}');" href="{{static_pages.my-static-page.url}}.html" title="{{static_pages.my-static-page.page_title}}" class="underline">Link to my static page</a>
A user clicks on a link or a button to a static page.
This action calls the function
JS/main.js -> $.open_static_page( event, page_url );
This function checks that the static page called is valid on the client side then makes a POST request to the server in order to retrieve the html code of the page.
The parameters sent to the server are:
{set: 'return_static_page', page_url: page_url}
↳ control::start();
control::start();
↳ tools::get_static_page();
tools::get_static_page();
This function will do security tests and test that the static page exists.
It will minify the html code of the page and will return a table in .json format with the following parameters
[{success: true}, {template: '<div> ... </div>}]
On the client side,
the function JS/main.js -> $.open_static_page( event, page_url ); receives the html code of the page and adds it as a template to Mustache
/* add html template */ $.Mustache.add(page_url, data.template);
then we call the function JS/main.js -> $.show_page( event, page_url ); to display the page to the customer.
Note: This page will remain cached and will no longer be downloaded from the server.
Thus, if the user clicks again on a button or on a link to this page, it will be returned to him immediately.
A request to access a static page is made by a URL request.
Like this: https://my-shop.com/my-static-page.html.
This request will be sent directly to the server, to the index.php file, located at the root of the website.
↳ control::start();
control::start();
↳ control::router();
Here we check that it is indeed a GET request to a static page.
We extract the portion of the URL that will tell us which static page is requested.
We save this value in the global array
api::$REQ
api::$REQ = array( 'page' => $page );
Then we call the function PHP/program.php -> program::get_home_page();
program::get_home_page();
/* GET url request - STATIC PAGE asked */ if( isset( api::$REQ['page'] ) ){ $ARR = program::page_request($ARR); }
Here we have the information that tells us that we need to call a static page. We need to insert the partial template of the static page into the base template of the application.
Note: Static page templates are located in the templates/STATIC_PAGES folder.
When you create a static page from the management interface, an .html file is created in this folder.
This file is a basic file, you must edit it with html code in order to create your own page.
This file contains an automatically created comment in the header that indicates how to insert links or buttons pointing to this page.
↳ program::page_request( $ARR );
This function will do security checks.
Please note that page URLs that exceed 500 characters will be rejected.
It will adjust the values of the
<meta property="og:..." content="...">
tags for social networks. Then it will add keys and values to the
$ARR
global data array to tell Mustache which partial template we should insert into the base template. The process continues in the function
PHP/program.php -> program::get_home_page(); where Mustache inserts the partial static page template into the base template.
Finally, the server sends back to the client the html code of the application with the view of the static page.
The other processes follow one another as in the case of an empty GET request.
The visitor directly accesses the requested static page.
All the features of the site are present.