Hello World package is a simply package to explain how a very simple package can be created.

Hello World Package is define the following:

  • Block: Display a text that is taken as Block Shortcode Parameter.
  • Template: Style the displayed text.
  • readme
  • license

Template Code

h1.hello-world-text {font-size: 24px; color: red}

Block Code

<h1 class="hello-world-text">
<?php
// Display text as passed for the Text input parameter.
echo $cb->params()->get('text');
?>
</h1>

definition.xml File

<?xml version="1.0" encoding="utf-8" ?>
<package xmlns="http://css-javascript-toolbox/xml/namespaces/cjt/6/package">
<name>HelloWorld</name>
<description>CJT Hello World package example</description>
<author>CJT</author>
<webSite>https://css-javascript-toolbox.com/scripts/examples/HelloWorld/</webSite>
<license locate="file" />
<readme locate="file" />
<objects>
<object type="template">
<name>hello-world-style-sheet</name>
<description>Hello World Stylesheet file</description>
<code locate="file">template/style.css</code>
</object>
<object type="block">
<name>HelloWorld</name>
<code locate="file">block/hello-world.php</code>
<params>
<form>
<name>Hello World</name>
<groupType>tab</groupType>
<groups>
<group>
<name>General</name>
</group>
</groups>
</form>
<list>
<param>
<name>Text</name>
<type>text</type>
<group name="General">
<renderer>input</renderer>
</group>
</param>
</list>
</params>
<links>
<link name="hello-world-style-sheet" />
</links>
</object>
</objects>
</package>

The package is also available for hello-world

Attaching images to Template can be very useful when a Template of type CSS need to link to images.

Attaching images can be done via folder tag as following:

<folders path="PATH/TO/ALL/CHILD/FOLDERS">
  <folder path="FOLDER_PATH_TO_UPLOAD" />
</folders>

folders tag allows to group a set of related folders without repeating the path on each on of them. Multiple folder tags might exists inside the folders tag.

Pointing to file is to point to a package file located inside the package from the definition.xml file, so that package process can locate those files and loading them

Point to Block code File named block.php located in the package root folder.

<object type="block">
  <code locate='file'>block.php</object>
</object>

Point to Block code File named block.php located in the a folder named blocks in the package root folder.

<object type="block">
  <code locate='file'>blocks/block.php</object>
</object>

Group is used to group a set of parameters together. It has no logical affects however it will be used by the Form to display each group as set of parameters.

Creating group can be done by using group tag. Its possible to create multiple groups with no limitation.


<group>
 <name>NAME</name>
 <description>DESCRPTION_TEXT</description>
</group>

Data Fields

  • NAME: Used as the parameters set title.
  • DESCRIPTION_TEXT: Help text for that define the parameters set. It will be showed as Tooltips.

Linking Template to a Block can be done through package definition XML file via link tag. Link multiple Templates can be done by using as many link tags as needed.

link tag must be presented under the root links tag as following:

<object type="block">
  <links>
   <link name="TEMPLATE_NAME_1" />
   <link name="TEMPLATE_NAME_2" />
   <link name="TEMPLATE_NAME_3" />
  </links>
</object>

CJT Block Shortcode parameters form is provide a few Input Types to be used for talking user inputs. Its mean the Input Field Type to be used for getting user Inputs. For example Boolean Parameter might use either Checkbox or (Yes/No) Dropdown list! This is up to the package author to define which type to use. CJT if providing the following Input Types.

  • array: Used to display parameter of type array. Its generate HTML Fieldlist with the member/child Parameters inside.
  • structure: The same as the array except its used for the structure data type.
  • checkbox
  • dropdown
  • list
  • input
  • textarea
  • imageslist: Allows user to select multiple images via WordPress Media Popup.

Parameter Data Types is used by CJT Shortcode Block parameters form for validating user inputs and generating Shortcode Parameters Text/String.

The following Data Types are being supported by CJT.

Native/Primitive Data Types

  • boolean: Accept String true/false or numeric 1/0.
  • number: Accepts any numeric value
  • text: Accept String data.
  • raw: Same as the text data type except that when generated as Shrotcode, it won’t wrapped by Quotes.

Structured Data Types — Collection

  • array: Accepts a list/array of any CJT Data Types (Array, Boolean, List, etc..). Generate Shortcode Parameter Text as CJT Array JSON {A ITEM-0, ITEM-1 A}. Passing Javascript array as CJT parameters require use of {A A} instead of Javascript array [ ]. This is important as WordPress Shortcode parser is unable to parse Shortcodes when parameters containing [ or ].
  • structure: Represent Structure Data Type that holds other CJT Data Types. The different between array and structure is that the later one would generate Shortcode Parameters text as JSON Object instead of Array. Array type is discarding all the child parameters names unlike structure data type is preserving the names.

