Juncture for Developers

For Developers

Juncture is designed for easy extension and customization.

Simple changes can often be performed directly from the Github website using the provided editing tools. When performing more extensive changes a development environment will generally be used. A couple of options for development environments include:

Setting up a local development environment on your personal computer
Using a cloud-based environment such as Gitpod

Development Environments

Setting up a local development environment

Clone a Github repository

Setting up a local development environment requires cloning a repository on your local computer. These instructions were developed for macOS but should work similarly for Windows.

To clone a Github repository use the following command from a console (terminal) window.

git clone https://github.com/<GH-USERNAME>/<GH-REPOSITORY>.git

For Juncture this would be: git clone https://github.com/JSTOR-Labs/juncture.git

Run a local development server

Code changes can be viewed in your browser using a local web server capable of serving static files. For Juncture the Node serve server is known to work and is a good option. Running the serve server can be performed using npx using a single command.

npx serve -l 8080 -n

Using Gitpod

Gitpod is a web service that provides pre-built development environments that are used from a browser. A free "open source" option is provided which may suffice for some users.

The Gitpod development environment includes the Visual Studio Code(VSC) editor and a Linux command line interface.

The Juncture Github project is includes a simple Gitpod configuration file providing quick activation of a development environment. To launch a Gitpod environment for a Github repository simple prepend gitpod.io# to the Github repository URL. For example, for Juncture the Github repository URL is https://github.com/JSTOR-Labs/juncture. To launch a Gitpod development environment the URL would be https://gitpod.io#https://github.com/JSTOR-Labs/juncture

Browser extensions are also available which activate a Gitpod environment with a single click.

Chrome (also works for Edge, Brave and other Chromium-based browsers)
Firefox

After Juncture repository (or forked a copy) is launched in Gitpod two browser windows are created, one with the VSC editor and another with the rendered site. Changes performed in the VSC editor can be seen in the web site browser window after refreshing.

Creating New Components

Juncture includes a rich set of components that may satisfy most needs "out of the box". In cases where custom features are needed new components may be added to provide the desired functionality. Juncture components are implemented as Vue.js Single File Components which include component markup (HTML), code (javascript), and styling (CSS) in a single self-contained file.

Juncture component files (and Vue.js components, more generally) are named with the component name (using camel case) and the .vue file extension, for example MyNewComponent.vue.

The default components included with Juncture are located in the /components folder at the root of the Juncture repository. New components may be added to the /components folder in a forked repository if the component name does not conflict with an existing Juncture component. However, since new components may be added to the Juncture core creating the potential for a future name collision this approach is not recommended. Rather, it is recommended that new components be added in a new /custom/components folder in a forked repository.

Components found in the /custom/components folder take precedence over Juncture default components allowing custom versions of an existing default component to be used. As an example, if a customized version of the Juncture Header component was needed a Header.vue component found in the /custom/components would override the the default Header component.

Component communication with the Juncture framework is accomplish using Vue.js props and events.

Component props

Data is passed to Juncture components using Vue.js component props. The props values available to components include:

html - something about html...
path - something about path...
params - something about params...
entities - something about entities...

Component events

Components are able to emit events to be handled by the Juncture core. These events include:

event1 - something about event1...

An example component

<template>
  <div v-html="viewerLabel" :style="containerStyle">
  </div>
</template>

<script>

  module.exports = {
    props: {
      items: { type: Array, default: () => ([]) },
      viewerIsActive: Boolean
    },
    data: () => ({
      viewerLabel: 'Custom Component',
      viewerIcon: 'fas fa-code',
      dependencies: []
    }),
    computed: {
      containerStyle() { return { height: this.viewerIsActive ? '100%' : '0' } }
    },
    mounted() { this.loadDependencies(this.dependencies, 0, this.init) },
    methods: {
      init() {
        console.log(`${this.$options.name}.mounted`)
      }
    }
  }

</script>

<style>
</style>