A note on the philosophy of the webkit and its documentation

I would add this - there should be a clear distinction between the Open Source project and the Edgeryders version. The two are mostly the same, but there are some important differences:

  1. The Edgeryders API behaves a little differently from a vanilla installation of Discourse. James built useful endpoints for fetching content - for example, for fetching topics. These endpoints should not (and are not) used in the Open Source project, as they will not work with any other Discourse installation.

  2. The Edgeryders Webkit hosted at live.edgeryders.eu has a ‘multi-site’ configuration. This means one installation is the ‘backend’ for many sites - and these sites are routed through different domains or aliases (in our case defined here).

After the XML syntax, this is the second significant change made in the last few weeks.

The benefit of using a single installation means:

  • Updates are deployed across all sites instantly
  • We reduce overhead by only having one repository to maintain (versus many dozens, one for each site),
  • We can easily use something like Netlify Analytics to get visitor stats from all the sites at once.
  1. The form component, which we are still trying to integrate with the platform, requires significant customisation on the Discourse end (this was done by Matthias, James and Hugi) - and so is not standard with the open source project for now.

The final point, being this:

I agree and that needs to be updated… I think the XML syntax serves project managers (and myself) better than the JSON syntax, it reads like HTML and is a lot closer to writing a post on Discourse, with the use of some additional tags.

The end result is still JSON, but that part is now behind the scenes and does not require a project manager to learn. It’s far easier to write this with fewer errors:

<Content>
  <Text style="color: red">
    Hello
  </Text>
</Content>

Than this:

"blocks": {
 "content": {
   "text": "hello",
   "style": {
     "color": "red"
    }
  }
}

JSON is very picky with trailing commas, missing quotation marks or closing curly braces (and the more of them you have, the higher the risk of error). It’s an error prone format for what we are trying to do, which is easily deploy sites with minimal trouble.

So, this needs to be properly documented - probably here and will do it next.


Agree that themes are also very important, for the same reason as mentioned before: using a small set of CSS themes makes updating and improving the look of dozens sites a lot easier than updating one site at a time. At the moment we have two basic themes:


Overall I’m happy with the direction the Webkit is taking and more comfortable with people using it in this form than the previous iteration…

In terms of project development, the main hurdles are (in reverse order of difficulty & time needed):

  • Getting the form component to work with the platform (this has been very challenging)
  • Parsing the XML tags for all the Views (slides, grids, lists, events…)
  • A blog view for displaying topics
  • Documentation:
    • How to use the XML tags
    • How to use a theme
    • How to configure a form
    • How to style individual elements
    • How to set up an alias and domain

I think I first need to have a session with Owen to better understand what direction the webkit is taking since got to the last milestone we set out in the original design plan. It all got into a bit of a flux with a lot of changes happening very quickly in the last month or so. I haven’t really been involved in project management for those changes, and we would need to set out a goal for what we want to achieve in the next 6 months.

I really don’t think we should be actively maintaining a vanilla version of the webkit that does not use custom webkit endpoints. I would not support us doing double work for that. After all, our webkit endpoint plugin is also open source and can be readily installed to any Discourse instance that needs it.

They will work just fine if the Discourse installation has this plugin installed:

What is the rationale for having an “open source” version when we’ve made the plugin the webkit depends on open source?

I think that our highest priority now is getting us to a completely stable 1.0 version of the webkit, which is 100% documented and which will not change until a future major release. This 1.0 version needs to have all the old dead-end code stripped away too for ease of access for future development.

If the plugin is available and open source then I see your point. It does mean some parts of the webkit will not work out of the box unless that plugin is installed however.

I think that is fine. We are, after all, mostly building this for ourselves. If people outside of ER like it and want it to work without our plugin, they can carry the maintenance for that themselves.

1 Like

Ok - that’s probably the way to go then. I’m free tomorrow morning if you have time for a call, otherwise let me know when would suit you.

1 Like

How about Tuesday afternoon at 15:00?

works! Speak to you then


17:00 would work, or later? Otherwise I am free most of Wednesday, you just can just ping on riot when you have time.

Hmm, no. Better on Thursday then, perhaps at 13?

1 Like

Yep, works fine

Hello @hugi and @owen, I would like to ask to put two items on the agenda of your meeting today.

  1. Documentation, as per this topic.
  2. Can I get an update on the webkit as a funnel for registering to the platform? We are rolling out comms for the Sf-Econ first event about now, so we need to quickly decide whether to have signup via our own infrastructure or through a third party. What we need to know is when we can use a webkit website to sign up to an ER event. In fact, I thought this was working already (there are forms in Owen’s example JSON config file), but Nadia claims it is not.