Define Block Shortcode Form Parameters would inform CJT to carry up few steps based on the current process. Two process is being handled when using Block Shortcode with parameters based.

Insert Shortcode

  • Get user Inputs through internal Parameter Form
  • Validate Parameters value based on the Parameter Data Type
  • Generate Block Shortcode text.

Process Shortcode

  • Read Shortcode Parameters.
  • Validate Shortcode Parameters (This is important in case Shortcode text is typed manually)
  • Allow Code Block to access Shortcode parameters by using CJT Blocks Developer API (CBDA)

Defining Block Parameter is done by using param tag. There is no limitation of the number of parameters that can be defined for the Block.

<param>
  <name>PARAM_NAME</name>
  <type>DATA_TYPE</type>
  <defaultValue>DEFAULT_VALUE</defaultValue>
  <group name="GROUP_NAME">
   <renderer>INPUT_TYPE</renderer>
   <description>PARAM_DESCRIPTION</description>
  </group>
</param>

Data Fields

  • PARAMS_NAME: Parameter name used for read/write parameter value and will be the title of the input field.
  • DATA_TYPE: Data type used to validate and generate parameter Shortcode text.
  • DEFAULT_VALUE: To be used when Parameter is not being passed
  • GROUP_NAME: Associate to group.
  • INPUT_TYPE: Input field type to be used for receiving user inputs (Text, Dropdown List, Checkbox, etc…). For more info about the supported input types checkout Input Types article.
  • PARAM_DESCRIPTION: Parameter input field help text.

Content Parameter

Each block might content one Content Parameter. Content Parameter is to use the TEXT between Shortcode open and close tags. Its great when generating TEXT inside the Shortcode is required like getting a list of HTML Images of Links. It should be used with RAW data type.

<param>
  <contentParam>1</contentParam>
</param>

One of few features is only available via Packages and currently cannot be achieved using Windows!

Shortcode parameters form is CJT internal form used to prompt for Block parameters when inserted as Shortcode via TinyMCE shortcodes list. Parameters also might be passed directly by writing the Shortcode manually however PRO edition helps using simple form that validate and do the internal jobs that required for generating Shortcode.

Defining Shortcode Parameters form created using form tag and just required few simple parameters.

<form>
  <name>FORM_NAME</name>
  <groupType>GROUP_TYPE</groupType>
</form>
  • FORM_NAME: Form name to show as the Form Title
  • GROUP_TYPE: Form allows add a set of parameters under specific Group. Currently only group of type tab is being supported.

The basic valid structure of the definition.xml file is as following:

<?xml version="1.0" encoding="utf-8" ?>
<package xmlns="http://css-javascript-toolbox/xml/namespaces/cjt/6/package">
   <name>PACKAGE_NAME</name>
   <description>DESCRIPTION</description>
   <author>AUTHOR_NAME</author>
   <webSite>PACKAGE_WEBSITE</webSite>
   <license>RAW_LICENSE or LICENSE_FILE</license>
   <readme>RAW_README or README_FILE</readme>
   <objects>
      OBJECT LIST GOES HERE ...
      AT LEAST ONE BLOCK OBJECT SHOULD BE PRESENETED
      ....
      ....
      .... 
      ....
   </objects>
</package>

The following tags are currently supported for the Package. All of them are being displayed in the Packages Table List.

  • name: Use to identify the package.
  • description: Package description text.
  • author: Package author name.
  • webSite:
  • license
  • readme
<?zml version="1.0" encoding=utf-8" ?>
<package xmlns="http://css-javascript-toolbox/xml/namespaces/cjt/6/package">
<name>NAME</name>
<description>DESC</description>
<author>AUTHOR</author>
<webSite>WEB SITE</webSite>
<license>
<readme>
...
...
...
...
</package>

Attaching license file for the package script is great for developers like to publish/share their CJT package scripts with others. Defining a license for the CJT Package script is defining by license tag. License can be either of raw text inside the Definition XML file or independent package text file.

RAW License

<license>
<![CDATA[
... LICENSE TEXT HERE
... LICENSE TEXT HERE
... LICENSE TEXT HERE
]]>
</license>

License File

<license locate='file' />

NOTE: license.txt file must be presented in the package root folder.

