Importing

You can import modules from any Git repository like GitHub, GitLab, or Bitbucket. These are preconfigured Studios bundles which contain: modules, types, pages, components, and translations.

Modules can be used to quickly expand your application functionality.

A module list and usage instructions can be found at: Studios Universe - Modules.

Import a Module

The simple-blog has types, pages, and components for posts, comments, and tags. This module shows many of the configurable options within the designs.

Import command
hof import "#simple-blog"

Pulls the latest studios-modules and imports designs from the simple-blog folder.

The full import command is available in Studios Universe - Modules documentation.

Enable in the App

Update your design/modules.yaml file to include the following line:

app:
  name: ...

  modules:
    - account
    - blog
Create a Menu Entry

You can create menu links for the modules in navbar, by editing the file:

design/layout.yaml

add the following:

app:
  name: ...

  layout:
    navbar:
      ...
      leftItems:
        ...

        # the new content
        - name: posts
          route: "/posts"
          roles:
            - user
            - admin

Module Overview

The following is the directory layout of your new blog module.

blog/
│
├── module.yaml
├── post.yaml
├── comment.yaml
├── tag.yaml
│
├── pages
│   ├── all-posts.yaml
│   ├── edit-post.yaml
│   ├── new-post.yaml
│   ├── user-posts.yaml
│   ├── view-post.yaml
│   └── post
│       ├── edit
│       │   ├── content.html
│       │   └── style.scss
│       ├── list
│       │   ├── content.html
│       │   └── style.scss
│       ├── new
│       │   ├── content.html
│       │   └── style.scss
│       ├── user
│       │   ├── content.html
│       │   └── style.scss
│       └── view
│           ├── content.html
│           └── style.scss
│
├── components
│   └── CommentOwnerEditable.jsx
│
├── locales
│   ├── en.json
│   └── es.json
│
└── seeds
    └── posts.json

Extending and Overriding

You can extend and override an imported module by writing types, pages, and component files in your application’s design folder.

Extend the Design

You can extend and override module designs and files imported to the design-vendor directory. This means you can add just the new designs and files to express your desired changes. Create the same folder / file structure, as well as the same, minimal object structure for designs.

Start the mirrored directories
mkdir -p design/modules/blog/locales
Create the file: design/modules/blog/post-mods.yaml
type:
  name: post

  # extend by adding field 'blurb'
  fields:
  - name: blurb
    type: string
    length: 256
Copy the file: design/modules/blog/locales/en.js
cp design-vendor/modules/blog/locales/en.js design/modules/blog/locales/en.js

and add

"blurb": "Blurb",

to the json

{

  "post": {
    "fields": {

      "blurb": "Blurb",

    }
  }
    
}

Overriding a Page

Create the mirrored directory
mkdir -p design/modules/blog/pages/list
Copy the file: design/modules/blog/pages/post/list/content.html
cp design-vendor/modules/blog/pages/post/list/content.html design/modules/blog/pages/post/list/content.html

and change (around line 32)

<p className="mb-1">{ post.content.substring(0,64) }</p>

to

<p className="mb-1">{ post.blurb }</p>

Updating the Application

The next section is all about this. It assumes we are deploying for the first time, so if you already have deployed your application, you can skip some steps.

Note that because we have changed the shape of the data, we will need to both:

(TODO dev note, add a flag to push, so one can migrate as well)

Custom and Private Repositories

The import command has a longer format enabling the use any git based repository or the local filesystem. See the Studios Universe - Modules documentation for more information.

Private repositories are supported for GitHub using the GITHUB_TOKEN environment variable.