WordPress & Joomla Documentation - ThemeXpert

Custom Element Path

2016-05-18T16:59:11+06:00

Extension developers can create elements for their extension direct inside the extension folder. By default, Quix listen its own elements folder and active template's folder.

Register Element Path

if ( file_exists( JPATH_LIBRARY . "/quix/app/bootstrap.php" ) ) {
    quix()->getElementsBag()->fill( YOUR_EXTENSION_PATH . "/elements", YOUR_EXTENSION_URL . "/elements" );
}

You have to provide your extension's element path and url. Replace YOUR_EXTENSION_PATH with extension's file path and YOUR_EXTENSION_URL with extension's url.

How To Disable Elements

2016-05-18T16:46:50+06:00

Sometimes you need to disable few core elements from your template or extensions. Create a file name quix.php inside templates/YOUR_TEMPLATE/quix directory and use this code below to disable any elements you want.

<?php
    quix()->disableElements(['button', 'image']);

Provide element slug in disableElements function. Replace YOUR_TEMPLATE with your current active template name.

User can always enable any of your disabled element from Element Manager. If you disable an element that already used on some pages, the element will work as it is. It will only effect when someone try to add a new element.

If you disable any elements from template/extensions that already enabled/disabled by user before, disableElements will not have any effect on that elements.

How to Load CSS / JS in Element

2016-05-18T13:42:32+06:00

A new Asset Manager introduced in Quix 1.1.0 to unify the interface throughout Quix for adding and managing CSS and JavaScript. Asset Manager simplify the process of adding JavaScript and/or CSS from your elements view file.

The Asset Manager is just a class that is available throughout Quix files. There are 2 paths already registered as global constant so you can quickly resolve the path from your elements.

Constant	Resolved Path
`QUIX_URL`	/libraries/quix
`QUIX_TEMPLATE_URL`	/templates/YOUR_TEMPLATE/quix

Adding Css

Assets::Css ( string $handle, string $src = false, int $order, string|bool|null $ver = false )

Parameters	Description
`$handle`	(string) (Required) Name of the script. Should be unique. You can also pass $slug as its unqiue for every element
`$src`	URL of the script, eg: `QUIX_URL."/assets/css/style.css"`
`$order`	(int) (Optional) Specifying assets order, if it has one, asset will load on specified order or default order.
`$ver`	(string or bool or null) (Optional) String specifying script version number, if it has one, which is added to the URL as a query string for cache busting purposes. If version is set to false, a version number is automatically added equal to current installed Quix version. If set to null, no version is added.

Example

Assets::Css($slug, QUIX_TEMPLATE_URL."/elements/MY_ELEMENT/css/style.css", 12);

Replace MY_ELEMENT with your element folder name. By defining 12 you are telling Quix to load this assets to 12 number position. If total assets is less than provided order value, it will load end of the asset.

Adding InlineCss

Create style.php file insdie your element folder and you can write css code here. All css code will injected to your html header.

Beauty of this approach is, you can write conditional css with php and all the element fields available on this file.

Example

