Building my website with TowerBuilder

TowerBuilder is a system to generate websites with data visualizations that mix open contracting and beneficial ownership data, all without requiring programming knowledge. It is designed to follow the money in large contracting processes and has been used in both big public works (TorreDeControl.org) and in medicine procurement (VivirConVIH.org).

What do I need to create my own TowerBuilder website?

• Get an OCDS-format contracting list.
• Create a spreadsheet shared with contracting businesses owners.
• Write and edit text in MarkDown format.
• A GitHub.com account.

What are the advantages of creating websites using TowerBuilder?

• Default design doesn’t require any coding or web hosting, everything is done in GitHub.com
• Visually impressive data visualization and a useful contracting search system.
• If you already have the data, you’ll be able to create your website within minutes.
• Highly customizable design.
• You can use open data from your country’s government and show how useful the open contracting standard (OCDS) is for journalism.

If you find it difficult, you can try again in 15 minutes, check our Errors and corrections section, or ask for help.

Launched projects

• Living with HIV - [http://livingwithhiv.org/](http://livingwithhiv.org/)

Contact us to add your project created with TowerBuilder through the following e-mail address: info@quienesquien.wiki.

Demos

You can see an example page at:

Spanish: http://es.towerbuilder.projectpoder.org/

English: https://towerbuilder.projectpoder.org/

Documentation

Spanish: https://towerbuilder.readthedocs.io/es/latest/index.html

English: https://towerbuilder.readthedocs.io/en/latest/index.html

Building my website with TowerBuilder

TowerBuilder is a system to generate websites with data visualizations that mix open contracting and beneficial ownership data, all without requiring programming knowledge. It is designed to follow the money in large contracting processes and has been used in both big public works TorreDeControl.org and in medicine procurement VivirConVIH.org.

What do I need to create my own TowerBuilder website?

• Get an OCDS-format contracting list.
• Create a spreadsheet shared with contracting businesses owners.
• Write and edit text in MarkDown format.
• A GitHub.com account.

What are the advantages of creating websites using TowerBuilder?

• Default design doesn’t require any coding or web hosting, everything is done in GitHub.com.
• Visually impressive data visualization and a useful contracting search system.
• If you already have the data, you’ll be able to create your website within minutes.
• Highly customizable design.
• You can use open data from your country’s government and show how useful the open contracting standard (OCDS) is for journalism.

If, during this process you find anything to be difficult, you can try again in 15 minutes, check our Errors and Corrections section, or ask for help.

Launched projects

• Living with HIV - http://livingwithhiv.org/

Contact us to add your project created with TowerBuilder through the following e-mail address: info@quienesquien.wiki.

Demos

You can see an example page at:

Spanish: http://es.towerbuilder.projectpoder.org/

English: https://towerbuilder.projectpoder.org/

Documentation

Spanish: https://towerbuilder.readthedocs.io/es/latest/index.html

English: https://towerbuilder.readthedocs.io/en/latest/index.html

Fork the repository

In order to start building your website, you need to create your own repository first. A repository is the space where your website’s files are saved. You will be using a fork -that is, a copy- of TowerBuilder’s original repository.

1. You need sign in to GitHub.com. If you don’t have an account, you can create one over here.

   Disclaimer: GitHub.com is a Microsoft Inc. subsidiary that provides git repositories hosting and web hosting services in a free and simple way. That’s why we chose to use it for posting this project and our organization’s code.

2. GitHub will require an e-mail verification. For more information, you can read the official documentation.

3. In order to fork the repository, you need to browse to the repository’s home and click on “fork”, on the upper-right corner of the page. This will create a new page under your user, as in http://github.com/your_username/TowerBuilder. Now, you’ll start working there, and you’ll be allowed to modify files and publish sites. For further reading, check GitHub article about how to fork a repository. You can also read about forks in general.

4. To add outside collaborators, so they can edit data and texts, you must configure your repository according to the GitHub documentation.

Edit configuration

Now you can start building your website: you’ll have to define a project name and other settings. To do this, you must:

1. Browse to the settings file: To do so, enter your repository and search for the file named “_config.yml”.

2. Click on the file’s name to open it.

3. Click on the “edit” button on the upper-right corner.

4. Start changing values. This file is on a YAML format, which means it’s composed of a series of variables and its values. Each line starts with a variable name, and a colon (:) followed by a value.

   variable: value
   

   Don’t change the names of the variables, only make changes after the “:”.

   • Begin by changing the title variable. It defines your site’s name in different places, such as browser’s tabs, search results and the header of the site. For this, search where it says:

   title: "TowerBuilder"
   

   and replace the text between quotation marks with your site’s title:

   title: "South road's contracting analysis".
   

   • Other important values to change are:

   image: tb-logo.png -> change for the project logo, or leave it empty, it's optional.
   description: >-
    Modify the existing text and put your project's description here.
   

    - To enable or disable the top menu, toggle the following variable between true or false:
   

   top_menu: true
   

   • To change the title of the top menu item (appears when there are several items in the menu or when the window is adjusted to smaller screens):

   menu_button_title: More information
   

   To change the logo, follow these instructions.

   • To display the main name of your graphic on the Visualization slider, edit the following variable:

   graphTitle: "Graphic name"
   

   • Jekyll has a Plugins system that allows executing the customized code without a need to modify the Jekyll’s source. In the TowerBuilder’s configuration page, it’s represented in the following way:

   plugins:
     - jekyll-feed
     - jekyll-sitemap
   

   In this link, you can find more advanced information about the plugins.

   • To exclude any file, add it to the exclude section.

   exclude:
     - Gemfile
     - Gemfile.lock
     - node_modules
     - vendor/
     - docs/
   

   • Collections are an excellent way to group related content. This is how our configuration file shows TowerBuilder’s collections:

   collections_dir: collections
   collections:
     first-slider:
       output: true
     visualization-slider:
       output: true
   

   Important: This collections directory shouldn’t be edited. Collections can be added, but without deleting the default ones.

   For more information about collections, visit this page.

   • The last variables shown into “_config.yml” file are related to the options TowerBuilder has in order to show the articles:

   show_excerpts: true
   future: true
   

   If you want to know more about these options, visit this link.

If you want to learn about more advanced options of this configuration file, visit Jekyll’s official documentation.

To add analytics to the site, you can add one of these options:

# Analytics Configuration
jekyll_analytics:
  GoogleAnalytics:          # Add, if you want to track with Google Analytics
    id: UA-123-456          # Required - replace with your tracking id
    anonymizeIp: false      # Optional - Default: false - set to true for anonymized tracking

  Matomo:                   # Add, if you want to track with Matomo (former Piwik Analytics)
    url: matomo.example.com # Required - url to Matomo installation without trailing /
    siteId: "1234"          # Required - replace with your Matomo site id (Write id as string)

  Piwik:                    # Add, if you want to track with Piwik
    url: piwik.example.com  # Required - url to Piwik installation without trailing /
    siteId: "1234"          # Required - replace with your Piwik site id (Write id as string)

  MPulse:                   # Add if you want to track performance with mPulse
    apikey: XXXXX-YYYYY-ZZZZZ-AAAAA-23456   # Required - replace with your mPulse API key

  Plausible:
    domain: 'example.com'   # The domain configured in plausible
    source: 'https://plausible.example.com/js/plausible.js' # The source of the javascript

Importing data

Contracting data

For this section, the set of contracts you want to visualize must be formatted in OCDS, the open contracting data standard. You can use the Kingfisher tool to save to a local drive the listing of some OCDS sources. For more information, you can check Kingfisher’s full documentation. You can also check the OCDS Publisher full directory, which is updated quarterly.

OCDS standard is a model to publish and analyze contracting processes data. Data published under this standard is on JSON format and can appear in two ways: release and record. Generally, OCDS data is published in sets of contracting processes, known as packages. You can find Release Packages and Record Packages published by governments of several countries.

Data must be on a file named contracts.json and the file will be located in assets/data/. To upload the file to the GitHub repository:

• Browse to the repository’s home page.
• On the files list, click on the assets item.
• On the next page, click on the item named data.
• Once into the folder, click on “Upload files”, located in the file’s listing on the right corner of the screen. This will take you to another page.
• Choose the file from your computer or drag it into the browser. If you can’t see the button to upload files, you must log into GitHub with your username and password.

The data file must have a set of contracting processes in either records or releases. To allow the file to only contain an array records or releases, you might need to manipulate the file’s contents. For this, we recommend the ocdskit and jq tools.

Contracts.json file structure

Contracts.json file must keep to the structure of one of the following sort of data: Release Package or Record Package.

A Release Package is a JSON object with a property called «releases», which contains a a set of contracts in the form of an array, indicated by brackets []. It’s elements are individual objects of a release type, separated by commas (,). Each release type object corresponds to an individual contracting process.

{
    "releases": [
        { (release 1) },
        { (release 2) },
        ...
        { (release n) }
    ]
}

A Record Package is a JSON object with a property called «records», which contains a set of contracts in the form of an array, indicated by brackets []. It’s elements are individual objects of a record type, separated by commas (,). Each object of a record type is composed, in turn, of two properties: a «releases» property, which must keep to the same format as the Release Packages described before; and another property called «compiledRelease», which contains an individual object of a release type. Each release type object corresponds to an individual contracting process. The releases directory inside a record type of object contains the revision history for a contracting process, and the compiledRelease object contains the last version of each individual data of the same contract.

{
    "records": [
        {
            "releases": [
                { (release 1) },
                { (release 2) },
                ...
                { (release n) }
            ],
            "compiledRelease": { (latest version of the release) }
        },
        { (record 2) },
        ...
        { (record n) }
    ]
}

Note: Inside each release, certain fields need to contain some value so the graphics will display correctly. The mandatory fields are:

• ocid
• tender.title
• tender.mainProcurementCategory
• tender.procurementMethodDetails
• contracts.value.amount
• contracts.value.currency
• Inside the field “parties”, there should be at least one with role: [”supplier”] and values for the id and name fields.

Guide: Manually create a contracts set

1. Browse to a repository or open data API that offers OCDS-format contracting downloads. For this guide, we’ll use the API of Mexico’s federal government: https://api.datos.gob.mx/.

2. For this example, we’ll use a query for a JSON-format contract set.

3. Right-click this link and select “Save link as…”, then proceed to save the .json file.

4. Open a command prompt and browse to the downloaded file location. If you’ve never used a command prompt, you can read the following tutorials to learn more: Linux / Windows / Mac.

5. Use jq to work with JSON data and structure it as you need. You’ll find download and installation instructions for your operating system over here. You can learn how to use jq reading the official manual.

6. The API response consists of a root object that contains, among other things, the “results” property. The “results” value is the OCDS contracting directory that you need for TowerBuilder. With the following command (in Linux), you can take the items, put them inside an object named “releases”, and save them on a file under the name contracts.json:

   cat Releases_SFP.json | jq '{releases: .results}' > contracts.json
   

   • cat Releases_SFP.json read the Releases_SFP.json content and display it on screen.
   • | jq take the result of the previous command and send it to the jq command as input.
   • {releases: .results} filters the JSON received as input, take the “results” property value and save it on a new property named “releases”.
   • > contracts.json takes the result of the previous filter and saves it as a file called “contracts.json”, in the current folder.

7. Copy the file contracts.json to assets/data/ in your repository, as explained in the previous section.

Beneficial Owners Data

In order to complement the contracting processes data, you can display relations between it and the people and enterprises behind the entities that appear on data published under OCDS. Relations are expressed as a hierarchy tree. They can be among companies, like a parent company and its subsidiaries; or among companies and people, like shareholders and members of the board of directors. This hierarchy tree allows establishing who the beneficial owners of the analyzed contracting processes are.

A Beneficial Owner is any individual who, either directly or indirectly, owns, influences, controls and/or benefits of at least 5% of an asset through a corporation, commercial society or trust. For more information about Beneficial Owners, click here (link in spanish).

To create the Beneficial Owners dataset, download the template available in assets/data/BO-template.csv, and edit its values with a spreadsheet software, such as LibreOffice Calc, Excel, Google Spreadsheets, etc. The file contains the following columns:

1. NAME: the entity name (individual or enterprise) as shown on the OCDS data.
2. TYPE_ENTITY: “company” or “individual” depending on the entity defined on the first column.
3. RELATED_TO: The entity you want to define the relation with.
4. TYPE_RELATIONSHIP: How the entity on the first column is related to the entity on the third column. It may contain the following values:
   • “parent” to establish that the third column’s company is a subsidiary of the first column’s company.
   • “shareholder” when the first column’s individual is a shareholder of the third column’s company.
   • “boardmember” if the first column’s individual is part of the board of directors of the third column’s company.
5. POSITION: the position name the individual holds. It only applies to a TYPE_RELATIONSHIP with a value of “boardmember”.

Each row represents a branch of the hierarchy tree, starting from a base row that will only contain the company name on the first column and the word “company” on the second one. You should introduce the company name on each row, exactly as it appears on the contracting directory, so the graph can link the information. Let’s look at the following hierarchy:

• Company A (1) appears on a contracting process.
• Company B (2) is the parent company of Company A.
• Individual C (3) and Individual D (4) are shareholders of Company B.
• Individual E (5) and Individual F (6) are the President and Vice-president ofCompany B’s board of directors.

You must fill in the file in the following way, using one row per entity:

CSV Example

Repeat the same process for each company’s hierarchy you have data for. Once the file is complete, you can repeat the same procedure from the previous section to upload it to assets/data/. The file must be named owners.csv.

Editing texts

Editable text files are in MarkDown (.md) format.

Markdown is a light and user-friendly syntax used to style web texts. You are in control of the document visualization: you can bolden or italicize text, add images and create lists, among other things that can be done with MarkDown. Broadly speaking, Markdown is just plain text with some non-alphabetical characters, such as # or *.

We recommend reading Github’s Markdown guide to learn more about it.

Main texts

Main texts are composed of sections that appear on the main menu.

To edit files:

1. On GitHub’s repository, click on the title of the file you want to modify.
2. Click on the pencil icon located on the upper right corner (Edit this file).
3. Edit the text using Markdown format.
4. Once finished, go to the Commit changes section, underneath the edit section. Add a short description of changes you’ve made on the first box and, optionally, a longer description in the second box.
5. Save changes by clicking the green Commit changes button.

List of editable documents:

Home page

The main page consists of nine sections, each section is an editable file in markdown and contains variables with different options to configure the section, they are located in the collections folder as shown below:

• collections/_home/1-main.md
• collections/_home/2-intro.md
• collections/_home/3-section.md
• collections/_home/4-section.md
• collections/_home/5-section.md
• collections/_home/6-highlight-section.md
• collections/_home/7-section.md
• collections/_home/8-section.md
• collections/_home/9-contacto.md

You can change the name of these files, but keeping the numbering according to the order you want to follow in the final site.

Below we show and explain the variables that you must modify within the file of each section according to the content that you are going to add:

Cover page, file 1-main.md

In this section you can display a background image that occupies the entire screen, a main title or a logo, a short text and buttons.

Variables:

---
title: Home -> # The title of the section, this will be displayed in the menu that will appear on the right side of the screen.
main-section: true -> # Activate the styles, the main background image and the highlighted texts will display.
main-logo: todosloscontratoscr-logo-blanco.png -> # If you want to show your logo, add the name of the file that should already be in the folder **assets/img/**.

# Column options
one-column-section: true -> # It must be activated to show the section in a single column
---

Content:

Below the variables section, you can add the short text and buttons you need, in markdown format. We recommend keeping the length of the text found as an example.

Introduction, file 2-intro.md

In this section you can add a title, text, subtitles and add an image, video or iframe and a button. There is also the option to activate a notes section that will appear below.

Variables:

---
title: Introduction -> # Section title
cta-button-section: true -> # Activate if you want to show a button at the end of the section
button:
  link: "https://projectpoder.github.io/tolococr/" -> # Url button
  text: "Botón"  -> # Name button
# Media section
media: true -> # Activate to add an image, video or iframe, only choose one option
media-type: # Fill only one option
  image: -> # Add the name of the file that should already be in the folder assets/img
  iframe: https://link.com -> # Add iframe link
  video: https://youtube.com -> # Add video link

# If iframe, set the different iframe size, depending of de size screen
iframe-size: -> # This option will work if you added an iframe, you will be able to set the height of the iframe depending on the size of the screen
  xl-size: "20%" # Extra large screen ≥1280px
  lg-size: "30%" # Large screen ≤1279px
  md-size: "50%" # Medium screen ≤992px
  sm-size: "100%" # Small screen ≤768px
  xs-size: "120%" # Extra screen small <576px

# Column options
one-column-section: true -> # Activate to display the content in a single column

# Section background and text colors
background-color: "#ffffff" -> # Choose a background color of the section
text-color: "#333333" -> # Choose the color text of the section

# Article information -> # These variables activate the articles of this section
articles: true -> # Show articles
articles-section:
  background-color: "#EFEFEF" -> # Modify the background color of the entire article section
# Article 1
article-content: -> # Add an article information as the example text
  title: Article title
  author: Marisol Carrillo
  organization: PODER
  description: Proin tempus vehicula nibh, et mollis erat consequat sit amet. Aliquam molestie, elit feugiat sagittis luctus, ex lorem ultrices elit, ac molestie orci elit eu nisi. Phasellus accumsan fringilla ligula, id vulputate lorem bibendum in. Fusce congue ullamcorper tempus. In metus velit, finibus et libero nec, tempus aliquam metus.
  image: bg-masthead.jpg
  link: https://github.com/ProjectPODER
# Article 2
article-content2: -> # Second article information
  title: Article title 2
  author: Marisol Carrillo
  organization: PODER
  description: Proin tempus vehicula nibh, et mollis erat consequat sit amet. Aliquam molestie, elit feugiat sagittis luctus, ex lorem ultrices elit, ac molestie orci elit eu nisi. Phasellus accumsan fringilla ligula, id vulputate lorem bibendum in. Fusce congue ullamcorper tempus. In metus velit, finibus et libero nec, tempus aliquam metus.
  image: bg-masthead.jpg
  link: https://github.com/ProjectPODER
---

Content:

After the variables section, you will be able to add text and subtitles in markdown format. You can add the text you want, there is no limit here.

One column general section, file 3-section.md

Esta sección general, contiene un título, texto, la opción de mostrar una imagen, video o iframe, un botón y una sección de notas. Es la misma estructura que la Introducción y se muestra en una sola columna.

Variables:

title: One column section
cta-button-section: true
button:
  link: "https://projectpoder.github.io/tolococr/"
  text: "Button"
# Media section
media: true
media-type:
  image: graphic-example1.png
  iframe:
  video:
# Column options
one-column-section: true

# Section background and text colors
background-color: "#ffffff"
text-color: "#333333"

# Article information
articles: true
articles-section:
  background-color: "#EFEFEF"
# Article 1
article-content:
  title: Article title
  author: Marisol Carrillo
  organization: PODER
  description: Proin tempus vehicula nibh, et mollis erat consequat sit amet. Aliquam molestie, elit feugiat sagittis luctus, ex lorem ultrices elit, ac molestie orci elit eu nisi. Phasellus accumsan fringilla ligula, id vulputate lorem bibendum in. Fusce congue ullamcorper tempus. In metus velit, finibus et libero nec, tempus aliquam metus.
  image: bg-masthead.jpg
  link: https://github.com/ProjectPODER
# Article 2
article-content2:
  title: Article title 2
  author: Marisol Carrillo
  organization: PODER
  description: Proin tempus vehicula nibh, et mollis erat consequat sit amet. Aliquam molestie, elit feugiat sagittis luctus, ex lorem ultrices elit, ac molestie orci elit eu nisi. Phasellus accumsan fringilla ligula, id vulputate lorem bibendum in. Fusce congue ullamcorper tempus. In metus velit, finibus et libero nec, tempus aliquam metus.
  image: bg-masthead.jpg
  link: https://github.com/ProjectPODER

Content:

After the variables section, you will be able to add text and subtitles in markdown format. You can add the text you want, there is also no limit.

Two columns section, file 4-section.md

In this section you can show a title, a text and an image, video or iframe in two columns and a colored background, the background color is taken from the primary color configuration of the site.

Variables:

---
title: Section 4
# Media section
media: true -> # Activate an image, video or iframe, only one option
media-type:
  image: graphic-example1.png -> Name of the file that should already be in the folder assets/img
  iframe: -> # Iframe link
  video: -> # Video link
# Column options
one-column-section: false -> # Deactivate one column
two-columns-section: true -> # Activate two columns
# If two columns is true
# Media position
media-left: false - > # In this section we will show the image, video or iframe in the right column if this option is false
# Section background and text colors
background-color: "#ffffff" -> # Select the background color of the entire section
text-color: "#ffffff" -> # Select the text color of the entire section

---

Content:

Add the title and the text in the left column, we recommend short text.

Two columns section, file 5-section.md

This section is the same as the previous one, but you can show the image, video or iframe in the left column and show the article section below.

Variables:

---
title: section 5
# Media section
media: true
media-type:
  image:
  iframe:
  video: https://www.youtube.com/embed/TYCBicKyVhs -> # Add a video

# Column options
one-column-section: false
two-columns-section: true
# If two columns is true
# Media position
media-left: true -> # Activate the option to show the image, video or iframe in the left column
# Section background and text colors
background-color: "#ffffff"
text-color: "#ffffff"

# Article information
articles: true -> # Activate article section
articles-section:
  background-color: "#EFEFEF"
# Article 1
article-content:
  title: Título de la nota
  author: Marisol Carrillo
  organization: PODER
  description: Proin tempus vehicula nibh, et mollis erat consequat sit amet. Aliquam molestie, elit feugiat sagittis luctus, ex lorem ultrices elit, ac molestie orci elit eu nisi. Phasellus accumsan fringilla ligula, id vulputate lorem bibendum in. Fusce congue ullamcorper tempus. In metus velit, finibus et libero nec, tempus aliquam metus.
  image: bg-masthead.jpg
  link: https://github.com/ProjectPODER
# Article 2
article-content2:
  title: Título de la nota 2
  author: Marisol Carrillo
  organization: PODER
  description: Proin tempus vehicula nibh, et mollis erat consequat sit amet. Aliquam molestie, elit feugiat sagittis luctus, ex lorem ultrices elit, ac molestie orci elit eu nisi. Phasellus accumsan fringilla ligula, id vulputate lorem bibendum in. Fusce congue ullamcorper tempus. In metus velit, finibus et libero nec, tempus aliquam metus.
  image: bg-masthead.jpg
  link: https://github.com/ProjectPODER
---

Contenido:

Add the title and the text in the right column.

Highlight section, file 6-highlight-section.md

In this section you can highlight content, it consists of a title, text and a button, you can modify the background color of the section and the box containing the text.

Variables:

---
title: Highlight
cta-button-section: true
button:
  link: "https://projectpoder.github.io/tolococr/"
  text: "Botón"
# Highlight section options
highlight-section: true -> # Activate to show the styles of the highlight section
highlight-section-background: "#006607" -> # Add a background color to the text container
# Column options
one-column-section: true -> # Show one column

# Section background and text colors
background-color: "#ffffff"
text-color: "#ffffff"
---

Content:

Add a title or subtitle and a highlight text.

General section in one column, file 7-section.md y 8-section.md

Esta sección muestra títulos, textos, imagen, video o iframe y un botón, en una columna. La configuración del ejemplo muestra secciones simples de texto. This section shows titles, texts, image, video or iframe and a button, in one column. The example shows simple text sections.

Variables:

---
title: About the project
cta-button-section: false
button:
  link: "https://projectpoder.github.io/tolococr/"
  text: "Button"
# Media section
media: false
media-type:
  image:
  iframe:
  video:
# Column options
one-column-section: true

# Section background and text colors
background-color: "#ffffff"
text-color: "#333333"

---

Content:

Add headings or subheadings and paragraphs of text as needed. There is no text limit here.

Contact section, file 9-contacto.md

You can add the title, a text and a link that goes to the place where you want to be contacted.

Variables:

---
title: Contact
cta-button-section: true
button:
  link: "https://projectpoder.github.io/tolococr/"
  text: "Button"

# Column options
one-column-section: true

# Section background and text colors
background-color: "#97C461"
text-color: "#333333"

---

Content:

Add a title and text.

Footer

To edit the footer, you’ll need to edit the files in the collections/_footer folder. You will find two files called column-1.md or column-2.md, each file has variables to configure the section, where you can add a title and a logo.

Variables:

---
title: Project of -> # Column title
image-logo: logoPODER_19.png -> # File name that should be in the folder assets/img
image-name: PODER logo -> # Image name
width-logo: 100px -> # Image size
# If there are more logos
image-logo2: Innovaap_logo.png -> # You can add a second logo in the same column
image-name2: Innovaap logo
width-logo2: 170px
---

Embed Kibana iframes

We explain the steps to follow to embed a Kibana iframe correctly:

• In Kibana, select the share option to embed the visualization (it can be reached from the dashboard edit option).
• The visualization must be on Simona.
• Copy the visualization to public space from saved objects, searching by name, choosing “clone to space” and choosing public.
• Go to the public space, find the visualization, select share and then embed.
• The choice of snapshot or saved object depends on whether we want the numbers to be updated (saved object) or if we want them to always stay that way (snapshot).
• From the copied url, remove everything except the url that is in quotes in src.
• Put this url in the iframe variable of the section in which you want to add it.

Example:

title: Introduttion
cta-button-section: false
button:
  link:
  text:
# Media section
media: true
media-type: # Fill only one option
  image:
  # Add the iframe link
  iframe: "https://publico-simona.quienesquien.wiki/s/publico/app/visualize#/edit/e5b829d0-ca23-11eb-b96d-0715cd05503e?embed=true&_g=(filters:!(),refreshInterval:(pause:!t,value:0),time:(from:'2008',to:'2019'))&_a=(filters:!(),linked:!f,query:(language:kuery,query:''),uiState:(),vis:(aggs:!((enabled:!t,id:'1',params:(customLabel:'Cantidad%20de%20contratos'),schema:metric,type:count),(enabled:!f,id:'2',params:(customLabel:'Suma%20de%20monto',field:monto),schema:metric,type:sum),(enabled:!t,id:'3',params:(customLabel:'Cantidad%20de%20Adjudicatarios',field:adjudicatario.keyword),schema:metric,type:cardinality),(enabled:!t,id:'5',params:(customLabel:'Cantidad%20de%20Instituciones',field:institucion.keyword),schema:metric,type:cardinality),(enabled:!t,id:'6',params:(customLabel:'Cantidad%20de%20municipios',field:municipio.keyword),schema:metric,type:cardinality)),params:(addLegend:!f,addTooltip:!t,metric:(colorSchema:Greens,colorsRange:!((from:0,to:100),(from:100,to:10000),(from:10000,to:30000),(from:30000,to:40000),(from:40000,to:500000)),invertColors:!f,labels:(show:!t),metricColorMode:Background,percentageMode:!f,style:(bgColor:!f,bgFill:%23000,fontSize:60,labelColor:!f,subText:''),useRanges:!f),type:metric),title:SICOP_DASH_numeros,type:metric))"
  video:

# If iframe, set the different iframe size, depending of de size screen
iframe-size: -> # This option will work if you added an iframe, you will be able to set the height of the iframe depending on the size of the screen
  xl-size: "20%" # Extra large screen ≥1280px
  lg-size: "30%" # Large screen ≤1279px
  md-size: "50%" # Medium screen ≤992px
  sm-size: "100%" # Small screen ≤768px
  xs-size: "120%" # Extra screen small <576px

To edit texts on the About page:

• 4-about.md

To edit texts on each slide:

• collections/_first-slider/slide-1.md
• collections/_first-slider/slide-2.md
• collections/_first-slider/slide-3.md

To add or remove a slide, just add or remove an .md file inside _first-slider folder.

If you want to change or add an image (.jpg, .png or .svg) inside the slider, you should add the image inside the assets/img/ folder and add the file’s name to the file corresponding to the slide where images will be.

---
title: First Slide
**image: graphic-example.png** -> file's name will be here.
---

To edit the visualization slider captions:

• collections/_visualization-slider/slide-1.md
• collections/_visualization-slider/slide-2.md
• collections/_visualization-slider/slide-3.md

Page names and permalinks

You can edit the name and permalink of each section that will be shown on the main menu.

To do this, find and edit this part:

---
layout: home
title: Home
permalink: /
---

To change the page’s name, edit:

---
title: Page name
---

To change the permalink, edit:

---
permalink: /page-link/
---

Changing the order of items on the main menu

Since TowerBuilder adds items to the main menu in alphabetical order, a custom order can be achieved by editing the numbers at the start of each file’s name.

This is the default order:

1. home
2. slider.html
3. visualization-slider.html
4. contracts.html
5. posts.md
6. about.md
7. styleguide.md

These are the steps to edit the name of a GitHub file:

1. On GitHub’s repository, click on the title of the file you want to modify.
2. Click on the pencil icon located on the upper right corner (Edit this file).
3. Edit the name in the filename box, located above the edit section.
4. Once finished, go to the Commit changes section, underneath the edit section. Add a short description of changes you’ve made on the first box and, optionally, a longer description in the second box.
5. Save changes by clicking the green Commit changes button.

Add a new page

To add a new page, you can create a file where you can add text in markdown format.

Steps to create a file are:

1. In GitHub, go to the repository’s home page and open the folder where you want to create a file.

2. Click on Create new file, located above the upper-right corner of the file list.

3. On Name your file box, write the file’s name with its extension.

4. Write the contents of the file in the Edit new file tab.

5. Always add the following file’s start code to new files created:

   ---
   layout: page -> must always be **page**
   title: Page name -> the title you chose for the page
   permalink: /link-name/ -> change it for the link you want to show
   ---
   

6. To review the content, click on Preview.

7. Once finished, go to the Commit New File section, underneath the edit section. Add a short description of changes you’ve made on the first box and, optionally, a longer description in the second box.

8. Save changes by clicking the green Commit changes button.

For more in-depth information of how to create a new file, visit Github’s official documentation.

Add a menu item

When creating a new page that contains the header described above, it will automatically be added to the bottom of the menu.

If you want to change the order that the page should appear in the menu, place the corresponding number and modify the numbers of the elements that are already there. To rename a file, follow the Github documentation here.

Hide/Delete a menu item

Removing a menu item is easy, you just need to delete its file.

If you want to delete a GitHub file:

1. Click on the file you want to delete.
2. On the upper part of the document, click on the trash can icon.
3. At the end of the page, add a short description of changes to Commit new file, the section’s first box. You can optionally add a longer description in the following box.
4. Save changes clicking on the green Commit changes button.

If you want to exclude a page from the menu, but not delete the file and offline, you should only add to the header “published: false”:

---
published: false
permalink: /link/ -> Offline page.
---

If you want to exclude the menu item, but keep the page online, you must delete the header title:

---
layout: page
title: Page name -> Delete this line.
permalink: /link/ -> Online page
---

Note: With these options, you can hide or delete any section like the Slider, the Visualization or the Styleguide page of your final project.

Edit the More information menu button title

To change the button title that appears when you reduce the screen width, you only have to change the text in the file _ config.yml of the next variable:

menu_button_title: More information -> change it to the text you want

Edit the Contracts search page titles

You can change the different filter titles of the contracts search page and the table columns titles in the file _ config.yml, this is an example of the default configuration:

contracts_title: Contracts by companies
search_title: Search
search_placeholder: Enter keyword to search
amount_title: Total amount (Mexican pesos)
amount_from_placeholder: From $
amount_to_placeholder: to $
type_contract_title: Type of contract
type_contract_title_tooltip: The law requires that the Buyer defines the type of contract because the rules vary in each case.
type_contract_all_option: All
type_procedure_title: Type of procedure
type_procedure_title_tooltip: La licitación pública es según la ley mexicana el procedimiento adecuado para contratar obra publica. Excepcionalmente también se pueden realizar otro tipo de procedimientos como adjudicación directa, convenio e invitación a cuando menos tres proveedores.
type_procedure_all_option: All
date_range_title: Date range
date_range_from_placeholder: From
date_range_to_placeholder: to
date_range_title_tooltip: Find active contracts between two dates.
filter_footnote_title: Apply filters on contracts with companies.

# Customize the Contract table titles
column_1: Companies
column_2: No. of contracts
column_3: Total amount

Changes can be seen in this section:

Articles

Articles are notes that analyze contracts, and are linked to them in the graph.

Create an article

To post an article in your repository:

1. Go to the _posts folder, inside the collections folder.
2. Click on Create new file.
3. Write the new file’s name. TowerBuilder won’t be able to read it unless it’s formatted this way:

YEAR-MONTH-DAY-title.MARKUP

YEAR is four-digit, MONTH and DAY are two-digits; title: the desired title; MARKUP: file extension

The following names are both valid:

2018-12-31-new-years-eve-is-awesome.md
2018-09-12-how-to-write-a-blog.md

1. All articles have to start with the following header:

---
layout: post -> All articles are post type.
title:  "Welcome to Jekyll!" -> The name you want for your article.
author: "Name" -> The author's name for your article.
---

1. Write the contents of the article. You can format it using Markdown, as in all other editable texts.
2. To link with graphic, you must know its OCID contract identifier, and add it to the header like this:

person: Juan Carlos Dueño

To save the new file, click on the Commit new file button after adding a comment about it.

If you wish to know all possible options for articles headers and other related settings, visit this link.

Important: All modifications are automatically reflected on the public site, although this process may take several minutes to take place.

Publish the website

Important: Before publishing your site, make sure to delete the content of the ** CNAME ** file or replace the content with the url of your website.

Once you’ve configured your website, imported data and edited texts, you can publish the website to verify that everything works as it should.

At first, your username and the repository name will be reflected on your website URL address once it’s published. It should be your_username.github.io/your_repository.

1. Below your repository name there are several tabs. Click on the last one: “Settings”.

2. Scroll down to GitHub Pages section, and click on Source the master branch option.

3. The page will refresh, scroll down again to Github Pages and you should see Your site is ready to be published at your_url on top of the section.

   Note: After publishing your site for the first time, you can customize the URL. For more information about setting your website address, click here.

4. Click on the URL to see your published site.

For more information, you can check GitHub’s official documentation.

Important: Don’t use the same URL as in the original repository because you won’t be able to see the site.

Iframe versions

Tower Builder has versions that can be inserted as an iframe in other websites, after publishing your site you can access this version by adding the parameter ?iframe to your url. For example, to see the iframe version of our demo, you can visit this link:

https://towerbuilder.projectpoder.org/?iframe.

To insert the visualization or slider iframe, add to your url /iframe-visualization or /iframe-slider, you can see an example of our demo in the following links:

https://towerbuilder.projectpoder.org/iframe-visualization/

https://towerbuilder.projectpoder.org/iframe-slider/

TowerBuilder updates

TowerBuilder, the base with which you are building your website, may have occasional updates, which means that if you want to have the latest safety updates, you need to keep your repository synchronized with the original. The process to synchronize repositories consists of the following steps:

1. In your browser, open the repository home page (https://github.com/your_username/TowerBuilder).
2. Click on the “Compare” button, located above the upper-right corner of the files directory.
3. The next screen will show the changes you made on your TowerBuilder version, but this isn’t exactly what we want to see, we want to see the changes made in TowerBuilder’s original repository. Below the title, there is a drop-down menu to select the repository. Use it to select yours.
4. On the next screen, right below “Comparing changes” there is a text that reads “Choose two branches to see what’s changed or to start a new pull request. If you need to, you can also compare across forks”. Click on “compare across forks”.
5. You’ll see the previous screen drop-down menus are enabled again. Now you’ll need to use the third selector from the left to choose Towerbuilder’s base repository (ProjectPODER/TowerBuilder). This will show all changes made on the master repository, which are the updates you need for your repository. If you have no updates, “There isn’t anything to compare” will pop up and you won’t need to continue.
6. Click on the green “Create pull request” button. A text editor will pop up where you can enter a message. You don’t have to, but it’s better to add one that states you’re updating from the master repository.
7. You can click again the green “Create pull request” button.
8. In the following screen, a green icon with a check mark should show there are no conflicts. If there are any conflicts between the repositories, this icon won’t appear and updates won’t continue. You need to click right under the green “Merge pull request” button icon. The button’s text will change to “Confirm merge”, click it again to finish the synchronization process.

Follow these steps periodically to keep up with changes and upgrades of the master repository.

Define your site’s address

By default, your username and the repository name will be shown on your website URL address once it’s published. It should be: your_username.github.io/TowerBuilder.

1. If you wish to change your_username, you can change your username or create an organization account in Github and choose the organization when you fork the repository. If you’ve already created the repository, you can move it to the organization account.
2. If you wish to change the TowerBuilder part, you can rename the repository.
3. GitHub.com allows the use of custom domains, you can check the documentation here.

Using a custom subdomain

To use a custom subdomain, you need to modify its DNS. You can do it on the website where the domain has been registered.

You need to add a CNAME that takes you to username.github.io. For more details, check GitHub’s documentation.

Important: Don’t use the same URL as in the original repository because you won’t be able to see the site.

Give your own style to your website

You can customize the style of TowerBuilder. You can change color, typography, home page background image, and text size.

To edit styles, open _variables.scss, located in _sass/. In this file, you’ll find some variables you can modify.

The file is a .scss, which is a version of CSS. It is comprised of a series of variables with its values. Each line starts with a variable name, and a colon (:) followed by a value.

$variable: value

Never change the variables names, only change the value after the colon.

Change the colors

These are the color default variables:

$blue:    #007bff !default;
$indigo:  #6610f2 !default;
$purple:  #6f42c1 !default;
$pink:    #e83e8c !default;
$red:     #dc3545 !default;
$orange:  #fd7e14 !default;
$yellow:  #ffc107 !default;
$green:   #28a745 !default;
$teal:    #20c997 !default;
$cyan:    #17a2b8 !default;

Web colors are expressed in hexadecimal, for example: #007bff.

You can modify the default color tones changing its hexadecimal value or, just for the colors section, adding variables with new colors. For example:

To change the tone, change
$blue:    #007bff !default;
for
$blue:    #0056b2 !default;

To add a new color
$turquoise: #40e0d0;

TowerBuilder main color is defined in the $primary variable, default color is $blue. If you want to change color, just replace it with any color you want:

Change
$primary:       $blue !default;
for
$primary:       $turquoise !default;

Or leave it as it is, if you just changed the color tone.

We recommend you this website to find the colors hexadecimal codes.

Changing the preloader colors

The preloader appears when the slider and the visualization are loading, to change the colors you just have to place the color you want in the next variables:

$preloader-color1: #1ee6d3;
$preloader-color2: #343a40;
$preloader-color3: $primary;

Changing the home page background image

The background image is defined by the $bgHome variable:

$bgHome : "./img/bg-masthead.jpg";

1. To change it, you’ll need to copy the image file to the folder assets/img/, in jpg or png format.

2. Then, go to _variables.scss and edit the $bgHome variable:

   Change the Default
   $bgHome : "./img/bg-masthead.jpg";
   for
   $bgHome : "./img/your-file-name.jpg";
   

Changing the logo

1. Copy your logo image file to the folder assets/img/, in jpg, png or svg format.
2. Go to the configuration file (_config.yml) and edit the value of the image variable with your logo filename:

image: tb-logo.png

Changing favicon

1. Replace the file on the project root, named favicon.png, with your favicon. It must have the same name and, preferably, 32 x 32 pixels.

Mobile-friendly visualization

By default, the 3-visualization-slider.html file has configured the option “responsive” as “true” for better browsing experience on mobile devices:

---
layout: default
title: Visualization
permalink: /visualization/
responsive: true
---

Visualization needs to display properly in mobile devices. To achieve this, you’ll have to turn each visualization into image (.png or .jpg) once you have your graphic, add the images into the folder assets/img/, then add the name of your image on each corresponding slide header. For example:

---
title: First Slide
image: your-graphic.png -> Add the name of your image.
---

You can also deactivate the “responsive” option and avoid placing the image in each slide, just delete all the line responsive: true in the file header 3-visualization-slider.html and delete the entire line that begins with image: from the header of each slide.

Why is the graphic not showing?

It could be because contracts.json is not formatted properly. Please refer to our documentation to help you check any errors.

Why are my articles not showing in the graphic?

Check that each article name is in the right format or correctly linked, as we explain here.

Why is my text or article format broken?

Check that the file has an .md format.

Check if the file has the right header, as we explain here.

Check you’re using items that accept Markdown format. You can look through the official documentation over here.

I have another issue

If you find any problem that isn’t contemplated in this manual, or if you need help creating your website, you can get in touch with PODER through the following e-mail address: info@quienesquien.wiki.

On the other hand, you can also report an issue to GitHub through the following link: https://github.com/ProjectPODER/TowerBuilder/issues.