Widget

Installing

You can easily add our data to your website by using our widget. Connect our script on your webpage, preferably before the closing body tag:

<script src="https://avoid-crowds.dev/js/widget.js"></script>

This script requires JS library to make the widget work. There are no dependencies, just this one - widget.js

Also, pay attention that if you use more than one widget on single page, don't add <script src="https://avoid-crowds.dev/js/widget.js"></script> more than one time.

Add widget markup

After script installation, create a HTML block where you want to add the text or chart widget with a unique id. It can be any HTML code inside this block with placeholder values. When widget.js will start to initialize, placeholdres will be replacing by values. There are two different widget components that can be used inside a HTML block:

  1. Text widget

  2. Chart widget

After creating a HTML block, add the following parameters:

<div id="widget"
     data-token="YOUR_TOKEN"
     data-region="YOUR_REGION"
     data-date="DATE_FOR_TEXT_WIDGET"
     data-days-between="DAYS_INTERVAL_FOR_CHART"
></div>

List of HTML block parameters:

  • data-token - insert your token, which you can get by contacting us via email;

  • data-region - insert any available region from this list;

  • data-date - insert date which you want to display in the widget. Works for text widget only. Available formats: Y-m-d (For example, 2019-05-25) + (For example, +6 days) - (For example, -6 days) ago first (For example, first day of this month) next (For example, next tuesday) last (For example, last day of this month) this (For example,this friday) yesterday today tomorrow

  • data-days-between - two dates separated by comma with the same format as the for date parameter. Using for chart widget. For example: first day of this month,last day of this month

On render action, all of this parameters (and your token too) will be removing from HTML.

Now, code should be looks like that (inside your <body> tag):

<div id="widget"
     data-token="YOUR_TOKEN"
     data-region="YOUR_REGION"
     data-date="DATE_FOR_TEXT_WIDGET"
></div>
<script src="https://avoid-crowds.dev/js/widget.js"></script>

For rendering the chart widget you have to write a block with a unique id for the chart. 

<div id="widget"
     data-token="YOUR_TOKEN"
     data-region="YOUR_REGION"
     data-days-between="DAYS_INTERVAL_FOR_CHART"
>
     <div id="chart"></div>
</div>
<script src="https://avoid-crowds.dev/js/widget.js"></script>

Callback function

When you will connect the widget.js file and create the HTML block, you have to add a callback function to your webpage:

<script>buildAvoidCrowdsWidget('#YOUR_BLOCK_ID');</script>

Callback function has two parameters:

  • widgetID

  • chartID inside widget ID

So, if you will use the chart widget or chart widget + text widget, you have to write the function with a second parameter:

<script>
    buildAvoidCrowdsWidget('#YOUR_BLOCK_ID', "#YOUR_CHART_ID");
</script>

Text widget

Text widget can be used for displaying data about a single day. Just write any markup code created in the previous chapter inside the widget tag to customize how our data is displayed.

List of placeholders: {{text.date}} - crowd entry date in Y-m-d format; {{text.title}} - crowd entry title; {{text.link}} - link on this day to avoid-crowds.com landing page; {{text.avoid_crowds_score}} - avoid crowds score from 0 to 100; {{text.total_cruise_passengers}} - total number of cruise passengers arriving in the selected city on the selected day. Can be empty for some cities, dates and other entries (eg. no cruise traffic for land locked Madrid); {{text.total_cruise_crew}} - total cruise crew in this city for this date. Can be empty for some cities, dates and other entries; {{text.ships_in_port}} - ships in port in this city for this date. Can be empty for some cities and entries; {{text.local_public_holiday}} - local public holiday in this region for this date (yes/no); {{text.local_school_vacation}} - local school vacation in this region for this date (yes/no); {{text.local_events}} - local events in this region for this date; {{text.vacations}} - overview of countries with school vacations for given date;

For advanced rendering placeholders you can check VueJS documentation in Template Syntax page.

Example of widget code after connecting scripts to HTML document:

index.html
<div id="widget"
     data-token="YOUR_TOKEN"
     data-region="YOUR_REGION"
     data-date="DATE_FOR_TEXT_WIDGET"