<?php if($field['title]):?>
#<?php echo $id?> .qx-title{ color: red; }
<?php endif?>

In this example, we checked if there anything in title field. If yes, we added title color. We can make it more dynamic like this :

<?php if($field['title]):?>
#<?php echo $id?> .qx-title{ <?php Css::prop('color', $field['title_color']);?> }
<?php endif?>

Adding Javascript

Assets::Js ( string $handle, string $src = false, array $deps = array(), int $order, string|bool|null $ver = false )

Parameters	Description
`$handle`	(string) (Required) Name of the script. Should be unique. You can also pass $slug as its unqiue for every element
`$src`	URL of the script, eg: `QUIX_URL."/assets/css/style.css"`
`$deps`	(array) (Optional) An array of registered script handles this script depends on.
`$order`	(int) (Optional) Specifying assets order, if it has one, asset will load on specified order or default order.
`$ver`	(string or bool or null) (Optional) String specifying script version number, if it has one, which is added to the URL as a query string for cache busting purposes. If version is set to false, a version number is automatically added equal to current installed Quix version. If set to null, no version is added.

Example

Assets::Js($slug, QUIX_TEMPLATE_URL."/elements/MY_ELEMENT/js/script.js", array('jQuery'), 12);

Replace MY_ELEMENT with your element folder name. By defining 12 you are telling Quix to load this assets to 12 number position. If total assets is less than provided order value, it will load end of the asset.

Adding Inline Javascript

Create another php file inside your element folder and call it line any other javascript file.

Assets::Js( QUIX_TEMPLATE_URL . '/elements/MY_ELEMENT/inline-js.php');

If you add php file using Assets::Js() it will automatically add in your html header. There are several benefits of this approach. You can pass any php value in your js file.

Example

Assets::Js( QUIX_TEMPLATE_URL . '/elements/MY_ELEMENT/inline-js.php', compact(['id']));

inline-js.php file

jQuery(document).ready(function(){
  jQuery("#<?php echo $id?>").css('width', 20);
});

In this example, we passed id from our view file(You can pass any php variable) and used it in your js file

Understanding YAML

2016-05-09T10:03:55+06:00

According to the official YAML website, YAML is "a human friendly data serialization standard for all programming languages".

Even if the YAML format can describe complex nested data structure, this chapter only describes the minimum set of features needed to use YAML as a configuration file format.

YAML is a simple language that describes data. As PHP, it has a syntax for simple types like strings, booleans, floats, or integers. But unlike PHP, it makes a difference between arrays (sequences) and hashes (mappings).

Scalars

The syntax for scalars is similar to the PHP syntax.

Strings

Strings in YAML can be wrapped both in single and double quotes. In some cases, they can also be unquoted:

A string in YAML

'A singled-quoted string in YAML'

"A double-quoted string in YAML"

Quoted styles are useful when a string starts or end with one or more relevant spaces, because unquoted strings are trimmed on both end when parsing their contents. Quotes are required when the string contains special or reserved characters.

When using single-quoted strings, any single quote ' inside its contents must be doubled to escape it:

'A single quote '' inside a single-quoted string'

Strings containing any of the following characters must be quoted. Although you can use double quotes, for these characters it is more convenient to use single quotes, which avoids having to escape any backslash \:

:, {, }, [, ], ,, &, *, #, ?, |, -, <, >, =, !, %, @, \

The double-quoted style provides a way to express arbitrary strings, by using \ to escape characters and sequences. For instance, it is very useful when you need to embed a \n or a Unicode character in a string.

"A double-quoted string in YAML\n"

If the string contains any of the following control characters, it must be escaped with double quotes:

\0, \x01, \x02, \x03, \x04, \x05, \x06, \a, \b, \t, \n, \v, \f, \r, \x0e, \x0f, \x10, \x11, \x12, \x13, \x14, \x15, \x16, \x17, \x18, \x19, \x1a, \e, \x1c, \x1d, \x1e, \x1f, \N, \_, \L, \P

Finally, there are other cases when the strings must be quoted, no matter if you're using single or double quotes:

When the string is true or false (otherwise, it would be treated as a boolean value);
When the string is null or ~ (otherwise, it would be considered as a null value);
When the string looks like a number, such as integers (e.g. 2, 14, etc.), floats (e.g. 2.6, 14.9) and exponential numbers (e.g. 12e7, etc.) (otherwise, it would be treated as a numeric value);
When the string looks like a date (e.g. 2014-12-31) (otherwise it would be automatically converted into a Unix timestamp).

When a string contains line breaks, you can use the literal style, indicated by the pipe (|), to indicate that the string will span several lines. In literals, newlines are preserved:

|
  \/ /| |\/| |
  / / | |  | |__

Alternatively, strings can be written with the folded style, denoted by >, where each line break is replaced by a space:

>
This is a very long sentence
that spans several lines in the YAML
but which will be rendered as a string
without carriage returns.

Notice the two spaces before each line in the previous examples. They won't appear in the resulting PHP strings.

Numbers

# an integer
12

# an octal
014

# an hexadecimal
0xC

# a float
13.4

# an exponential number
1.2e+34

# infinity
.inf

Nulls

Nulls in YAML can be expressed with null or ~.

Booleans

Booleans in YAML are expressed with true and false.

Dates

YAML uses the ISO-8601 standard to express dates:

2001-12-14t21:59:43.10-05:00

# simple date
2002-12-14

Collections

A YAML file is rarely used to describe a simple scalar. Most of the time, it describes a collection. A collection can be a sequence or a mapping of elements. Both sequences and mappings are converted to PHP arrays.

Sequences use a dash followed by a space:

- PHP
- Perl
- Python

The previous YAML file is equivalent to the following PHP code:

array('PHP', 'Perl', 'Python');

Mappings use a colon followed by a space (: ) to mark each key/value pair:

PHP: 5.2
MySQL: 5.1
Apache: 2.2.20

which is equivalent to this PHP code:

array('PHP' => 5.2, 'MySQL' => 5.1, 'Apache' => '2.2.20');

In a mapping, a key can be any valid scalar.

The number of spaces between the colon and the value does not matter:

PHP:    5.2
MySQL:  5.1
Apache: 2.2.20

YAML uses indentation with one or more spaces to describe nested collections:

'symfony 1.0':
  PHP:    5.0
  Propel: 1.2
'symfony 1.2':
  PHP:    5.2
  Propel: 1.3

The above YAML is equivalent to the following PHP code:

array(
  'symfony 1.0' => array(
    'PHP'    => 5.0,
    'Propel' => 1.2,
  ),
  'symfony 1.2' => array(
    'PHP'    => 5.2,
    'Propel' => 1.3,
  ),
);

There is one important thing you need to remember when using indentation in a YAML file: Indentation must be done with one or more spaces, but never with tabulators.

You can nest sequences and mappings as you like:

'Chapter 1':
  - Introduction
  - Event Types
'Chapter 2':
  - Introduction
  - Helpers

YAML can also use flow styles for collections, using explicit indicators rather than indentation to denote scope.

A sequence can be written as a comma separated list within square brackets ([]):

[PHP, Perl, Python]

A mapping can be written as a comma separated list of key/values within curly braces ({}):

{ PHP: 5.2, MySQL: 5.1, Apache: 2.2.20 }

You can mix and match styles to achieve a better readability:

'Chapter 1': [Introduction, Event Types]
'Chapter 2': [Introduction, Helpers]

'symfony 1.0': { PHP: 5.0, Propel: 1.2 }
'symfony 1.2': { PHP: 5.2, Propel: 1.3 }

Comments

Comments can be added in YAML by prefixing them with a hash mark (#):

# Comment on a line
"symfony 1.0": { PHP: 5.0, Propel: 1.2 } # Comment at the end of a line
"symfony 1.2": { PHP: 5.2, Propel: 1.3 }

Comments are simply ignored by the YAML parser and do not need to be indented according to the current level of nesting in a collection.

Taken from Symfony YAML doc

Utility Functions

2016-05-09T10:03:02+06:00

Quix comes with so many utility functions and classes to help you develop faster.

classNames

A simple utility function for conditionally joining classNames together. Example:

$classes = classNames( "qx-element qx-element-{$type} {$field['class']}", $visibilityClasses, [
    'qx-text-left' => $field['alignment'] === 'left',
    'qx-text-center' => $field['alignment'] === 'center',
    'qx-text-right' => $field['alignment'] === 'right',
    "wow {$field['animation']}" => $field['animation']
]);

Think you have an alignment slectbox in your element config that allow you to control text alignment. Bootstrap comes with alignment classes so you need to add right class in your <div> or <p> tag.

Traditional Way

$class = '';
if( $field['alignment'] == 'left' ){
  $class = 'qx-text-left';
}elseif( $field['alignment'] == 'center' ){
  $class = 'qx-text-center';
}elseif( $field['alignment'] == 'right' ){
  $class = 'qx-text-right';
}

classNames() Function

$classes = classNames([
    'qx-text-left' => $field['alignment'] === 'left',
    'qx-text-center' => $field['alignment'] === 'center',
    'qx-text-right' => $field['alignment'] === 'right',
]);

Plus you can join many class together, like :

$classes = classNames( "qx-element qx-element-{$type}",[
    'qx-text-left' => $field['alignment'] === 'left',
    'qx-text-center' => $field['alignment'] === 'center',
    'qx-text-right' => $field['alignment'] === 'right',
    "wow {$field['animation']}" => $field['animation']
]);

"wow {$field['animation']}" => $field['animation'] based on animation settings.

This class is designed to reduce your conditional code. Take a look at all core element for better understanding of its usages.

More Example of classNames()

classNames('foo', 'bar'); // => 'foo bar'
classNames('foo', [ bar: true ]); // => 'foo bar'
classNames([ 'foo-bar': true ]); // => 'foo-bar'
classNames([ 'foo-bar': false ]); // => ''
classNames([ foo: true ], [ bar: true ]); // => 'foo bar'
classNames([ foo: true, bar: true ]); // => 'foo bar'

// lots of arguments of various types
classNames('foo', [ bar: true, duck: false ], 'baz', [ quux: true ]); // => 'foo bar baz quux'

// other falsy values are just ignored
classNames(null, false, 'bar', undefined, 0, 1, [ baz: null ], ''); // => 'bar 1'

Css Helpers

Font

<?php Css::fonts($field['font']);?>

This function automatically determine the font properties from your config and output them. If any of your typography field left blank, this function will not output it. Css output example:

font-family: 'Ubuntu';
font-size: 16px;
line-height: 30px;
....

Margin

<?php Css::margin($field['margin']);?>

This function automatically determine the margin properties from your config and output them accordingly. If any field left blank, this function will not output it. Css output example:

margin-top: 16px;
margin-btoom: 30px;
....

Padding

<?php Css::padding($field['padding']);?>

This function automatically determine the padding properties from your config and output them accordingly. If any field left blank, this function will not output it. Css output example:

padding-top: 16px;
padding-btoom: 30px;
....

Css Properties

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

This is a dynamic class for all css properties. First argument takes the css properties and second argument takes the value.

More example :

<?php Css::prop('background-repeat', $field['image_repeat']);?>
<?php Css::prop('background-position', $field['image_position']);?>
<?php Css::prop('background-size', $field['image_size']);?>

Elements Overriding and Extending

2016-05-09T10:01:39+06:00

Sometime you need to override core elements style and view for your theme. When creating overrides, you should always keep these files in your quix directory.

Do not change any core element files. You may loose all changes when you update Quix.

Creating a New Element

2016-05-09T10:00:55+06:00

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="https://www.themexpert.com/<?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.

Element Field Types

2016-05-09T09:59:43+06:00

Quix has lots of built-in form fileds which you can use to build your element. Look at our step by step guide to creating an element.

Which fields you can use

Field	Description
Text	A simple text field
Textarea	A textarea
Link	Link field with all associated fields
Switch	A switch value field
Icon	A fontawesome icon slector
Image	A image field for uploading and selecting image
Select	A select field
Editor	A WYSIWYG editor field
Typography	Typography selector fields
Color	A color input field
Margin	A margin input field
Padding	A padding input field
Slider	A range input type
Divider	Used to add a title, text or an horizontal line to the form
Input Repeater	A single input repeater field
Group Repeater	Group input repeater field can contain multiple input field

Common Fields Attributes

Every field accepts a list of attributes you can use. Each field could share these common attributes, but particular fields might ignore them. The best way to check which attributes are allowed on a field is to check the field description in this page, and see which attributes are mentioned.

This list provides a common ground so there's no need to repeat the description of a common field.

Attribute	Description
`name`	sets the field name
`type`	sets the field type
`label`	sets the field label (optional)
`help`	Adds a tooltip to the field (optional)
`value`	sets the field default value (optional)
`depends`	sets the field depends another field (optional)

Positive values

You can set positive values in multiple ways: 'true', 1. Other values are interpreted as negative.

The Text Field {#the-text-field}

The text field is used to present a text input field.

Example:

- name: title
  type: text

Common Attributes Allowed
name
label
help
value