Creating a New Element

Creating a new Element in Quix is a pretty straightforward process. You will need a text editor(Notepad, Sublime Text), as you will be creating three files for the Element.

Lets create a simple Call To Action element. This Element consist of three main fields, Title, Description and Button and few style fields. Elements can be as simple or complex as you need them to be.

File Structure

.
├── call_to_action
|   ├── config.yml
|   ├── view.php
|   ├── style.php
|   ├── element.svg/png

Creating the Config file

While creating your Element, it may be easier to start with the config.yml file as this store configuration data. The view.php file pull the information and output them and style.php are being used in style the Element. The element.svg or element.png represent the Element on Element list.

Navigate to your template folder and create a folder name quix and then create another folder inside name elements. Now create the Element folders and files.

If you are not familiar with YAML, read our Understanding YAML doc. You can use PHP array based configuration. Create config.php file instead.

YAML file code example

config.yml

name: Call To Action
slug: call_to_action
groups: content

form:
  general:
    - name: title
      type: text
      help: Provide title text

    - name: description
      type: editor
      value: Lorem ipsum dolor sit amet timeam
      help: Create or modify your description.

    - name: button 
      type: link

  styles:
    - name: font
      type: typography

    - name: title_color
      type: color

    - name: description_color
      type: color

    - name: bg_color
      type: color
      label: Background Color

    - name: margin
      type: margin

    - name: padding
      type: padding

PHP file code example

config.php

return [
  'name' => 'Call To Action',
  'slug' => 'call-to-action',
  'groups' => ['content'],
  'form' => [
    'general' => [
      [ 
        'name' => 'title', 
        'type' => 'text',  
        'help' => 'Provide title text' 
      ],
      [ 
        'name' => 'description', 
        'type' => 'editor',  
        'value' => 'Lorem ipsum dolor sit amet timeam'
        'help' => 'Create or modify your description.' 
      ],
      [
        'name' => 'button',
        'type' => 'link'
      ]
    ],
    'styles' => [
      [
        'name' => 'font',
        'type' => 'typography'
      ],
      [
        'name' => 'title_color',
        'type' => 'color'
      ],
      [
        'name' => 'description_color',
        'type' => 'color'
      ],
      [
        'name' => 'bg_color',
        'type' => 'color'
        'label' => 'Background Color'
      ],
      [ 'name' => 'margin', 'type' => 'margin'],
      [ 'name' => 'padding', 'type' => 'padding'],
    ]
  ],
];

In PHP 5.4 and above you can write array like 'general'=> [] instead 'general'=> array().

This YAML is made up of two main parts. First, the head of the file which sets the Name, Slug, and Group. The Name is what appears in the administrator as the title of the Element in the Element List and Settings panels. The Slug is the unique indentifier of the Element. The Groups is use to organize the Element on list page.

The Slug must be an unique name and same as the Element folder name.

The second section sets the forms/fields that appear in the administrator Element settings. These fields are what appear in the administrator and are accessible to site managers. They give them the ability to do things like set custom text, titles, and toggle settings.

The first block general is the name of the tab under the fields will be visible. It tells Quix to organize the fields under differnet tab.

There are three main tabs for every Element settings:

Tab	Description
General	Put your content related fields (title, description, image) and general fields(alignment, animation, etc) here.
Style	Pull all style releated fields here, color, typography, background etc.
Advanced	Quix automatically push this tab to every Element settings screen allow you to set name, id and class.

Here is a breakdown of the settings used in the example above and how they affect the file:

Settings	Description
Name	(Required) Unique Name identifying the field. Must be different from all other field names.
Type	(Required) Sets the type of field. This determines if your user will see a text field, checkbox, toggle, or some other input type. More about field type.
Label	(Optional) This label appears on the backend next to the field, letting the user know what it is/does. Fall back to name field if not provided.
Help	(Optional) This field sets the additional instrution to the user.
Value	This sets the default value that appears in the field. If it's a text field, you would enter text. If it's a toggle, you would set it a true or false.

Creating the View File

The next file you will need to create will sit in the same directory as the YAML file is view.php.

Here is the content of the view.php file:

<?php
  $classes = classNames( "qx-element qx-element-{$type} {$field['class']}", $visibilityClasses );
?>
<div id="<?php echo $id; ?>" class="<?php echo $classes; ?>">
  <?php if($field['title']):?>
    <h3><?php echo $field['title']; ?></h3>
  <?php endif; ?>

  <?php if($field['description']):?>
    <div><?php echo $field['description']; ?></div>
  <?php endif; ?>

  <?php if(<?php echo $field['button']['text'] ?>):?>
    <a 
      class="qx-btn qx-btn-default" 
      href="/<?php echo $field['button']['url'] ?>" 
      <?php echo ( $field['button']['target'] ) ? ' target="_blank"' : '' ?>>
      <?php echo $field['button']['text'] ?>
    </a>
  <?php endif; ?>
</div>

This is basic example of a view file.

$classes = classNames( "qx-element qx-element-{$type} {$field['class']}", $visibilityClasses );

classNames is an utility function gives you flexibility of adding classes. See our utility functions page for more details. There are few variable available in every Element view file.

Variable	Description
$id	Unique ID for every Element. Quix create an unique ID and you can change it from Advanced Tab
$type	Element type define in slug
$visibilityClasses	Bootstrap responsive classes added by Quix.
$field['class']	You can add extra class for Element from Advanced Tab and get the value using this code.

Accessing fields value is pretty straightforward using the $field variable. You can pull any field value using $field['NAME'] code.

Styling the Element

Create style.php file under the same directory of yoru YAML file. Quix seperate styleing from view file so it looks clean and easily managable.

Here is the content of style.php file :

#<?php echo $id?>{
  <?php Css::fonts($field['font']);?>
  <?php Css::prop('background', $field['bg_color']);?>
  <?php Css::margin($field['margin']);?>
  <?php Css::padding($field['padding']);?>
}
#<?php echo $id?> h3{
  <?php Css::prop('color', $field['title_color']);?>
}
#<?php echo $id?> div{
  <?php Css::prop('color', $field['description_color']);?>
}

You can write simple css code here. #<?php echo $id?> code ensure this style only affecting this element.

<?php Css::prop('color', $field['description_color']);?>

This css helper function will reduce your conditional check for each field. First argument takes css properties and second is the field value. See our utility functions page for more details.