Creating a Module

Last edit:  Dec 22, 2018

Contributors:  diana-lakatos ignacy pavelloz

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 graph_queries directory inside private, and the views/pages directories inside public.

See the structural overview of the module you'll create here for reference:

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

Step 2: Create GraphQL queries

Create a GraphQL query that pulls a list of Customizations.

admincms/private/graph_queries/get_customizations.graphql

query get_customizations {
  customizations(
    per_page: 10
    sort: [{ name: "id", order: "desc" }]
  ) {
    results {
      human_name
      properties
    }
  }
}

Create another GraphQL query that pulls a list of pages

admincms/private/graph_queries/get_pages.graphql

query get_pages {
    admin_pages(per_page: 10) {
    results {
      format
      slug
    }
  }
}

Step 3: Create page

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> Customizations </h3>
    {%- query_graph "modules/admincms/get_customizations", result_name: "c" -%}
    <table class="table table-compact">
      <thead>
        <tr>
          <th> Name </th>
          <th> Properties </th>
        </tr>
      </thead>
      <tbody>
        {% for customization in c.customizations.results %}
          <tr>
            <td> {{ customization.human_name }} </td>
            <td> {{ customization.properties }} </td>
          </tr>
        {% endfor %}
      </tbody>
    </table>
  </div>

  <div class="col-xs-12 col-lg-6">
    <h3> Pages </h3>
    {%- query_graph "modules/admincms/get_pages", result_name: "c" -%}
    <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>

As you can see you are using the queries like usual but the name is prefixed with the module name


{%- query_graph "modules/admincms/get_pages", result_name: "c" -%}

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:

.
├── marketplace_builder
│   └── views
|   └── graph_queries
│       ...
└── modules
    └── admin
        └── public
            └── views
                └── pages
                    └── admin.html.liquid

Live example and source code

To see 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.

Questions?

We are always happy to help with any questions you may have. Check out our Help page, or contact us.