Managing Projects

Creating A New Project

After you logged in to your application you'll be redirected to your dashboard. In this page you can see all your projects.

When creating a new project you can choose one of the options. Blank projects don't have any collections or content. Templates are prebuild projects with collections to get you started.

After you created a new project click the project to see details. This is the main page for your project.

You can create collections and content. At the top right side you can see the settings icon.

Project Settings

Project

In this page you can change the name and description of the project. And you can delete the project permanently.

Localization

You can manage content locales for your project. Project must have at least one locale. In order to change the default locale you need to add a new one and set it as the default locale. Then you can delete the old locale.

Users & Roles

In this section you can manage user access to your your project. There are two roles you can use. Admin roles can manage project collections and content. Editors can only manage content. Super admin accounts have the admin role for all your projects.

When you're assigning a user to a project you can create a new user.

API Access

In this page you can update your API settings. When you created a new project a random ID will be created.

This section allows you to issue API tokens that can be used to authenticate API requests to your application. When making requests using API tokens, the token should be included in the Authorization header as a Bearer token. You can set permissions for access tokens.

These tokens typically have a very long expiration time (years), but can be manually revoked at anytime.

Enabling Public API Access

You can enable public access for your project's endpoints. Public access is only available for the get requests(read). You're still going to need an access token for the create, update and delete operations. You can enable public access for projects separately.

Webhooks

Webhooks provide a method to notify other applications that an event occurred.

Using webhooks, you can send information about events to third-party applications when new content is created or updated.

The way a webhook works is by delivering information to a receiving application through POST requests.

There are 7 different events you can use:

  • Content Created
  • Content Updated
  • Content Trashed
  • Content Deleted
  • Content Published
  • Content Unpublished
  • Content Restored
  • Form Submitted

Creating Webhooks

You can create multiple webhooks for any project.

  1. Navigate to Webhooks in the sidebar.
  2. Press "Create a New Webhook" in the upper right corner of the window.
  3. Fill out the configuration for your webhook.
  4. Press "Create Webhook"

Configuration

  • Name of your webhook (required)
  • Description for you webhook (optional)
  • URL to receive your webhook (required)
  • Secret to sign your requests. Details below. (optional)
  • Collections. You can choose multiple collections to watch for an event. (required)
  • Events. You can choose multiple events. (required)
  • Source for your webhook. You can either choose User or API. (required)
  • Include Payload. Choose to include or not the content data in your request.
  • Active. You can enable or disable your webhooks. This may be useful when you don't want to delete the webhook.

Securing Webhooks

When setting up, it's common to generate, store, and share a secret between your app and the app that wants to receive webhooks. You can generate a secure secret key by pressing the "Generate" button or you can manually create your secret key.

Elmapi will create a signature for your request using HMAC method.

Using HMAC signature to validate webhooks

When you create a webhook with a secret key to sign your request, Elmapi sends the request with a "signature" header. You can validate this signature to ensure the request is coming from your application.

To verify the signature the steps required are:

  • Get the raw body of the request;
  • Extract the signature header value;
  • Calculate the HMAC of the raw body using the SHA-256 hash function and the secret;
  • Compare the calculated HMAC with the one sent in the signature header

Here is an example code for PHP:

<?php
define('SECRET_KEY', 'webhook_secret_key');

function verify_webhook($data, $hmac_signature){
    # Calculate HMAC
    $calculated_hmac = hash_hmac('sha256', $data, SECRET_KEY);
    return hash_equals($hmac_signature, $calculated_hmac);
}
# Extract the signature header
$headers = getallheaders();
$hmac_signature = $headers['Signature'];

# Get the raw body
$data = file_get_contents('php://input');

# Compare HMACs
$verified = verify_webhook($data, $hmac_signature);

error_log('Webhook verified: '.var_export($verified, true)); 
if ($verified) {
    # Do something with the webhook
    http_response_code(200);
} else {
    http_response_code(401);
}

Using Queues

Elmapi uses Laravel's queue system to process webhooks. By default when an event happens, the webhook will be triggered immediately. That's because the default configuration for queue connection has been set to "sync". You can change this setting in your .env file. Avaible queue connections are : sync, database, beanstalkd, sqs, redis.

QUEUE_CONNECTION=sync

You can find more information about queues in the Laravel documentation.

Collections

Collections are where you can create your schema for your content. Inside the collections module you can create new collections and add fields. All changes to your collections are immediately avaible in content managing view.

Creating Collections

To create a new collection simply use the Add New button. Name your collection and the slug will be created. You can change the slug if you want to.

You can create as many collections as you want.

Adding Fields

You can add fields to your collection. Learn more about field types in the next section.

Fields

Elmapi allows you to use 15 different field types to create your schema.

Every field type has some default and additional settings according to its type.

Label: Display name of the field

Field name: Database name of the field

Description (optinal): Displays a hint for the field when creating or editing content

Placeholder (optional): Placeholder text for input fields.

