Webkit Usage

This is a step-by-step guide to making an Edgeryders website with the webkit.

Content

Understanding the webkit and why we use it

  • Why we need the webkit and when to use it
  • How it works: introducing configuration posts

Step 1: Make the design decisions

Step 2: Prepare the content

  • Choose and structure a home for your content
  • Make or choose high-quality content

Step 3: Prepare the configuration post

  • Make a copy of the example configuration post
  • Edit the Config block
  • Edit the Menu block
  • Edit the Header block
  • Choose, arrange and edit the Content blocks
    • Static text Content blocks
    • Discourse category Content blocks
    • Discourse tags Content blocks
    • Form Content blocks

Step 4: Finishing touches

  • Themes
  • Polish
  • Third-level domain

Understanding the webkit and why we use it

Why we need the webkit, and when to use it

The webkit is a piece of software that lives on the Edgeryders server. It creates instant websites based on files of a special type, called the configuration files. Each configuration file generates a website. The webkite can in theory support an infinite number of websites. This addresses a strong need in Edgeryders, that of having multiple, simple, specialized websites. The platform is great, but it is very big (70,000 posts) and can be intimidating. For example, you could want a simple website for your unit (like this, or for an event you are organizing.

The webkit allows us to do this, with:

  • No need to install anything. No matter how many websites we make, they are all created by the one installation already on our server.
  • No need for software other than the browser you already use to access the Edgeryders platform.
  • Full compatibility with the platform. You can tell the webkit to display on your website the content of a single Edgeryders post, but also of a category, or a Discourse tag. Anything you can display on edgeryders.eu you can also display on a webkit website.
  • Automatic updating. Suppose your website contains a feed from the Campfire category: when a new post is made in that category on the platform, it will automatically show up on the website. This last feature is useful because it means we can control what’s on our website simply by making normal edits to posts on the platform. For example the list of projects here: Edgeryders | Start is taken from this post. If we want to add a project we just need to edit the post, and it shows up automatically on the website.

How it works: introducing configuration posts

To access a webkit website, type in the address box of your browser:

https://live.edgeryders.eu/12345

Where 12345 is the number of a topic in edgeryders.eu that contains the configuration file. You will find the same topic at https://edgeryders.eu/t/12345. For example, the Research Network’s website lives at `Edgeryders, and is generated by the configuration file that lives at research.edgeryders.eu - Webkit XML.

Configuration files contain the instructions for the webkit to render your website. They live in posts on the edgeryders.eu platform. This means you can create and edit one just as you do with any post. But they look and behave a little differently from normal forum posts. In the rest of this manual, we speak therefore of configuration posts.

Webkit configuration posts are in a format called XML. XML files are made of “blocks”; each block contains some content and some styling decisions about that content. Look at this example:

You can see seven blocks: Config, Menu, Header, and four Content blocks, called "about", "methodology", "projects" and "partnership". You can have as many blocks as you want. Making a website with the webkit is about deciding which blocks you want; then preparing the content (text, pictures, videos… ) for each block; putting the blocks into your configuration post; and adding some finishing touches as needed.

Step 1: make the design decisions

Before you start making a website, it is a good idea to be clear about why you need one, and what will be in it. For example: “I need a simple registration website to the event I am organizing, with the program, practical info and a form for signing up”, or “I want to make a website showcasing our team, with a section for each person. Each section should contain a bio and a nice picture”.

It is good practice (but not necessary) to put down these decision into a wireframe. This is a simplified visual rendering of the look of your website. Pen and paper are usually more than enough, but on the Net you will also find more sophisticated tools.

Profilewireframe
Example wireframe. Source: https://www.flickr.com/people/doos/ / CC BY

Please be clear about your website, you will save yourself and others a lot of time and stress.

2 Likes

Step 2: prepare the content

As a general principle, let all your content live on the platform.

  • Do not use third party websites (except for things like YouTube videos, that were never meant to be uploaded onto the platform. This fragilizes your website, because now more websites have to keep working (and update their certificates etc.) for your own website to display correctly.

  • And do not write text directly in the configuration files. If you do this, you lose the automatic updating feature. Now you will have to make updates manually, tediously editing the XML file.

Choose and structure a home for your content

Make sure the materials for your website remain easy to find, for yourself and others. Currently, I (@alberto) am using this method:

  • Make a subcat Web content in the top-level cat that the website refers to. So, for example, Web Content within Research Network. Note that the category containing your content must be public, or the webkit will be unable to display it.
  • Within that subcat, start by creating an empty topic that will be the home of your configuration file. Give it an explanatory title, for example “Website of the collaborative ethnography webinar series – configuration file”.
  • Create a reply to that topic, and upload to it the logos and pictures that you need. Web designers call this “the assets” (example).
  • Within that same subcat, create topics and posts as needed for “static” text blocks (for example, the “about” section). Remember to use titles that help “future you” to find what you are looking for, when you or a colleague want to change the website a year from now. You can create a topic for each content block: in the example here these will be called “About”, “Methodology”, etc. Alternatively, you can create a single topic, using different reply posts for different static texts. The webkit can handle both methods.

Make or choose high-quality content

Websites are longer-lived than forum topics. Better get them right.

For static text:

  • Be brief and snappy. No rambling about. Short sentences. Avoid adverbs and passive forms as much as possible. I like to write these texts with the Hemingway Editor..
  • Be confident (but not arrogant). Edgeryders no longer needs to prove its worth, so you don’t need to put a whole list of publications to prove the point that we authored several publication. We just write “we authored several high-quality publications”, and people will believe it.

For static images and videos:

  • Make sure that logos files are available in an acceptable definition.
  • Choose nice pictures and videos.
  • Make sure you have the legal right to use the pictures; find out the license they have been published under, and respect to the letter its terms. Here is a how-to guide to attribution for content published under a Creative Commons.
  • Find out If the client or funder requires the inclusion of logos (this is the case for all EU-funded projects), and again behave accordingly.

Step 3: prepare the configuration post

General principle: you need to edit the configuration post in order to see all elements of it. This because Discourse hides some elements, including XML tags. So, don’t worry if the configuration post does not look right: edit it, then look at it in the edit window, and everything will be there. :+1:

Make a copy of the example configuration post

In theory, you can start writing a configuration file from a blank page, but no one does that. Instead,

  • Head over to the pre-prepared example configuration post (Resilient Livelihoods (XML)).
  • Click on “edit”. Once in the editor window, select the whole post and copy it.
  • Head back to the topic where you want to park your configuration post, edit it, select all content and paste-replace the example configuration post into it. Next, save.

At this point, you can already see the first step of the construction of your website. If the topic number of your configuration post is 12345, a website immediately appears if you type in your browser https://live.edgeryders.eu/12345. The content of the website, however, is all wrong: this is because it obeys the example configuration post. In order to make it look more like what you want, you will need, step by step, to change the configuration post.

Edit the config block

When you first open the configuration post, look at the top for the config block. It looks something like this:

<Config>
site:
  title: Research Network
  template: campaign
  theme: research
  lang: en-US
header:
  image: https://i.redd.it/x5zojh91awfz.jpg
  social: ['url', 'twitter', 'facebook', 'linkedin', 'email']
menu: 
  edgeryders: 
    icon: classic
    color: #fff
    url: https://edgeryders.eu
  other: 
    icon: https://edgeryders.eu/uploads/default/original/2X/b/be232a915d18e16a2b3e17c3d21dc47261e42689.png
    color: #fff
    url: https://edgeryders.eu
  links: 
    anchor: false
    fade: false
</Config>
  • Next to title:, type the title of your site.
  • Next to icon: (under other:), copy-paste the link of the icon you want (if any). This you already have uploaded onto Edgeryders during step 2, so it has an address starting in edgeryders.eu/uploads/.

All parameters

Parameter Accepted Values
template name of the Vue template to load (can be ignored most cases)
theme name of the CSS theme to load (see themes)
header see header parameters (below)

Header parameters

Parameter Description Example
image url of the image to set as background https://www.noc.ac.uk/files/images/story/Dan%20Grinwis%20image_.jpg
position position of the background image 0 -300px (meaning 300px vertically up, 0px horizontally)
social social media buttons to display in the header [‘url’, ‘twitter’, ‘facebook’, ‘linkedin’, ‘email’]

Edit the menu block

The menu block looks like this:

<Menu style="background: linear-gradient(180deg, rgba(75,137,145,1) 2%, rgba(240,240,240,0) 190%)">
## Research Network
</Menu>

There are two things here.

  • You definitely want to change the text Research Network. It displays to the left of the menu bar:

  • You probably also want to change the first line, after style=". style is a general parameter used to control the aesthetics of the block. In this case, we want the backgroundof the menu block to be a color gradientfrom one color (the green-grey of the Research Network) to another one (white). To make a gradient from, say the green of Collaboration to white, you would need to write

<Menu style="background: linear-gradient(180deg, rgba(83,159,68,1) 2%, rgba(240,240,240,0) 190%)">

Edit the header block

The header block looks something like this:

<Header style="background: url(https://edgeryders.eu/uploads/default/optimized/2X/5/5b6f4dd67b8bbca24e1f9b1106c159530b781071_2_1035x621.jpeg); background-position: 40vw -50px; background-attachment: fixed; background-repeat: no-repeat;">
<Text>
## Collective intelligence, at scale {style="color: rgba(75,137,145,1)"}
We are the Edgeryders Research Network. We do research with participatory, inclusive methods, to harness the power of collective intelligence.
</Text>
</Header>

Two things probably need changing.

  • The background image. If you want a background image below your header, upload one in your assets post (see above, then put its link in the parenthesis after background: url. It should start with https://edgeryders.eu/uploads/. Make sure you select one that does not interfere with the text.
  • The text. Just replace the sentences here with your own. Notice that we have made an exception to the rule of having all content in separate topic. This text (“Collective intelligence, at scale. We are […]”) is actually written in the configuration topic itself. This is because we have decided to have “Collective intelligence, at scale” in one color (green) and “We are […]” in another (black). The webkit can only handle one color in each block, so we have to include the other in a {style="color: ..."} instruction. If we put everything in a different topic, it would render incorrectly.

Choose, arrange and edit the content blocks

There are several types of content blocks. The example configuration post contains at least one block for each type of content you might want. So, the first thing you want to do is look back at your wireframe scheme, and reproduce it in the form of a sequence of blocks. For example, your site might host an “about” page; a blog; and a signup form.

  • The “about” page is just a static text blog.
  • The blog is done by calling all the topics with the blog Discourse tag.
  • The form is custom-made.

In this case:

  1. Locate the static page Content block in the example configuration post. Copy-paste it directly under the end of the Header block. Notice: the Header block ends after </Header>.
  2. Locate the Discourse tag Content block in the example configuration post. Copy-paste it directly under the end of the first Content block, i.e. after its </Content>
  3. Do the same thing with the form Content block.
  4. Delete all the other blocks, but do not delete the closing tag, </Webkit>.

At the end of this phase, you have a website with the right menu, the right header, the right number and type of blocks. All is left to do is to edit each block so that it does what you want it to do.

Here is how you handle the different types of block.

The static text content block

The static text is contained in a post somewhere. This block, then, is simply a call to that post.

<Content id="methodology">
## Semantic Social Networks
<Text topic="13663/1"></Text>
<Text>

The id= declaration within <Content [...]> tells the webkit that this block is called methodology. This word shows up in the menu automatically.

The title of the section (“Semantic Social Networks”) is written directly in the configuration post for better control over the font, but it could also be in the content topic.

The topic declaration within Text says “take the text from https://edgeryders.eu/t/13663/1”. This means that, if you want to change that text, you have no need to edit the configuration post anymore: just head to the normal Discourse post containing the text, in our example https://edgeryders.eu/t/13663/1. You can verify that this post contains the same text that shows up in the websites, under the header “Semantic Social Networks”.

Adding a video to the Content block

In any Content block, simply add your video (YouTube or Vimeo) URL inside a <Text> tag:

<Text> 
https://www.youtube.com/watch?v=D8XYL0gj-R8 
</Text>
<Text> 
https://vimeo.com/video/120778280
</Text>

Adding a picture to the Content block

There are several ways to insert pictures into a webkit site: (1) as an Image View that will be presented on its own next to or above any other view, (2) inside a text view using markdown syntax, (3) as a background image on any element using custom CSS.

1. Image View

The simplest way of adding an image would be to put a URL of the image in between an <Image> tag.

<Image>

https://edgeryders.eu/uploads/default/optimized/2X/5/5b6f4dd67b8bbca24e1f9b1106c159530b781071_2_1035x621.jpeg

</Image>

Placing an image followed by a <Text> view in the same <Content> block, will present the two side by side:

<Text>

My text on the left

</Text>

<Image>

https://edgeryders.eu/uploads/default/optimized/2X/5/5b6f4dd67b8bbca24e1f9b1106c159530b781071_2_1035x621.jpeg

</Image>

It is also possible to set an image url with the attribute url as such for a more condensed form:

<Image url="https://edgeryders.eu/uploads/image.jpeg" />

Important: If you opt for this form, remember to close the tag with a forward slash at the end of the tag.

You can apply dimensions to your image (such as width) by adding a style attribute to the tag:

<Image url="https://edgeryders.eu/uploads/image.jpg" style="width: 200px" />

This will set a width of 200px to the image.

2. Inline images

In many cases, we want to place images within a paragraph of text. To do this, use the Markdown image syntax or HTML <img> tag inside a <Text> view:

<Text>

First paragraph.

![my_first_image](https://edgeryders.eu/uploads/image.jpg) 

More text..

<img title="my second image" src="https://edgeryders.eu/uploads/image.jpg" />

</Text>

If I want to apply some styling to the image in markdown, I can do so using markdown attributes:

<Text>

![img](www.site.com/image.jpg){style="padding: 10px; border: 2px solid gray"}

</Text>

3. Background Images

Finally I can set a background image on any element using the style attribute. This is particularly useful for setting images as backgrounds on a <Header> or <Content> section:

<Header style="background: url(site.com/image.jpg); background-size: cover; background-position: center"></Header>

Displaying text and images side-by-side vs. one below the other.

Sometimes you will want to render different contents side-by-side, other times arranged in a column. To display them side-by-side, with the text in the left column and the video in the right column, use ---, like this:

<Content id = "forum">
<Text>
This is my text.
---
https://www.youtube.com/watch?v=1ag-GxG8Uiw
</Text>
</Content>

To display them in a single column, with the text above the video, close and re-open the <Text> tag, like this:

<Content id = "forum">
<Text>
This is my text.
</Text>
<Text>
https://www.youtube.com/watch?v=1ag-GxG8Uiw
</Text>
</Content>

Displaying data from Discourse

We’ve seen how to display text from a topic on a site. There are situations, where we want to present multiple topics or posts from Discourse on a site. To do this, we can use views. <Text> is one view, <Image> is another, but we also have <Table>, <Grid>, <Slider>, <Cards> and more.

These components can not only display topics from a tag or category, but any arbitrary set of data provided it is correctly formatted.

Table

The table view presents topics from a tag or category in a table format (and as a list on mobile)

<Table category="workspaces" display="date, author" search="true"  />

The example above will fetch all topics from the workspaces category.

The display attribute determines to show the date or author of a selected item.

Attribute Accepted Values
category discourse category name (e.g. ‘campfire’ or ‘workspaces’)
tag discourse tag
data discourse topic id containing a json array
display author, date

Grid

The grid view presents topics from a tag or category in a grid format (and as a list on mobile)

<Grid tag="covid19-event"  />

The example above will fetch all topics tagged covid19-event.

The display attribute determines whether to show the date or author of a grid item.

Attribute Accepted Values
tag discourse tag
display author, date

Slider

The slider view presents topics from a tag or category in a slideshow format.

<Slider tag="edgeryders-summit-conversations"  />

The example above will fetch all topics tagged edgeryders-summit-conversations.

Attribute Accepted Values
tag discourse tag

Cards

The cards view presents a row of cards from a tag or category or JSON data inside a topic.

<Cards template="topics" tag="webcontent-edgeryders-summit-2020-topics"  />

The example above will fetch all topics tagged webcontent-edgeryders-summit-2020-topics.

The template option topics, will display the cards as topics.

Attribute Accepted Values
tag discourse tag
template topics

Blog

The blog view presents topics from a tag or category in blog form: title, author, date, and a preview of the full text.

<Blog tag="sf-econ-blog" title="Blog" template="standard" items="6" columns="2" display="author, date"  />`

The example above fetches the 6 most recent topics tagged sf-econ-blog, and arranges them in 2 columns.

Attribute Accepted Values
tag discourse tag
template topics
title string
items integer
columns integer

Form

The cards view presents a form with fields for the user to fill in.

To set up the form a table on AirTable must be created with identical column names matching the ID of each field.

<Form airtable='airtable_base_id'>

### Form Title

### Your City

<Field id="city" type="text" placeholder="City" required="true" />

### Your Country

<Field id="country" type="text" placeholder="Country" required="true" />

### Your Personal Site / LinkedIn profile

<Field id="site" type="text" placeholder="Your Website" required="true" />

### Your Bio

Please provide 2-4 sentences about your life experience as it relates to your domain, or anything else you would like to add. (Optional)

<Field id="bio" type="textarea" placeholder="Tell us a bit about yourself" />

</Form>

The example above will display a form and post it to AirTable database with a matching base ID.

Attribute Accepted Values
airtable airtable base ID

Step 4: Finishing touches

You now have a complete website, visible online. It has both static and dynamic content in all its right places. Despite this, there are still some steps that you can take to make it easier to access and more professional-looking.

Themes

Many aesthetical features of your websites are controlled by an external file called a theme. It is part of the webkit software, and lives in the same server. A theme decides, for example, what kind of font the website is going to use. The Config block in your configuration post contains a line that tells the webkit which theme to use for your website:

<Config>
site:
  title: Research Network
  template: campaign
  theme: research
  [...]
</Config>

You can try editing that line in the configuration post to see which them fits best your website. Currently available themes are:

  1. research: a minimalistic theme developed for the website of the Research Network.
  2. edgeryders: the standard Edgeryders theme see resilience livelihoods website.

If none of the themes fits your needs, talk to the tech team in Edgeryders, they might be able to make one for you depending on their workload. If you feel adventurous, you can also try to develop your own theme: again, talk to the tech team if you wish to do so.

Polish

The webkit is made to be used by people who are not web development professionals. However, for particularly ambitious projects, you might need expert help. An example is the 2020 policy summit’s website (@hugi please insert link here?). Check with your team leader to make the necessary procurement decisions.

That said, you can add some polish yourself. For example

Add a background to a Content block

You can do this by adding a style instruction to your block:

<Content id="long-termism" style="background: #efefef;">

The color #efefef corresponds to a light grey expressed in hex format. This is a website where you can pick colors in hex. You can, however, also express colors in other formats, such as RGB.

Whenever you are using style, you are giving the webkit instructions in a format called CSS, and must observe the proper syntax. Be sure to copy all the ;, : and ", or the website will not work. More on this here.

You can also add an image as a background:

<Content id="long-termism" style="background: url('https://edgeryders.eu/uploads/your-image-file.jpeg') no-repeat; background-size: cover;">

More on this here.

Third-level domain

Your website lives at https://live.edgeryders.eu/12345. That’s fine, but we mostly prefer to add a third-level domain to make the URL easier to remember and more snappy looking: something like https://your-project.edgeryders.eu. Ask @matthias to make one for you, and point it to your website.

All done! Congratulations! :partying_face:

1 Like

Is this manual obsolete, @owen?

Not obsolete, but parts of it are outdated now - the syntax has been simplified quite a bit.

The canonical manual should be this one - 📗 Webkit Manual

There are parts that remain in need of an update here too, on my todo list.

1 Like