diff --git a/documentation/documentation.html b/documentation/documentation.html new file mode 100644 index 0000000..9003d3f --- /dev/null +++ b/documentation/documentation.html @@ -0,0 +1,334 @@ + + + + + + + + Documentation + + + + + + + + + +
+
+ + MELODY + + +
+
+ +
+
+
+
+ +
+ +
+
+ +
+
+

Documentation

+

MELODY, a web-based, extensible, reusable, and user-friendly software for + retrieving, presenting, and publishing Linked Data in the form of Data Stories. This is made + possible by pre-built templates and functionalities described in the following sections. The + core components of the project are:

+
    +
  • A Python application developed with the Flask framework. +
    • +
  • A JSON configuration file that stores setup information.
    • +
  • A set of HTML pages that form the web interface.
    • +
  • A set of HTML layout templates.
    • +
  • A set of Ajax HTTP requests to query SPARQL endpoints and create charts.
    • +
+

The Flask + Application +

+

MELODY is a web-based Python application developed with the Flask framework. It serves two main functions: +

+
    +
  1. manages incoming and outgoing data from the configuration file using methods;
    2. +
  2. provides a web interface similar to a CMS rendered via routing.
    3. +
+

+ Configuration Methods +

+

Four methods have been defined to manage the data:

+
    +
  1. The read_json method accesses the config.json file to retrieve configuration + information. +
    2. +
  2. The update_json method updates the config.json file with any new incoming + information from the user.
    3. +
  3. The access_data_sources method accesses data of a specific data story based + on the + title and the name of the section. This is possible because these two parameters + define the location of each data story within the config.json file, as we will see + in the next sections.
    4. +
  4. The manage_datastory_data method manages and stores in the config.json file + the + information involved in submitting the WYSIWYG form. This means that information + about what and how an author wants content displayed in a data story is received, + processed, and stored in a specific structure that we will analyze in the next + section.
    5. +
+

+ Routing +

+

Main routing functions are:

+
    +
  • .route("/index.html"): returns the homepage. +
    • +
  • .route("/setup", methods=['POST', 'GET']): if the HTTP method is GET, it + renders the setup.html page, where the user can enter preliminary information + about a data story; if the HTTP method is POST, the information submitted + through the small form is received, managed, and stored in the config.json file. + With the same information, the user is redirected to the selected template + WYSIWYG form.
    • +
  • .route("/send_data/<string:section_name>", methods=['POST', 'GET']): + this + function manages the submission of the WYSIWYG form, i.e. the data is received + thanks to the manage_datastory_data method, processed and stored in the + config.json file. With the same data, the user is redirected to the final + product, the page with the data story.
    • +
  • .route("/<string:section_name>/<string:datastory_name>"): thanks to + the dynamic routing and the variables specified in the URL, the data story + template is rendered and filled with the correct data. This routing function + works for any available data story.
    • +
  • .route("/modify/<string:section_name>/<string:datastory_name>", + methods=['POST', 'GET']): if the HTTP method is GET, the server renders + the modifiable version of the data story, the WYSIWYG form; if the HTTP method + is POST, the server again manages the submission of the WYSIWYG form and + redirects to the data story page.
    • +
+

The + Configuration File +

+

The config.json file can be created almost from scratch. Ideally, when a new + user downloads + and runs the software for the first time, this file is filled with the most important + default information. Anything regarding data stories that can be created is filled in via + the setup passages provided by the web interface itself. On the server side, the + configuration methods shown above are responsible for receiving, processing, and storing the + data.

+

The config.json file contains information about:

+
    +
  • Types of available templates and their basic properties.
    • +
  • Types of charts.
    • +
  • Types of operations.
    • +
  • List of data stories, organized as “section:datastory_list”.
    • +
+

In detail:

+
    +
  • “sections” are the macro areas in which data stories can be organized. They are stored + as a list of strings, and are updated every time a new one is created.
    • +
  • “operations” are the type of actions that can be performed on data after retrieval from + the SPARQL endpoint. They are stored as a fixed list of strings.
    • +
  • “templates” stores the information about the provided template types. It is structured + as a dictionary that has as keys the name of each template, and as value a dictionary + with detailed information.
    • +
  • “chart_types” are the types of charts available to be visualized. They are stored as a + fixed list of strings.
    • +
  • “data_sources” contains the information about all the data stories created. It is + structured as a dictionary in which keys are the name of the sections, the value is a + dictionary that contains all the data story under a section. It is automatically updated + during the setup phase. Each data story has as value a dictionary that contains its + information, further organized.
    • +
  • “dynamic_elements” is a list of dictionaries. Each dictionary is a dynamic segment that + composes the final datastory, namely text, counts and charts. This is information that + the user can add during the setup phase in the WYSIWYG form.
    • +
+

Ajax HTTP + Requests +

+

Query Ajax HTTP requests are used to retrieve data from SPARQL endpoints: more + specifically, + in certain situations, the SPARQL queries in the config.json file are sent to the respective + SPARQL endpoint to retrieve data that needs to be presented in the data stories. They are + used for:

+
    +
  • Retrieving and displaying linked data from SPARQL endpoints as a preview when filling + out the WYSIWYG form. In this case, the temporarily cached SPARQL queries are used as + part of the input content.
    • +
  • Retrieving linked data from SPARQL endpoints and displaying it in the final data story. + In this case, it uses the SPARQL queries stored in the config.json file.
    • +
+
+
+
+
+
+ + + + + + + + \ No newline at end of file diff --git a/documentation/getting_started.html b/documentation/getting_started.html index 5295128..ea83356 100644 --- a/documentation/getting_started.html +++ b/documentation/getting_started.html @@ -153,7 +153,7 @@

Now y -