Attaching readme file for the package script is great for developers like to publish/share their CJT package scripts with others. Defining a readme for the CJT Package script is defining by readme tag. Readme file can be either of raw text inside the Definition XML file or independent package text file.

RAW readme

<readme>
<![CDATA[
... README TEXT HERE
... README TEXT HERE
... README TEXT HERE
]]>
</readme>

Readme File

<readme locate='file' />

NOTE: readme.txt file must be presented in the package root folder.

Like creating new Template via user Interface its possible to create new Template by writing definition.xml file command/tag that instruct CJT to create new Template.

Templates must be defined first before Blocks. Linking Block to Templates is not being created yet would cause the package installer to fail.

Creating Template can be done by using <object> tag. object tag with Type=’template’. It would instruct CJT to create new Template by using the fields laying between <object></object> tags.

<object type="template">
  TEMPLATE FIELDS GOES HERE...
  .....
  .....
  .....
</object>

Basic Template Data

Template Data is what defining the Template, the basic Data Field is currently name, type, description and code. They can defined as following:

<object type="block">
  <name>TEMPLATE-NAME</name>
  <description></description>
  <type>TEMPLATE_TYPE</type>
  <code>[RAWDATA] or [CODEFILE]</code>
</object>

Code data can be raw or point to file. Raw data must be presented inside CDATA section as following. Please note that name is very important as its what is used to link Template to Blocks.

Template type can be either html, javascript, css or php however if not specified and a code is pointing to a file it would obtain the type from the code file extension, if no code file or a type defined it would be a css by default. So be careful when defining the type.

<code><![CDATA[RAW-CODE]]></code>

In many situation specially when Block Code is huge, its better to add Block Code in external file as following

<code locate='file'>CODE-FILE</code>

Like creating new Block via user Interface its possible to create new Block by writing definition.xml file command that instruct CJT to create new Block.

Only Global Blocks can defined via Package definition file. Block cannot assigned to WordPress pages when created via Package, assignment to page must be done through UI by webmaster.

Block will be deactivated by default until its being activated by webmaster.

Creating Block can be done by using <object> tag. object tag with Type=’block’ would instruct CJT to create new Block by using the fields laying between <object></object> tags.

<object type="block">
  BLOCK FIELDS GOES HERE...
  .....
  .....
  .....
</object>

Basic Block Data

Block Data is what defining the Block, the basic Data Field is currently name and code. They can defined as following:

<object type="block">
  <name>BLOCK-NAME</name>
  <code>[RAWDATA] or [CODEFILE]</code>
</object>

Code data can be raw or point to file. Raw data must be presented inside CDATA section as following.

<code><![CDATA[RAW-CODE]]></code>

In many situation specially when Block Code is huge, its better to add Block Code in external file as following

<code locate='file'>CODE-FILE</code>

The one file that builds up the CJT Packages. Just like using User Interface for creating Blocks or Templates. User has to click ‘New’ button, Fill the Form, click save and Link Block to Templates if needed. The same operations can be done by writing few keywords to the definition.xml file that CJT Package installer would carry instead of users.

definition.xml file is defining a few XML Tags that can be used to tell CJT what operation should take. The file is processed by the same order from Top to Bottom.

The definition file must be exists in the package root folder otherwise the CJT Installer would fail.

Install

Installing CJT Package is to instruct CJT Package process to load the package definition.xml file and create all Objects (Blocks, Templates, Parameters, etc…)

Currently, after installed the package cannot be downloaded or upgraded. The package can only installed or uninstalled. For upgrading package it should be uninstalled and installed again. CJT Packages is still in BETA release and would be enhanced in the next releases.

NOTE: All installed Blocks would be Deactivated and not being assigned to any WordPress page.

Uninstall

Uninstalling Package is to remove the package and the Objects (Blocks, Templates, Parameters, etc…) that installed within the package. The action is permanent and cannot be reverted.

Packages is a set of CJT Blocks and Templates files added to a ZIP package and defining by the package definition.xml file.

The idea behind the package is to allow sharing a peace of codes between two CJT users or between two CJT servers that all would use the same Blocks/Templates.

A typical package contain one or more Blocks and zero or more Templates. Block can also be linked to Templates. All the available functionality of creating Block/Template from CJT UI is supported via the package definition.xml file. In fact, there’re more features that Packages providing is not being supported by CJT UI. Features like Passing Shortcode Parameters and attach Templates Images is only available through package.

The package is simply a group of files holds Block and Templates code. definition.xml is all about the package! Using this file to define how the CJT installer would handle the package installation process.