Homepage

Creating a Module

Last edit: Oct 26, 2022

This guide will help you learn how to create a module by walking you through the steps of creating a simple module.

Requirements

This is an advanced tutorial. To follow it, you should be familiar with basic platformOS concepts, the topics in the Get Started section, and modules.

Steps

Creating a module is a three-step process:

Step 1: Create directories

Create two directories inside the modules directory called admincms, then create the public and private folders inside it. Place the graphql directory inside private, and the views/pages directories inside public.

This is the structural overview of the module you'll create:

admincms
├── private
│   └── graphql
│       ├── get_records.graphql
│       └── get_pages.graphql
└── public
    └── views
        └── pages
            └── admin.liquid

Step 2: Create GraphQL queries

Create a GraphQL query that pulls a list of Records.

modules/admincms/private/graphql/get_records.graphql
query get_records {
  records(
    per_page: 10
    sort: [{ name: "id", order: "desc" }]
  ) {
    results {
      table
      properties
    }
  }
}

Create another GraphQL query that pulls a list of pages

modules/admincms/private/graphql/get_pages.graphql
query get_pages {
    admin_pages(per_page: 10) {
    results {
      format
      slug
    }
  }
}

Step 3: Create page

modules/admincms/public/views/pages/admin.liquid

---
slug: admincms
---

<h2> Module example - Admin </h2>

<div class="row">
  <div class="col-xs-12 col-lg-6">
    <h3> Records </h3>
    {%- graphql c = "modules/admincms/get_records" -%}
    <table class="table table-compact">
      <thead>
        <tr>
          <th> Name </th>
          <th> Properties </th>
        </tr>
      </thead>
      <tbody>
        {% for record in c.records.results %}
          <tr>
            <td> {{ record.human_name }} </td>
            <td> {{ record.properties }} </td>
          </tr>
        {% endfor %}
      </tbody>
    </table>
  </div>

  <div class="col-xs-12 col-lg-6">
    <h3> Pages </h3>
    {%- graphql c = "modules/admincms/get_pages" -%}
    <table class="table table-compact">
      <thead>
        <tr>
          <th> Slug </th>
          <th> Format </th>
        </tr>
      </thead>
      <tbody>
        {% for page in c.admin_pages.results %}
          <tr>
            <td> {{ page.slug }} </td>
            <td> {{ page.format }} </td>
          </tr>
        {% endfor %}
      </tbody>
    </table>
  </div>
</div>

You are using the queries as usual but the name is prefixed with the module name.


{%- graphql c = "modules/admincms/get_pages" -%}

The only difference between this code and code of a regular Instance is that this module code is split
into public and private folders, and if you'd pull the code when it's installed on an Instance,
you would get a structure like this:

.
├── app
│   └── views
|   └── graphql
│       ...
└── modules
    └── admin
        └── public
            └── views
                └── pages
                    └── admin.html.liquid

Live example and source code

To explore it in action go to live example.
Source files are also publicly accessible.

Next steps

Congratulations! You have created a module. Now you can learn about sharing your module on the platformOS Module Marketplace.

Contribute to this page More info

Contribute here

Questions?

We are always happy to help with any questions you may have.

contact us