Differences

This shows you the differences between two versions of the page.

Link to this comparison view

developer:splint_json [2019/06/04 01:20]
developer:splint_json [2019/06/04 01:20] (current)
Line 1: Line 1:
 +====== Splint.json Package Descriptor ======
  
 +The ''​splint.json''​ file that resides at the root of a splint package is a file that describes the package. It can also be used to convey more information about the package such as category, authors, etc.\\
 +
 +The full form of the file looks like this.\\
 +
 +<code json>
 +{
 +    "​name":​ "​vendor/​name",​
 +    "​type":​ "​library|application|config|template",​
 +    "​paged":​ true|false,
 +    "​config":​ "​@config_name",​
 +    "​config_items":​ {
 +      "​config_item1":​ "​(data_type) config_description1",​
 +      "​config_item2":​ "​(data_type) config_description2",​
 +      "​config_itemN":​ "​(data_type) config_descriptionN",​
 +    },
 +    "​description":​ "​Description goes here",
 +    "​tags":​ ["​tag",​ "​goes",​ "​here"​],​
 +    "​page":​ "​https://​github.com/​vendor/​name",​
 +    "​website":​ "​https://​example.com",​
 +    "​authors":​ [
 + {
 +     "​name":​ "a name goes here",
 +            "​email":​ "an email goes here",
 +            "​page":​ "a page goes here",
 +            "​role":​ "a role goes here"
 +        }
 +    ],
 +    "​php":​ ">​=7.2.0",​
 +    "​depends-on":​ [
 +        "​another-vendor/​another-name"​
 +    ],
 +    "​autoload":​ {
 +        "​libraries":​ [
 +            ["​ClassName1",​ {"​argKey1":​ "​argVal1",​ "​argKey2":​ "​argVal2",​ "​argKeyN":​ "​argValN"​},​ "​alias1"​],​
 +            ["​ClassName2",​ "​alias2"​],​
 +            ["​ClassName3",​ "​@config_file_name",​ "​alias2"​]
 +        ],
 +        "​models":​ [
 +            ["​Model1",​ "​alias2"​],​
 +            ["​Model2,​ "​alias3"​]
 +        ],
 +        "​helpers":​ ["​helper1,​ "​helper2",​ "​helperN"​],​
 +        "​configs":​ ["​config1",​ "​config2",​ "​configN"​] ​
 +    }
 +}
 +</​code>​
 +
 +===== Key-Value Pairs =====
 +
 +^ Key          ^ Description ​                                   ^ Required ^ Example(s) ​             ^
 +| ''​name''​ (string) ​   | Fully qualified package name. | Yes             | ''​zoey/​bootstrap''​ |
 +| ''​type''​ (string) ​     | Package Type                                | Yes            | ''​library'',​ ''​application''​ |
 +| ''​description''​ (string) | The Package'​s description | Yes            | A Library for making life easy. |
 +| ''​tags''​ (string array) | Tags or keywords that bring the package into a search result. | No | ''​git'',​ ''​preference'',​ ''​embedded''​ |
 +| ''​page''​ | The GitHub repository link for the package. | Yes | https://​github.com/​zoey/​bootstrap |
 +| ''​website''​ | A web page that contains more information about a package or its documentation. | No | http://​example.com |
 +| ''​authors''​ (json array) | An array of ''​JSON''​ objects that describes the author(s) of a package. | No | ''​{ "​name":​ "John Doe", "​email":​ "​johndoe@email.com",​ "​page":​ "​http://​example.com",​ "​role":​ "​Developer"​ }''​ |
 +| ''​php''​ (string)| The minimum php version required for this package to run seamlessly | No | 5.6.0 |
 +|''​depends-on''​ (string array)| An array of package identifiers the current package depends on in order to work. These packages will be installed alongside the current package. | No | ''​jonas/​git''​ |
 +|''​autoload''​ (json object) | A JSON object which optionally contains the ''​libraries'',​ ''​models'',​ ''​configs'',​ & ''​helpers''​ key which instructs the SPlint loader to load them when a call to ''​this->​load->​package($splint)''​ is made. | No | ''"​autoload":​ {"​libraries":​[ ["​ClassName",​ "​alias"​] ] }''​ |
 +| ''​libraries''​ (json array of json arrays) | A Child of the ''​autoload''​ key. A JSON Array of JSON Arrays with maximum a maximum length of 3 each, containing the Class name to load and its corresponding alias as the first and second element respectively,​ or the Class name to load, a JSON object containing key-value pairs for initialization paraters, and the corresponding alias as the first, second, and third elements respectively | No | ''​[ ["​ClassName",​ "​alias"​ ] ]''​ OR ''​[ [ "​ClassName",​ {"​param1"​ => "​val1",​ "​paramN"​ => "​valN"​},​ "​alias"​ ] ]''​ OR ''​[ [ "​ClassName",​ "​@config_file_name",​ "​alias"​] ]''​ |
 +| ''​models''​ (json aray of arrays) | A child of the ''​autoload''​ key. A JSON Array containing JSON Arrays with a maximum length of 2 each, containing the Model Class Name and optionally it's corresponding alias. | No | ''​ [ [ "​ModelClass",​ "​alias"​ ] ] ''​ |
 +| ''​helper''​ (json array) | A child of the ''​autoload''​ key. A JSON array of helpers to autoload. | No | ''​ [ "​helper1",​ "​helper2",​ "​helperN"​ ] ''​ |
 +| ''​configs''​ (json array) | A child of the ''​autoload''​ key. A JSON array of configs to autoload. | No | ''​ [ "​config1",​ "​config2",​ "​configN"​ ] ''​ |
 +| ''​paged''​ (boolean) | Used if package type is that of ''​application''​ this is used to indicate to Splint or end-users that your splint application fully supports paging. See [[app_developer:​splint_app_paging|Splint App Paging]] for more. | No | ''​true'',​ ''​false''​ |
 +| ''​config''​ (string) | Value optionally starts with an '​@'​ symbol. This indicates the config file to load and merge with the associative array you pass to the ''​$this->​load->​app()''​ function. | No | ''​@config_file''​ |
 +| ''​config_items''​ (json object) | A JSON of config items that can be present within the config file specified by the ''​config''​ key or the config file set in descriptor auto-loading, ​ and their description. This is for documentation purposes. | No | ''​{"​a_setting":​ "​a_value"​}''​ |
 +
 +===== Example =====
 +
 +<code json>
 +{
 +    "​name":​ "​zoey/​bootstrap",​
 +    "​type":​ "​library",​
 +    "​description":​ "A package for using bootstrap within code igniter.",​
 +    "​tags":​ ["​html",​ "​css",​ "​bootstrap"​],​
 +    "​page":​ "​https://​github.com/​zoey/​bootstrap",​
 +    "​website":​ "​https://​bootstrap.com",​
 +    "​authors":​ [
 + {
 +     "​name":​ "​Zoey",​
 +            "​email":​ "​zoey@email.com",​
 +            "​page":​ "​about.me/​zoey",​
 +            "​role":​ "​Developer"​
 +        }
 +    ],
 +    "​php":​ ">​=7.2.0",​
 +    "​depends-on":​ [
 +        "​jenkinson/​ci-css"​
 +    ],
 +    "​autoload":​ {
 +        "​libraries":​ [
 +            ["​BootStrap",​ "​bootstrap"​]
 +        ]
 +    }
 +}
 +</​code>​
 +
 +If you want your package to go get its loading parameters from a config file of choosing by end users, you can follow the example below.
 +
 +<code json>
 +{
 +    "​name":​ "​zoey/​bootstrap",​
 +    "​type":​ "​library",​
 +    "​description":​ "A package for using bootstrap within code igniter.",​
 +    "​tags":​ ["​html",​ "​css",​ "​bootstrap"​],​
 +    "​page":​ "​https://​github.com/​zoey/​bootstrap",​
 +    "​website":​ "​https://​bootstrap.com",​
 +    "​authors":​ [
 + {
 +     "​name":​ "​Zoey",​
 +            "​email":​ "​zoey@email.com",​
 +            "​page":​ "​about.me/​zoey",​
 +            "​role":​ "​Developer"​
 +        }
 +    ],
 +    "​php":​ ">​=7.2.0",​
 +    "​depends-on":​ [
 +        "​jenkinson/​ci-css"​
 +    ],
 +    "​autoload":​ {
 +        "​libraries":​ [
 +            ["​BootStrap",​ "​@bootstrap_config"​ "​bootstrap"​]
 +        ]
 +    }
 +}
 +</​code>​
 +
 +This means that a call to ''​$this->​load->​package("​zoey/​bootstrap"​)''​ will load the Splint package with parameters from a config file located at ''​application/​config/​bootstrap_config.php''​.
 +
 +> Splint will not throw an Exception if this file doesn'​t exist. You must check the argument array in your class constructor and verify use the ''​isset()''​ function to check for present values.
 +
 +The config file for end users in this particular scenario should look like this.
 +
 +<code php>
 +<?php
 +defined('​BASEPATH'​) OR exit('​No direct script access allowed'​);​
 +
 +$config["​bootstrap_config"​] = [
 +  "​arg1"​ => "​value1",​
 +  "​arg2"​ => "​value2",​
 +  "​argN"​ => "​valueN"​
 +]
 +?>
 +</​code>​
 +
 +> Notice that the ''​key''​ of the array in the ''​$config''​ variable is the same as the name of the config file.
 +===== NEXT =====
 +[[developer:​descriptor_autoloading|Descriptor Autoloading]] => \\
 +
 +===== PREVIOUS =====
 +<= [[developer:​unit_testing|Unit Testing Packages]]\\
 +
 +===== Other Topics =====
 +
 +[[library-install|Install a Splint Library]]\\
 +[[splint_client:​start|Splint Client]]\\
 +[[load_splint|Load Splint Libraries]]\\
 +[[developer:​descriptor_autoloading|Descriptor Autoloading]]\\