VALIDATIONS

When creating content, validation options can help users to keep the content data consistent and clean.

Required: Prevents saving content if this field is empty

Unique: Prevents saving content if there is a record with the same content.

Character count: Specifies a minimum and/or maximum allowed number of characters

You can write a custom error message for validations.

OTHER OPTIONS

Repeatable Field: Allows multiple entries for the field. It's available for text, longtext, email, number, color, date and time field types.

Hide in content list: Field will be invisible in the content list table

Hidden in API: Field will be invisible in API.

Field Types

Text

Single line text. Can be used for headings, post titles etc.

Long Text

Multi line text. Can be used for descriptions, summary or excerpt of a post.

Rich Text

Rich text editor with formatting. HTML editor allows user to format their content.

Slug

Like Urls and permalinks. Slug fields can be attached to another field. Slug will be generated from selected field. Only text fields can be selected.

E-mail

Email field with validation. E-mail field can be used for user information.

Password

Password field with encryption. Passwords will be stored in the database with bcrypt encryption.

Number

Integer, decimal, float numbers. Can be used for prices, quantites etc.

Color

Color picker.

Enumeration

List of values. You can specify the list of values like cities, countries, gender etc.

Boolean

True or false.

Date

Calendar date picker

Time

Time picker

Media

Files, images, videos. Select files from the advanced media library. You can choose single or multiple file options.

Relation

Collection relations. You can create relation to other collections. You can choose One to One or One to Many relation types.

JSON

Data in JSON format.

Content

Elmapi provides an advanced interface for content management. You can create, edit, publish content with easy to use content module.

Embeddable Forms

With the Elmapi's Forms module you can create embeddable forms from your collections.

After creating a new form for the selected collection, in the detail view you can add fields to your form. You can change the title and the description of the fields. You can give your form a name and a description.

After updating your form according to your needs you can preview the form and get the embed code. Then you can add your form to your html file using the iframe method.

Submitted forms will appear in the content table for that collection. When a form is submitted a content item will be created as a draft. You can see the item on the content list with a different color. If the draft label is blue, that means that item has been created via form submission. You can edit form items as any other content item.

Media Library

Managing project files is very easy with Elmapi's advanced Media Library. Upload your files and add them to your content.

You can set the maximum file size limit in your .env file

Amazon AWS S3 Upload

You can use AWS S3 to upload and retrieve media files. In order to configure Elmapi to use AWS S3 follow the instructions below.

Step 1 - Create a New S3 Bucket

If you want to use an existing bucket you can skip this part.

  1. Go to your AWS console
  2. Search for S3 and go to your S3 dashboard
  3. Go to Buckets
  4. Click on the Create Bucket button
  5. Choose your bucket name
  6. Choose bucket's region
  7. Select ACLs enabled
  8. Unselect Block all public access
  9. Check the option for acknowledging current settings
  10. Click on Create Bucket
Create a New S3 Bucket

Step 2 - Create a User

If you want to use an existing user you can skip this part.

  1. Go to your AWS console
  2. Search for IAM and go to your IAM dashboard
  3. Go to Users
  4. Click on the Add Users button
  5. Choose your user name
  6. Select Access key - Programmatic access
  7. Click on Next: Permissions
  8. Select Attach existing policies directly
  9. Search for and select AmazonS3FullAccess
  10. Click on Next: Tags
  11. Skip this step and click on Next: Review
  12. Click on Create User
  13. Copy your Access key ID and Secret access key
Create a User

Step 3 - Configure Elmapi

  1. Open your .env file
  2. Change the following lines according to your S3 credentials:
    • AWS_ACCESS_KEY_ID=your-access-key-id
    • AWS_SECRET_ACCESS_KEY=your-secret-access-key
    • AWS_DEFAULT_REGION=your-region
    • AWS_BUCKET=your-bucket-name

Step 4 - Check the configuration

  1. Go to one of your Elmapi projects.
  2. Go to project settings. You will see the Default Upload Disk option
  3. Select AWS S3 and click on Update Project. You can change the default disk later if you want. When you change this option you can continue to access older files which stored in other option. You can have files in both disk at the same time.
  4. Go to project's Media Library.
  5. Click on Upload Files and upload your files as usual.

Access Denied Error

Access Denied Error

If you get an Access Denied error when you try to upload or access files to your S3 bucket, you need to grant the following permissions to your IAM user:

  • PutObject
  • GetObject
  • ListBucket

You can find more information about this error in the AWS documentation.

You can also add a Policy to your bucket:

  1. Go to your bucket.
  2. Click on Permissions.
  3. Scroll to Bucket Policy section and Click on Edit.
  4. Add the following policy:
    {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Sid": "PublicRead",
                "Effect": "Allow",
                "Principal": "*",
                "Action": [
                    "s3:GetObject",
                    "s3:GetObjectVersion"
                ],
                "Resource": "arn:aws:s3:::your-bucket-name/*"
            }
        ]
    }