Differences
This shows you the differences between two versions of the page.
| — |
app_developer:develop_and_distribute_a_splint_application [2019/06/04 01:20] (current) |
||
|---|---|---|---|
| Line 1: | Line 1: | ||
| + | ====== Develop and Build Your First Splint Application ====== | ||
| + | As with any Splint package, you will have to create a directory structured in a way it's meant to be in an en user's Code Igniter distribution. you will only need to create a ''controllers'' and '' config'' folders additionally for Splint applications. | ||
| + | |||
| + | In this document, we are going to build a real Splint application called blogger, which uses a back-end library name ''blog''. The fully qualified name of this library is [[https://splint.cynobit.com/packages/francis94c/blog|francis94c/blog]] as the username of the vendor is [[https://splint.cynobit.com/vendors/francis94c|francis94c]]. | ||
| + | |||
| + | ===== Create A Blogger Application ===== | ||
| + | ==== Create and Setup the Project ==== | ||
| + | |||
| + | * Download and extract a Code Igniter [[https://github.com/bcit-ci/CodeIgniter/archive/3.1.10.zip|zip]] to your Web/Server Root (WAMP, XAMPP, var/www/html etc.).\\ | ||
| + | |||
| + | * ''cd'' into the ''application'' folder and create a folder named ''splints'' if it doesn't exist.\\ | ||
| + | |||
| + | * Create a folder whose name is your Splint account username e.g ''francis94c''.\\ | ||
| + | |||
| + | * Navigate into the folder and create another folder with the name of the Splint application you want to build. in this case, ''blogger''. This will be your Splint application project directory. | ||
| + | |||
| + | * Running the below from a terminal in the root of the Code Igniter distribution will automate the steps above. | ||
| + | |||
| + | <code bash> | ||
| + | splint -c francis94c/blogger | ||
| + | </code> | ||
| + | |||
| + | * Create a ''splint.json'' file and put something like the one below in it. (Remember, this is an example on how to create a real Splint application. This example is based on an actual procedure used in developing a real application currently existing in Splint with some omissions). | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | "name": "francis94c/blogger", | ||
| + | "type": "application", | ||
| + | "paged": false, | ||
| + | "config": "@config_file_name", | ||
| + | "config_items": { | ||
| + | "header_footer": "(boolean) Whether to display the header and footer on all app pages.", | ||
| + | "new_post_url": "(string) Base URL for the app page responsible for showing the post editor, necessary if instance is paged.", | ||
| + | }, | ||
| + | "description": "A Blog Library for Code Igniter.", | ||
| + | "tags": ["blog", "content", "ui", "application"], | ||
| + | "page": "https://github.com/francis94c/blogger", | ||
| + | "authors": [ | ||
| + | { | ||
| + | "name": "Francis Ilechukwu", | ||
| + | "email": "francis94c@gmail.com", | ||
| + | "page": "about.me/francisilechukwu", | ||
| + | "role": "Developer" | ||
| + | } | ||
| + | ], | ||
| + | "php": ">=5.3.0", | ||
| + | "depends-on": [ | ||
| + | "francis94c/blog" | ||
| + | ] | ||
| + | } | ||
| + | </code> | ||
| + | |||
| + | Notice that the value of the ''type'' key is ''application''. This is necessary for the terminal tool installing your application on an end-user's distribution to handle the installation differently (So as to work as expected) as you would see going further. | ||
| + | |||
| + | Also, as you can see from the above file, this application has a dependency on the ''francis94c/blog'' package, you need to install the package as well within your environment so that you can make use of.\\ | ||
| + | |||
| + | The ''@config_file_name'' is the name of the config file you expect your end-users to create in their own config directory and put in config values. This is not compulsory.\\ | ||
| + | |||
| + | The config file is to have the same structure as described [[developer:descriptor_autoloading#with_config_file|here]].\\ | ||
| + | |||
| + | When your end users install your application, the terminal tool will install all dependencies found. | ||
| + | |||
| + | * Navigate to the root of the Code Igniter application and run the blow in a terminal. | ||
| + | |||
| + | <code bash> | ||
| + | splint install francis94c/blog splint/platform | ||
| + | </code> | ||
| + | |||
| + | The ''splint/platform'' package is required to load a Splint Application. This means that even if your application does not have any dependency, you still need to install this package. and so do your end users. | ||
| + | |||
| + | ==== Create The Default Application Controller ==== | ||
| + | |||
| + | Navigate the application project directory and create a ''controllers'' directory and within it create a ''php'' file that will serve as a controller. Create a class (e.g. ''Home'') within it and make it extend ''SplintAppController'' as opposed to ''CI_Controller''. | ||
| + | |||
| + | > If you extend ''CI_Controller'' instead, you won't have access to some methods that enable you load resources from your application folder at run-time. (In reality, you are developing a sub-application and will need to access your resources differently). | ||
| + | |||
| + | The controller should look like the one below. | ||
| + | |||
| + | <code php> | ||
| + | defined('BASEPATH') OR exit('No direct script access allowed'); | ||
| + | |||
| + | class Home extends SplintAppController { | ||
| + | | ||
| + | function index() { | ||
| + | | ||
| + | } | ||
| + | } | ||
| + | </code> | ||
| + | |||
| + | ==== Doing Stuff ==== | ||
| + | |||
| + | Assuming the purpose of this application is mainly to build source codes, you can add the following inside the ''index'' function. | ||
| + | |||
| + | <code php> | ||
| + | $this->load->splint("francis94c/blog", "+Blogger", $params = ["name" => "sample"], "blog"); | ||
| + | $this->app->blog->renderPostItems(null, null, null, 1, 5, false, false); | ||
| + | </code> | ||
| + | |||
| + | Please see the [[app_developer:splint_app_controller_class|SplintAppController Class]] for details as to why ''$this->app'' is used to access the loaded package class as well as other details to take note of while developing Splint applications. (A full overview on how the system works). | ||
| + | ==== Setting the Default Controller ==== | ||
| + | Navigate to the root of the Splint application project and create the file ''config/routes.php'' file and the below in it. | ||
| + | |||
| + | <code php> | ||
| + | $route['default_controller'] = 'Home'; | ||
| + | $route['404_override'] = ''; | ||
| + | $route['translate_uri_dashes'] = FALSE; | ||
| + | </code> | ||
| + | |||
| + | Assuming ''Home'' is your default Controller. | ||
| + | |||
| + | ==== Running Your Application ==== | ||
| + | Navigate to the root of the Code Igniter distribution and create ''Controller'' as you would normally for a Code Igniter project.\\ | ||
| + | |||
| + | Within any function of choice (remember the function name so you can call it with your web browser), make the following call. | ||
| + | |||
| + | <code php> | ||
| + | $this->load->app("francis94c/blogger"); | ||
| + | </code> | ||
| + | |||
| + | That's it. Open your web browser and fire the recently created ''Controller''. You will see blog posts output. | ||
| + | |||
| + | > You'll likely see a database error if you used the ''francis94c/blog'' app. This is because you need to install the blog table. The README of the package at [[https://github.com/francis94c/blog|https://github.com/francis94c/blog]] has instruction on how to do this. | ||
| + | |||
| + | ==== Distribute Your Application ==== | ||
| + | The process of distribution for Splint applications is the same as that of Splint libraries/packages. See [[developer:create_project#publishingdeploying_your_package_on_splint|here]] for the details]]. | ||
| + | |||
| + | ===== Splint Application Effects on your URL ==== | ||
| + | |||
| + | Traditionally, the Code Igniter Controller ''Class'' and ''method'' to call are specified in the URL or routed in a ''routes.php'' file. This is usually the first 2 words after the base URL of a website. e.g | ||
| + | |||
| + | <code url> | ||
| + | http://example.com/Controller/method | ||
| + | </code> | ||
| + | |||
| + | Parameters follow beyond.\\ | ||
| + | |||
| + | Splint applications also need their Controllers and methods specified in the URL as well, and as such have a section in the URL to retrieve this from.\\ | ||
| + | |||
| + | Splint applications retrieve these information from the segments beyond the traditional ''Controller'' and ''Class'' segments. for example, A Splint application loaded from a ''Controller'' called ''AppTester'' under the method ''loadApp'' and requesting a ''Controller'' class of the application ''AppController'' and callint its function ''appFunction'' will have the following URL.\\ | ||
| + | |||
| + | <code url> | ||
| + | http://example.com/AppTester/loadApp/AppController/appFunction | ||
| + | </code> | ||
| + | |||
| + | The Splint AppEngine provides you with helper functions that allow you provide the right URL for pages or resources in your applications that equally considers any ''Controller'' or ''method'' the application was loaded from. so you need worry deeply about implementing this manually.\\ | ||
| + | |||
| + | Splint AppEngine also support the dynamic routing of URLs by extend/leveraging upon Code Igniter's dynamic routing systems. This means that you can add entries as you wish in the application ''routes.php'' file, However, you have to remember that the application URL segments begin after that of the application loading section. So your entries start matching URLs from there.\\ | ||
| + | |||
| + | In Code Igniter you can get the value of this segment with the below. | ||
| + | |||
| + | <code php> | ||
| + | $this->uri->segment(3); // Application segment starts from 3. | ||
| + | </code> | ||
| + | |||
| + | ===== Splint Application Architectural Design Consideration ===== | ||
| + | |||
| + | Though you can develop a Splint application package directly, a good number of your applications will likely need serious back-end components to work.\\ | ||
| + | |||
| + | It is advised to develop and deploy a separate project as a Splint package where all back end components (e.g Models, Classes) are built, then develop and deploy it's application package while adding the previously built package as a dependency in its descriptor file. | ||
| + | |||
| + | The splint package (where back-end components are built) should be built such that any vendor who looks at its documentation or source code can develop his/her own Splint application package as well. This is not compulsory, but necessary for innovative solutions to come about like a ripple effect.\\ | ||
| + | |||
| + | In summary, Back-End logic and Application logic should be separated in 2 different packages, having different names. You can append '-app' to the end of application package name. e.g. a back-end package named ''zoey/bootstrap'' can have it's application package as ''zoey-bootstrap-app'' | ||
| + | |||
| + | ===== NEXT ===== | ||
| + | |||
| + | [[app_developer/splint_app_controller_class|SplintAPPController Class]] => \\ | ||
| + | |||
| + | ===== PREVIOUS ===== | ||
| + | |||
| + | <= [[app_developer:start|Splint Application Development]]\\ | ||
| + | |||
| + | ===== Other Topics ===== | ||
| + | |||
| + | [[app_developer:application_urls|Splint Application URLS and Helper Functions]]\\ | ||
| + | [[load_splint|Load Splint Libraries]]\\ | ||
| + | [[app_developer:loading_application_resources_within_the_application|Loading Splint Application Resources]]\\ | ||