Today I am starting a manual about making a website with the webkite for dummies like me.

1 Like

Will discuss in the call, but as a preliminary answer:

  • There is a form component to build forms. The ongoing issue is getting this form data onto the platform. It is a work in progress, therefore I would not recommend waiting for it to launch your first event.

  • What the form component can do is post the result of the form to Airtable, or any third party service with a documented API. This requires some configuration, but it works.

Thanks. Meanwhile, started the manual:

Thanks for getting started on this - I will add to it as we go along.

In our call today we set the following goals:

  • Remaining components to be integrated and working with XML format by next week (July 2nd). The syntax of these components will follow closely how the < Text > and < Form > components work. Date: July 2nd
  • Documentation finished and working in tandem with webkit - Date: July 6th.
  • Form working, depending on outcome of fix - Date: July 6th

On the last point - for @alberto - I would not wait or delay an event page in the expectation of this form working. The reason is we’ve ran into a series of problems getting it to work thus far - if this last problem is easily fixed I will post a message here saying so - if not, it is best to adopt an alternative solution for your event.

There are several third party form solutions out there, but if you want the existing form integrated with a database or something like Airtable I can set that up - let me know, which way you go.

Finally, the footer for @nadia will be done today (in the next hour).

I think that covers everything - @hugi if there is anything else I missed here feel free to include it below.

2 Likes

These problems, for the record, have something to do with the plugin @gdpelican built no longer working as expected with Discourse. @matthias is investigating.

1 Like

@owen and @hugi, thanks for this.

I am now done with iteration 1 of A step-by-step guide to making an Edgeryders website with the webkit. There is still some information missing: I have @mentioned you to mark the points where I need you to fill it in. Once everything is in place, we can upgrade it to manual, with @matthias’s permission.

When making a website with the webkit, the main tool at the layman’s disposal is the example configuration file, or rather configuration post. I already recommended spending some care making one with example code for all the types of content supported. Now I want to add another recommendation: be generous with inline comments:

<!-- XML comment here -->

Problem with that, of course, is that an XML tag is not rendered by Discourse. We can live with it, and I already added it to the guide:

That said, if anyone is aware of a better workflow, incorporate it in the guide.

1 Like

@nadia please take note… AirTable it is.

@owen seen this? https://github.com/edgeryders/webkit_components/issues/55

yeah we use airtable already: https://edgeryders-start.netlify.app

An update on the documentation and syntax -

@alberto the components are now ported over to the new syntax, an example of a site built using the new syntax can be found here: https://webkitsandbox.netlify.app

This means now:

  • To display a grid of event topics I use the syntax:
<Grid template="events" tag="event_tag" />
  • To display cards I use the syntax:
<Cards tag="topic_tag" />
  • To display a table of topics I use the syntax:
<Table tag="topic_tag" />
  • To display a set of topics in a blog view:
<Blog tag="topic_tag" />

or

<Blog category="category_id" />

There will be situations where we will want to display a custom data set, rather than topics or posts.

For example on the resilience site - we are displaying a row of profile cards. This data is stored not as posts but in a JSON format here: https://edgeryders.eu/raw/14036.json

To display an arbitrary data set, you would do this:

<Cards data="14036" />

This means “get the JSON data from topic 14036 and display it in my Cards view”.


I will add all this to the documentation tomorrow, and update the sandbox to the latest version of the webkit so you can try it out.

1 Like

The sandbox (live.edgeryders.eu) is now updated.

For some examples -

  1. the Sci-Fi economics site has been updated to include the < blog > component
    Site: https://live.edgeryders.eu/13896/
    Config: SF-ECON Lab webkit XML - Raw

  2. the resilient livelihoods site has been converted to the XML syntax (slider, grid, cards):
    Site: https://live.edgeryders.eu/resilience/
    Config: Resilient Livelihoods XML - Raw

Also the Vimeo bug has been fixed.

More documentation tomorrow.

cc / @alberto @hugi

1 Like

Thanks @owen the Resilient Livelihoods site looks great!

I have reported a legitimate bug and a request for improvement – are you still using that repo? Also I have several questions and glitches, but I will wait for the documentation because it is probably just me not being familiar with the various parameters.