Creating a Module

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.

• platformOS Workflow
• Get Started
• 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: [{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

In this step, we will create a page that uses the previously defined GraphQL queries to display records and pages from the module:

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 the code of a regular Instance is that the module code is split into public and private folders. If you pulled the code when it’s installed on an Instance, you would get a structure like this:

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

Live example and source code

To see it in action, visit the live example.
Source files are also publicly accessible.

Next steps

Congratulations! You have created a module. Now you can learn how to share your module on the platformOS Module Marketplace.

• Sharing a Module