>
    <a :href="text.link"><h1>{{text.title}}</h1></a>
    <ul>
        <li>Date: {{text.date}}</li>
        <li>Avoid crowds score: {{text.avoid_crowds_score}}</li>
        <li>Total cruise passengers: {{text.total_cruise_passengers}}</li>
        <li>Total cruise crew: {{text.total_cruise_crew}}</li>
        <li>Ships in port: <span v-html="text.ships_in_port"></span></li>
        <li>Local public holiday: <span v-html="text.local_public_holiday"></span></li>
        <li>Local school vacation: <span v-html="text.local_school_vacation"></span></li>
        <li>Local events: <span v-html="text.local_events"></span></li>
        <li>Vacations: {{text.vacations}}</li>
    </ul>
</div>
<script src="https://avoid-crowds.dev/js/widget.js"></script>
<script>buildAvoidCrowdsWidget('#widget');</script>

Expected result:

Chart widget

For rendering our chart inside your block, add the folowing element with unique id inside your widget. Don't forget about the data-days-between parameter! Check example code below: 

<div id="widget"
     data-token="YOUR_TOKEN"
     data-region="YOUR_REGION"
     data-days-between="DAYS_INTERVAL_FOR_CHART"
>
    <h2>Average crowds score: {{chart.average_crowds_score}}</h2>
    <div id="chart"></div>
</div>

<script src="https://avoid-crowds.dev/js/widget.js"></script>
<script>
    buildAvoidCrowdsWidget('#widget', "#chart");
</script>

Expected result:

You can also use placeholders for the chart widget in your HTML code:

  • {{chart.average_crowds_score}} - average crowds score for this time period;

  • {{chart.link}} - link on this region;

Other

By combining this two widgets, you can achieve mixed view: text + chart. Check full correct code of working example:

<div id="widget"
     data-token="YOUR_TOKEN"
     data-region="YOUR_REGION"
     data-date="DATE_FOR_TEXT_WIDGET"
     data-days-between="DAYS_INTERVAL_FOR_CHART"
>
    <a :href="text.link"><h1>{{text.title}}</h1></a>
    <ul>
        <li>Date: {{text.date}}</li>
        <li>Avoid crowds score: {{text.avoid_crowds_score}}</li>
        <li>Total cruise passengers: {{text.total_cruise_passengers}}</li>
        <li>Total cruise crew: {{text.total_cruise_crew}}</li>
        <li>Ships in port: <span v-html="text.ships_in_port"></span></li>
        <li>Local public holiday: <span v-html="text.local_public_holiday"></span></li>
        <li>Local school vacation: <span v-html="text.local_school_vacation"></span></li>
        <li>Local events: <span v-html="text.local_events"></span></li>
        <li>Vacations: {{text.vacations}}</li>
    </ul>

    <div id="chart"></div>
    <div>
        Average crowd score: {{chart.average_crowds_score}}
    </div>
</div>

<script src="https://avoid-crowds.dev/js/widget.js"></script>
<script>
    buildAvoidCrowdsWidget('#widget', '#chart');
</script>

Expected result:

Add our widget to your WordPress blog

Adding our widget to a WordPress blog is east. Just repeat our instructions from the previous sections. For example, this is how you add a chart widget in the Wordpress widget area.

  1. Go to WordPress admin page;

  2. Menu item: Appearance > Widgets;

  3. Drag and drop widget "Custom HTML";

  4. Insert code from chart widget example above.

How it looks like:

The result:

OK. But how do you integrate our data in posts, pages or elsewhere on your Wordpress blog? The easiest way to do this is by using Gutenberg - more modern solution for writing articles. If you are using an old editor, just insert the same code in HTML. If you are using Gutenberg, read instructions:

  1. Create a new or edit an existing post;

  2. Add new Gutenberg block or Custom HTML;

  3. Insert HTML code from our widget;

  4. Save the post.

You can customize and improve your widgets. Widgets can have any custom HTML inside with your CSS customizations: text colors, paddings, margins, element's width and height. We did that on purpose, so you are able to give your own look and feel to our data.

Also, pay attention that if you use more than one widget on single page, don't add <script src="https://avoid-crowds.dev/js/widget.js"></script> more than one time.

PreviousREST APINextAdditional information

Last updated