<html><head><title>Nile</title>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" >
</head>
<body class='pod'>
<!--
generated by Pod::Simple::HTML v3.28,
using Pod::Simple::PullParser v3.28,
under Perl v5.016003 at Sun Jul 13 15:19:39 2014 GMT.
If you want to change this HTML document, you probably shouldn't do that
by changing it directly. Instead, see about changing the calling options
to Pod::Simple::HTML, and/or subclassing Pod::Simple::HTML,
then reconverting this document from the Pod source.
When in doubt, email the author of Pod::Simple::HTML for advice.
See 'perldoc Pod::Simple::HTML' for more info.
-->
<!-- start doc -->
<a name='___top' class='dummyTopAnchor' ></a>
<h1><a class='u'
name="NAME"
>NAME</a></h1>
<p>Nile - Visual Web App Framework Separating Code From Design Multi Lingual And Multi Theme.</p>
<h1><a class='u'
name="SYNOPSIS"
>SYNOPSIS</a></h1>
<pre> #!/usr/bin/perl
use Nile;
my $app = Nile->new;
$app->init(
#base application path, auto detected if not set
#path => dirname(File::Spec->rel2abs(__FILE__)),
#site language for user, auto detected if not set
#lang => "en-US"
#theme used
#theme => "default"
);
#handle request and send response
$app->run;</pre>
<h1><a class='u'
name="DESCRIPTION"
>DESCRIPTION</a></h1>
<p>Nile - Visual Web App Framework Separating Code From Design Multi Lingual And Multi Theme.</p>
<p><b>Alpha</b> version, do not use it for production. The project's homepage <a href="https://github.com/mewsoft/Nile" class="podlinkurl"
>https://github.com/mewsoft/Nile</a>.</p>
<p>The main idea in this framework is to separate all the html design and layout from programming. The framework uses html templates for the design with special xml tags for inserting the dynamic output into the templates. All the application text is separated in langauge files in xml format supporting multi lingual applications with easy traslating and modifying all the text.</p>
<pre> #!/usr/bin/perl
use Nile;
my $app = Nile->new;
$app->init(
#base application path, auto detected if not set
#path => dirname(File::Spec->rel2abs(__FILE__)),
#site language for user, auto detected if not set
#lang => "en-US"
#theme used
#theme => "default"
);
#handle request and send response
#$app->run;
# control everything manually
my $request = $app->request;
# load global shared application configuration file
$app->config->load($app->file->catfile($app->var->get("config_dir"), "config"));
say $app->config->get("database/user");
# connect to the database. pass the connection params or try to load it from the config object.
#$app->connect();
#$app->connect(%params);
# set or get some global shared application variables
#my $var = $app->var;
#$var->Body("Body variable"); # use auto getter and setter methods
#say "Title: ". $var->set("Title", "Hello world Title")->get("Title");
# load langauge file general.xml
$app->lang->load("general");
# load routes file route.xml
$self->router->load("route");
# run the application and show the content.
$self->dispatcher->dispatch;
# you can run any plugin or route
#$self->dispatcher->dispatch('/accounts/register/create');
#$self->dispatcher->dispatch('/accounts/register/create', 'POST');</pre>
<h1><a class='u'
name="EXAMPLE_APPLICATION"
>EXAMPLE APPLICATION</a></h1>
<p>Download and uncompress the module file. You will find an example application folder named <b>app</b>.</p>
<h1><a class='u'
name="URLs"
>URLs</a></h1>
<p>This framework support SEO friendly url's, routing specific urls and short urls to actions.</p>
<p>The url routing system works in the following formats:</p>
<pre> http://domain.com/plugin/controller/action # mapped from route file or to Plugin/Controller/action
http://domain.com/plugin/action # mapped from route file or to Plugin/Plugin/action or Plugin/Plugin/index
http://domain.com/plugin # mapped from route file or to Plugin/Plugin/plugin or Plugin/Plugin/index
http://domain.com/index.cgi?action=plugin/controller/action
http://domain.com/?action=plugin/controller/action
http://domain.com/blog/2014/11/28 # route mapped from route file and args passed as request params</pre>
<p>The following urls formats are all the same and all are mapped to the route Home/Home/index or Home/Home/home (Plugin/Controller/Action):</p>
<pre> # direct cgi call, you can use action=home, route=home, or cmd=home
http://domain.com/index.cgi?action=home
# using .htaccess to redirect to index.cgi
http://domain.com/?action=home
# SEO url using with .htaccess. route is auto detected from url.
http://domain.com/home</pre>
<h1><a class='u'
name="APPLICATION_DIRECTORY_STRUCTURE"
>APPLICATION DIRECTORY STRUCTURE</a></h1>
<p>Applications built with this framework must have basic folder structure. Applications may have any additional directories.</p>
<p>The following is the basic application folder tree that must be created manually before runing:</p>
<pre> ├───config
├───lang
│ └───en-US
├───lib
│ └───Nile
│ └───Plugin
│ └───Home
├───log
├───route
└───theme
└───default
├───image
├───view
└───widget</pre>
<h1><a class='u'
name="CREATING_YOUR_FIRST_PLUGIN_'HOME'"
>CREATING YOUR FIRST PLUGIN 'HOME'</a></h1>
<p>To create your first plugin called Home for your site home page, create a folder called <b>Home</b> in your application path <code>/path/lib/Nile/Plugin/Home</code>, then create the plugin Controller file say <b>Home.pm</b> and put the following code:</p>
<pre> package Nile::Plugin::Home::Home;
use Nile::Base;
sub home : GET Action {
my ($self) = @_;
my $view = $self->me->view("home");
$view->var(
fname => 'Ahmed',
lname => 'Elsheshtawy',
email => 'sales@mewsoft.com',
website => 'http://www.mewsoft.com',
singleline => 'Single line variable <b>Good</b>',
multiline => 'Multi line variable <b>Nice</b>',
);
$view->process;
$view->render;
}
1;</pre>
<h1><a class='u'
name="YOUR_FIRST_VIEW_'home'"
>YOUR FIRST VIEW 'home'</a></h1>
<p>Create an html file name it as <b>home.html</b>, put it in the default theme folder <b>/path/theme/default/views</b> and put in this file the following code:</p>
<pre> <vars type="widget" name="header" charset_name="UTF-8" lang_name="en" />
{first_name} <vars name="fname"/>
{last_name} <vars name="lname" />
{email} <vars type="var" name='email' />
{website} <vars type="var" name="website" />
{date_now} <vars type="plugin" name="Date::Date->date" format="%Y %M %D" />
{time_now} <vars type="plugin" name="Date->now" format="%M %Y %D" />
{date_time} <vars type="plugin" name="date" format="%M %Y %D" />
Version: <vars type="perl"><![CDATA[print $self->me->VERSION; return;]]></vars>
<vars type="perl">system ('dir c:\\*.bat');</vars>
<vars type="var" name="singleline" width="400px" height="300px" content="ahmed<b>class/subclass">
cdata start here is may have html tags and 'single' and "double" qoutes
</vars>
<vars type="var" name="multiline" width="400px" height="300px"><![CDATA[
cdata start here is may have html tags <b>hello</b> and 'single' and "double" qoutes
another cdata line
]]></vars>
<!--block:first-->
<table border="1" style="color:red;">
<tr class="lines">
<td align="left" valign="<--valign-->">
<b>bold</b><a href="http://www.mewsoft.com">mewsoft</a>
<!--hello--> <--again--><!--world-->
some html content here 1 top
<!--block:second-->
some html content here 2 top
<!--block:third-->
some html content here 3 top
<!--block:fourth-->
some html content here 4 top
<!--block:fifth-->
some html content here 5a
some html content here 5b
<!--endblock-->
<!--endblock-->
some html content here 3a
some html content here 3b
<!--endblock-->
some html content here 2 bottom
</tr>
<!--endblock-->
some html content here 1 bottom
</table>
<!--endblock-->
some html content here1-5 bottom base
<vars type="widget" name="footer" title="cairo" lang="ar" /></pre>
<h1><a class='u'
name="YOUR_FIRST_WIDGETS_'header'_AND_'footer'"
>YOUR FIRST WIDGETS 'header' AND 'footer'</a></h1>
<p>The framework supports widgets, widgets are small views that can be repeated in many views for easy layout and design. For example, you could make the site header template as a widget called <b>header</b> and the site footer template as a widget called <b>footer</b> and just put the required xml special tag for these widgets in all the <b>Views</b> you want. Widgets files are html files located in the theme <b>'widget'</b> folder</p>
<p>Example widget <b>header.html</b></p>
<pre> <!doctype html>
<html lang="[:lang_name:]">
<head>
<meta http-equiv="content-type" content="text/html; charset=[:charset_name:]" />
<title>{page_title}</title>
<meta name="Keywords" content="{meta_keywords}" />
<meta name="Description" content="{meta_description}" />
</head>
<body></pre>
<p>Example widget <b>footer.html</b></p>
<pre> </body>
</html></pre>
<p>then all you need to include the widget in the view is to insert these tags:</p>
<pre> <vars type="widget" name="header" charset_name="UTF-8" lang_name="en" />
<vars type="widget" name="footer" /></pre>
<p>You can pass args to the widget like <b>charset_name</b> and <b>lang_name</b> to the widget above and will be replaced with their values.</p>
<h1><a class='u'
name="LANGUAGES"
>LANGUAGES</a></h1>
<p>All application text is located in text files in xml format. Each language supported should be put under a folder named with the iso name of the langauge under the folder path/lang.</p>
<p>Example langauge file <b>'general.xml'</b>:</p>
<pre> <?xml version="1.0" encoding="UTF-8" ?>
<site_name>Site Name</site_name>
<home>Home</home>
<register>Register</register>
<contact>Contact</contact>
<about>About</about>
<copyright>Copyright</copyright>
<privacy>Privacy</privacy>
<page_title>Create New Account</page_title>
<first_name>First name:</first_name>
<middle_name>Middle name:</middle_name>
<last_name>Last name:</last_name>
<full_name>Full name:</full_name>
<email>Email:</email>
<job>Job title:</job>
<website>Website:</website>
<agree>Agree:</agree>
<company>Email:</company></pre>
<h1><a class='u'
name="Routing"
>Routing</a></h1>
<p>The framework supports url routing, route specific short name actions like 'register' to specific plugins like Accounts/Register/create.</p>
<p>Below is <b>route.xml</b> file example should be created under the path/route folder.</p>
<pre> <?xml version="1.0" encoding="UTF-8" ?>
<register route="register" action="Accounts/Register/register" method="get" defaults="year=1900|month=1|day=23" />
<post route="blog/post/{cid:\d+}/{id:\d+}" action="Blog/Article/Post" method="post" />
<browse route="blog/{id:\d+}" action="Blog/Article/Browse" method="get" />
<view route="blog/view/{id:\d+}" action="Blog/Article/View" method="get" />
<edit route="blog/edit/{id:\d+}" action="Blog/Article/Edit" method="get" /></pre>
<h1><a class='u'
name="CONFIG"
>CONFIG</a></h1>
<p>The framework supports loading and working with config files in xml formate located in the folder 'config'.</p>
<p>Example config file path/config/config.xml:</p>
<pre> <?xml version="1.0" encoding="UTF-8" ?>
<admin>
<user>admin_user</user>
<password>admin_pass</password>
</admin>
<database>
<driver>mysql</driver>
<host>localhost</host>
<dsn></dsn>
<port>3306</port>
<name>blog</name>
<user>blog</user>
<pass>pass1234</pass>
<attribute>
</attribute>
<encoding>utf8</encoding>
</database></pre>
<h1><a class='u'
name="APPLICATION_INSTANCE_SHARED_DATA"
>APPLICATION INSTANCE SHARED DATA</a></h1>
<p>The framework is fully Object-oriented to allow multiple separate instances, we use the shared <b>var</b> method on the main object to access all application shared data. The plugin modules files will have the following features.</p>
<p>Moose enabled Strict and Warnings enabled. a Moose attribute called 'me' or 'nile' injected in the same plugin class holds the application singleton instance to access all the shared data and methods.</p>
<p>you will be able to access from the plugin class the shared vars as:</p>
<pre> $self->me->var->get("lang");</pre>
<p>you also can use auto getter/setter</p>
<pre> $self->me->var->lang;</pre>
<h1><a class='u'
name="URL_REWRITE_.htaccess"
>URL REWRITE .htaccess</a></h1>
<p>To hide the script name <b>index.cgi</b> from the url and allow nice SEO url routing, you need to turn on url rewrite on your web server and have .htaccess file in the application folder with the index.cgi.</p>
<p>Below is a sample .htaccess which redirects all requests to index.cgi file.</p>
<pre> # Don't show directory listings for URLs which map to a directory.
Options -Indexes -MultiViews
# Follow symbolic links in this directory.
Options +FollowSymLinks
#Note that AllowOverride Options and AllowOverride FileInfo must both be in effect for these directives to have any effect,
#i.e. AllowOverride All in httpd.conf
Options +ExecCGI
AddHandler cgi-script cgi pl
# Set the default handler.
DirectoryIndex index.cgi index.html index.shtml
# save this file as UTF-8 and enable the next line for utf contents
#AddDefaultCharset UTF-8
# REQUIRED: requires mod_rewrite to be enabled in Apache.
# Please check that, if you get an "Internal Server Error".
RewriteEngine On
#=========================================================#
# force use www with http and https so http://domain.com redirect to http://www.domain.com
#add www with https support - you have to put this in .htaccess file in the site root folder
# skip local host
RewriteCond %{HTTP_HOST} !^localhost
# skip IP addresses
RewriteCond %{HTTP_HOST} ^([a-z.]+)$ [NC]
RewriteCond %{HTTP_HOST} !^www\.
RewriteCond %{HTTPS}s ^on(s)|''
RewriteRule ^ http%1://www.%{HTTP_HOST}%{REQUEST_URI} [L,R=301]
#=========================================================#
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond %{REQUEST_URI} !=/favicon.ico
RewriteRule ^(.*)$ index.cgi [L,QSA]</pre>
<h1><a class='u'
name="REQUEST"
>REQUEST</a></h1>
<p>The http request is available as a shared object extending the <a href="http://search.cpan.org/perldoc?CGI%3A%3ASimple" class="podlinkpod"
>CGI::Simple</a> module. This means that all methods supported by <a href="http://search.cpan.org/perldoc?CGI%3A%3ASimple" class="podlinkpod"
>CGI::Simple</a> is available with the additions of these few methods:</p>
<pre> is_ajax
is_post
is_get
is_head
is_put
is_delete
is_patch</pre>
<p>You access the request object by $self->me->request.</p>
<h1><a class='u'
name="ERRORS,_WARNINGS,_ABORTING"
>ERRORS, WARNINGS, ABORTING</a></h1>
<p>To abort the application at anytime with optional message and stacktrace, call the method:</p>
<pre> $self->me->abort("application error, can not find file required");</pre>
<p>For fatal errors with custom error message</p>
<pre> $self->me->error("error message");</pre>
<p>For fatal errors with custom error message and full starcktrace</p>
<pre> $self->me->errors("error message");</pre>
<p>For displaying warning message</p>
<pre> $self->me->warning("warning message");</pre>
<h1><a class='u'
name="LOGS"
>LOGS</a></h1>
<p>The framework supports a log object which is a <a href="http://search.cpan.org/perldoc?Log%3A%3ATiny" class="podlinkpod"
>Log::Tiny</a> object which supports unlimited log categories, so simply you can do this:</p>
<pre> $self->me->log->info("application run start");
$self->me->log->DEBUG("application run start");
$self->me->log->ERROR("application run start");
$self->me->log->INFO("application run start");
$self->me->log->ANYTHING("application run start");</pre>
<h1><a class='u'
name="FILE"
>FILE</a></h1>
<p>The file object provides tools for reading files, folders, and most of the functions in the modules <a href="http://search.cpan.org/perldoc?File%3A%3ASpec" class="podlinkpod"
>File::Spec</a> and <a href="http://search.cpan.org/perldoc?File%3A%3ABasename" class="podlinkpod"
>File::Basename</a>.</p>
<p>to get file content as single string or array of strings:</p>
<pre> $content = $self->me->file->get($file);
@lines = $self->me->file->get($file);</pre>
<p>supports options same as <a href="http://search.cpan.org/perldoc?File%3A%3ASlurp" class="podlinkpod"
>File::Slurp</a>.</p>
<p>To get list of files in a specific folder:</p>
<pre> #files($dir, $match, $relative)
@files = $self->me->file->files("c:/apache/htdocs/nile/", "*.pm, *.cgi");
#files_tree($dir, $match, $relative, $depth)
@files = $self->me->file->files_tree("c:/apache/htdocs/nile/", "*.pm, *.cgi");
#folders($dir, $match, $relative)
@folders = $self->file->folders("c:/apache/htdocs/nile/", "", 1);
#folders_tree($dir, $match, $relative, $depth)
@folders = $self->file->#folders_tree("c:/apache/htdocs/nile/", "", 1);</pre>
<h1><a class='u'
name="XML"
>XML</a></h1>
<p>Loads xml files into hash tree using <a href="http://search.cpan.org/perldoc?XML%3A%3ATreePP" class="podlinkpod"
>XML::TreePP</a></p>
<pre> $xml = $self->me->xml->load("configs.xml");</pre>
<h1><a class='u'
name="DATABASE"
>DATABASE</a></h1>
<p>The database class provides methods for connecting to the sql database and easy methods for sql operations.</p>
<h2><a class='u'
name="Sub_Modules"
>Sub Modules</a></h2>
<p>Views <a href="http://search.cpan.org/perldoc?Nile%3A%3AView" class="podlinkpod"
>Nile::View</a>.</p>
<p>Shared Vars <a href="http://search.cpan.org/perldoc?Nile%3A%3AVar" class="podlinkpod"
>Nile::Var</a>.</p>
<p>Langauge <a href="http://search.cpan.org/perldoc?Nile%3A%3ALang" class="podlinkpod"
>Nile::Lang</a>.</p>
<p>Http Request <a href="http://search.cpan.org/perldoc?Nile%3A%3ARequest" class="podlinkpod"
>Nile::Request</a>.</p>
<p>Dispatcher <a href="http://search.cpan.org/perldoc?Nile%3A%3ADispatcher" class="podlinkpod"
>Nile::Dispatcher</a>.</p>
<p>Router <a href="http://search.cpan.org/perldoc?Nile%3A%3ARouter" class="podlinkpod"
>Nile::Router</a>.</p>
<p>File Utils <a href="http://search.cpan.org/perldoc?Nile%3A%3AFile" class="podlinkpod"
>Nile::File</a>.</p>
<p>Paginatation <a href="http://search.cpan.org/perldoc?Nile%3A%3APaginate" class="podlinkpod"
>Nile::Paginate</a>.</p>
<p>Database <a href="http://search.cpan.org/perldoc?Nile%3A%3ADatabase" class="podlinkpod"
>Nile::Database</a>.</p>
<p>XML <a href="http://search.cpan.org/perldoc?Nile%3A%3AXML" class="podlinkpod"
>Nile::XML</a>.</p>
<p>Settings <a href="http://search.cpan.org/perldoc?Nile%3A%3ASettingNile%3A%3ASetting" class="podlinkpod"
>Nile::SettingNile::Setting</a>.</p>
<p>Abort <a href="http://search.cpan.org/perldoc?Nile%3A%3AAbort" class="podlinkpod"
>Nile::Abort</a>.</p>
<h1><a class='u'
name="Bugs"
>Bugs</a></h1>
<p>This project is available on github at <a href="https://github.com/mewsoft/Nile" class="podlinkurl"
>https://github.com/mewsoft/Nile</a>.</p>
<h1><a class='u'
name="HOMEPAGE"
>HOMEPAGE</a></h1>
<p>Please visit the project's homepage at <a href="https://metacpan.org/release/Nile" class="podlinkurl"
>https://metacpan.org/release/Nile</a>.</p>
<h1><a class='u'
name="SOURCE"
>SOURCE</a></h1>
<p>Source repository is at <a href="https://github.com/mewsoft/Nile" class="podlinkurl"
>https://github.com/mewsoft/Nile</a>.</p>
<h1><a class='u'
name="AUTHOR"
>AUTHOR</a></h1>
<p>Ahmed Amin Elsheshtawy, احمد امين الششتاوى <mewsoft@cpan.org> Website: http://www.mewsoft.com</p>
<h1><a class='u'
name="COPYRIGHT_AND_LICENSE"
>COPYRIGHT AND LICENSE</a></h1>
<p>Copyright (C) 2014-2015 by Dr. Ahmed Amin Elsheshtawy mewsoft@cpan.org, support@mewsoft.com, <a href="https://github.com/mewsoft/Nile" class="podlinkurl"
>https://github.com/mewsoft/Nile</a>, <a href="http://www.mewsoft.com" class="podlinkurl"
>http://www.mewsoft.com</a></p>
<p>This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.</p>
<!-- end doc -->
</body></html>