📗 Webkit Manual

This topic is a part of the webkit documentation. For complete documentation on how the Webkit works please refer to the webkit documentation website. This guide is specifically to help project managers build and deploy Webkit sites from scratch.

Content

1. Getting Started

2. Configuration

3. Build


1. Getting Started

1.1. Prerequisites

Building the site requires a local installation of Node.js and NPM. Some basic knowledge of Git and the command line is required.

To install Node.js on your local machine, please refer to the official Node.js guide to installing Node on your local system.

NPM will be automatically installed with Node.js.

1.2. Cloning the repository

Download the latest version of the webkit by performing the following command in your terminal or by downloading it from the repository page in your browser.

git clone https://github.com/edgeryders/webkit_components.git webkit

Change directory into the new folder titled ‘webkit’ (this is the folder where the repository has been downloaded) and install local dependencies with the following command:

cd webkit && npm install

1.3. Running the development server

When dependencies have been installed, you can preview the site locally by running a development server:

npm run serve

You can then preview the site in your browser by visiting http://localhost:8080 in your browser.

The localhost address may be different depending on your setup, the terminal window will show which address to visit in any case.

When running on a local server, you will need to disable Cross Origin Restrictions. The Discourse API will not respond to queries from an unknown source. To disable this restriction:

  • In Chrome, use an extension such as CORS Unblock
  • In Safari, enable the develop menu and select ‘Disable Cross-Origin Restrictions’
  • For other browsers, search for guides online to Disable Cross-Origin Restrictions

2. Configuring

Now the site is locally installed, you will need to configure it.

Configuration of a webkit site is set up in the file config.json. To get to it, open the src folder, then the data folder, and open the config.json file in your code editor.

A basic configuration will include a title and site description, you can fill these in the “config” section of the JSON file.

 "config": {
   "title": "Site Title",
   "description": "Site description"
  }

2.1. Adding Blocks

The blocks object will determine the content of your site and the order of the content. Here is an example of the Header block:

"blocks": [{
   "type": "Header",
   "views": [
    {
      "menu": {  
          "config": {
             "links": "id"
           }
       },
       "hero": {  
          "config": {
             "template": "standard",
           },
           "title": "Webkit Sandbox",
           "text": "This is some text for the hero."
           "image": {
              "url": "https://erwebkit.netlify.app/edgeryders.svg",
              "width": ["100px", "160px"] 
            },
            "buttons": [
              {
                "text": "Link #1",
                "url": "#join"
              },
              {
                "text": "Link #2",
                "url": "#strategy"
              },
              {
                "text": "Link #3",
                "url": "#about"
              }
            ]
          }
        }
      ]
    }
}]

Each block contains one or more views to display content. The header block above, displays the menu and hero views.

block views
header hero, menu
content text, image, video, form
topics list, grid, slider
events list, grid, slider
footer text, image

For more on configuring each block, please refer to the site documentation on Blocks.

2.2. Adding Views to a Block

Views are responsible for the presentation of the data in a block.

To add a view to a block, pass it into the views array.

{
  "type": "Content",
  "id": "about",
  "views": [
     {
      "image": [{ "url": "https://placekitten.com/540/360", "size": 300 }],
      "text": "<h3 class='font-bold text-xl mb-3'>About this section</h3><p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</p>"
    },
   {
    "text": "This text view will appear beneath the two views"
   }
]
}

Here you’ll notice two views grouped together in the same object. This means these two views text and image will appear side by side on the site.

The following text view will take up the full width of the container and appear below the above views.

2.3. Changing the UI

Every block element can be styled differently in the configuration file.

Here is a list of what can be styled and with which properties. Some knowledge of CSS helps in understanding how these properties work, but is not essential.

object property
container width, padding, background, margin, class
wrapper width, padding, background, margin, class
title width, font, weight, class
text font, weight, class
button color, border, background, class

To configure a style for a block, use the style object inside the block. Here is an example of the content block with a custom title, text and wrapper style:

{
  "type": "Content",
  "id": "about",
  "style": {
    "wrapper": {
      "width": ["100%", "80%"],
      "padding": ["0", "30px 0px"],
      "class": ["border rounded-lg"]
    },
   "title": {
     "weight": ["bold", "normal"],
     "color": ["red", "black"]
   },
   "text": {
     "font": ["Georgia", "Helvetica"],
     "color": ["orange"]
   }
  }
}

You’ll notice each property is inside an array. The first value of the array will be applied to the mobile viewport, the second to the desktop viewport.

In this case the title font weight will be bold on phones, but normal on desktop. If there is only one value in the array, the property will be applied to both desktop and mobile. So the text color property will be orange, regardless of the viewport.

Properties follow the same logic as CSS. If we look at the padding property for the wrapper, it will have 30px of padding horizontally and 0px of padding vertically.

The class property will add css classes to the element. This is is useful for applying Tailwind CSS classes. In this case, the wrapper will be rounded (applying a border-radius to the element) and have a border of 1px. For more on the range of classes available, see the Tailwind Documentation here.

For more on styling each block, please refer to the site documentation on Styling.

3. Build

3.1. Building the site for production

When you have finished configuring the site, you will want to perform a build. Building will bundle the components into a minified javascript file, making the site ready to deploy on a server.

To perform a build, make sure you are not running a development server (hit Control-C to stop the server if this is the case). Type in the following command into the command line:

npm run build

This process will take about a minute, after which the the production ready version of the site will be created in a directory called dist at the root of the project.

This folder contains all the elements of the site, it can be uploaded via FTP to a server that serves HTML or to a service such as Netlify. To deploy to Netlify follow the next steps.

3.2. Deploying to Netlify

Login to the Edgeryders account on Netlify. If you are a project manager, look for the login credentials in our accounts topic or contact @owen, @hugi or @matthias.

Once logged in scroll to the bottom of the page where you will see this box:

From your file browser drag the dist folder to this box.

Netlify will begin the process of publishing the site. You will be redirected to the site information page and a domain will be automatically assigned to the site. You can change the domain by clicking on Domain Settings:

Assign a domain to the site you wish to use, or follow the instructions on Netlify for adding a custom domain.

3.3. CORS Whitelist

The final step is to add this domain to the CORS whitelist on the Discourse platform. Without this step, queries from this domain will be blocked which will prevent components from displaying data from Discourse. Contact @hugi or @matthias to add your domain to the list. When this is done, the site should be up and working.

3 Likes

As part of the documentation, the Webkit Sandbox allows you to preview sites using the topid_id of a post with the configuration. It also allows you to edit content fields without reloading the page. The sandbox can be used here:

The aim of this is to allow non developers to preview sites before deployment. However some knowledge of JSON, as well as looking at the example configuration topic will go a long way in helping you set up custom styling, fonts, content and sections.

1 Like

@noemi @MariaEuler @estragon

1 Like