Horuph is a framework that helps you create everything!

Development Requirements:

You only need minimum PHP version 7.1.3 to start developing.

Modify Apache's httpd.conf file as listed here:

You'll need to restart Apache server after these.

LoadModule rewrite_module modules/mod_rewrite.so
            

DocumentRoot "${SRVROOT}/htdocs/www"
<Directory "${SRVROOT}/htdocs/www">
            

#AllowOverride None
AllowOverride All
            

#DirectoryIndex index.html
DirectoryIndex index.php
            

Modify php.ini file as listed here:

extension=sqlite3
extension=sockets
extension=curl
extension=mbstring
extension=gd2
extension=openssl
            

Installation:

Download and Install Karen:

Karen is the command line tool for Horuph.

Download the appropriate version of Karen for your operating system.

Follow the instructions to install Karen on your system.

Install Horuph via Karen:

You can easily install Horuph with Karen. You can follow the instructions provided to install the Horuph SDK.

Permissions:

In order to read and make changes to database files, you'll need 777 permission.

Server Configuration:

Running on Linux/Apache

Running on Windows/IIS

Activating url rewriting rules on nginx server:

To activate the rewrite rules on nginx servers please change the location value like the example:

location / { try_files $uri $uri/ /index.php?$args; }
    

Directory Structure:

bin directory: This directory holds the server files.

Addon Manifest:

The first thing you need to develop our addon, is a manifest.json file. This file is the identification for your addon. It is a JSON formatted file that has properties as below:

{
    "title": "addon_title",
    "version": "1.0",
    "priority": 1,
    "toolbar": {
        "title": "addon_action_name",
        "icon": "addon_icon",
        "iconfilter": "",
        "click": "DoSomething"
    }
}
            

Addon's manifest.json example located inside core/addons/[ADDON_NAME]:

Addon Icon:

This is where you add an icon for your addon. You'll need to add your icon with these formats and names inside your addon folder:

Addon Version:

To keep a documentation on the latest changes of your addon, you'll need to make a version folder inside your addon folder. This folder contains html files with the name of your language packs; for example fa.html

Addon Publish:

You need to have a publish JSON for your addon. This JSON contains information about your addon that will be used in the publishing process.

You will also specify the requirements of your addon inside this JSON file.

{
    "description":"publish_desc",
    "developer":"John Doe",
    "url":"http://www.horuph.com",
    "requirements":[
        {"addon":"cartable", "version":"1.2.100"},
        {"addon":"users", "version":"1.1.230"}
    ]
}
            

Addon's publish.json example located inside core/addons/[ADDON_NAME]:

Addon Language:

{
    "addon_name": "نام افزونه"
}
            

fa.json example located inside core/addons/[ADDON_NAME]/languages:

Addon Public Directory:

default.phtml: If you add this file inside your public folder, every variable, method and class that is written inside this file will be available throughout the application.

Addon Pages:

All the pages in your addon that can be shown in the site, are located here.

To start using pages, first you will need to make a directory in your addon folder, named pages.

Indexing pages

{
"pages": [
    { 
        "title": "page_title", 
        "page": "default", 
        "linkable": 1 
    }
]
}
            

Meta data for pages

The next step is to add meta data for your pages. If you don't add this data, you will get a 404 error. To add meta data, add a _meta.phtml file inside your pages folder.

Here is an example of the _index.phtml file located in core/addons/[ADDON_NAME]/pages/:

{ 
"title": "YOUR_PAGE_TITLE", 
"description": "YOUR_PAGE_DESCRIPTION", 
"image": "YOUR_PAGE_THUMBNAIL_IMAGE", 
"status": YOUR_PAGE_STATUS, 
"canonical": "YOUR_PAGE_CANONICAL_URL", 
"template": "YOUR_PAGE_TEMPLATE" 
}
            

Addon Console:

You can have a custom console for your addon to manage. Your console can have multiple tabs that manage different tasks.

To have a console for your addon, first you need to make a directory named console inside core/addons/[ADDON_NAME] directory.

Then in this console directory, you need to make a file named _index.phtml. This file contains a JSON that specifies your console's tabs.

_index.phtml example located inside core/addons/[ADDON_NAME]/console:

{
    "tabs": [
            { 
                "title": "categories", 
                "page": "categories", 
                count: "categories_counter"
            }
        ]
}
            

Addon Settings:

If you need settings to apply to your addon, you can use the settings implementation of Horuph.

To have settings for your addon, create a file named settings.phtml inside your addon's console directory.

Add this settings tab inside your console's _index.phtml file.

Inside this settings file, you should create a form to give the user the ability to change the settings.

addonsettingitem=1
            

Here is an example of the config.ini file located inside data/addons/[ADDON_NAME]/:

Addon Styles:

Create a folder named styles inside your addon's directory.

Inside this folder, there are multiple types of styles that you can create:

default.phtml: The styles you put in this file are only accessible to the pages of your own addon and other addon's can't use them.

global.phtml: The styles you put in this file are accessible to all the addons.

console.phtml: The styles you put in this file affect only the console of your addon.

global_console.phtml: The styles you put in this file affect all the consoles.

print.phtml: The styles you put in this file affect the print styles of the site.

Addon Scripts:

Create a folder named scripts inside your addon's directory.

Inside this folder, there are multiple types of scripts that you can create:

default.phtml The scripts you put in this file are only accessible to the pages of your own addon and other addon's can't use them.

global.phtml The scripts you put in this file are accessible to all the addons.

console.phtml The scripts you put in this file affect only the console of your addon.

global_console.phtml The scripts you put in this file affect all the consoles.

staff.phtml The scripts you put in this file are only available to the staff of the site.

Addon AJAX:

All your AJAX pages are placed in this directory.

You can create up to one level of sub directories to better organize your AJAX pages.

These AJAX pages are accessible from [HOME_URL]/ajax/[ADDON_NAME]/[YOUR_AJAX_PAGE]

Addon WebParts:

To create webparts for your addon, first create a folder insode your addon's directory named webparts.

To index your webparts, you'll need a _index.phtml file inside your webparts directory.

{
"webparts": [
    { 
        "title": "webpart_title", 
        "page": "webpart_page" 
    }
]
}
            

Here is an example of the _index.phtml file located in core/addons/[ADDON_NAME]/webparts/:

Addon API:

Creating APIs in Horuph is very easy and straight forward.

All you need to do is create a folder inside your addon's directory with the name of "api".

Next step is to create your API files inside this directory and they all will have the appropriate headers for acting as an API.

Addon Sockets:

Addon Data:

Your databases for your addon must be placed inside a directory with the name of your addon inside the data directory.

This is the directory map that should contain your data: data/addons/[ADDON_NAME].

JavaScript Public Variables:

These variables are automatically generated and ready to use:

JavaScript Methods:

These methods are accessible to everyone:

AJAX Dialogs:

openWindowBox(windowWidth, windowTitle, windowToken)

This method is for creating an AJAX popup window.

Each window has an id that gets generated with this method.

Then you post to a page containing your AJAX page as explained in the Addon AJAX directions.

If you have any values to post you can use id, item, content or query to send your data.

Then you set the html of the box created in the first step with the data fetched from your post method.

This method takes three variables:

Here is an example of creating a window box:

function openPopupWindow(itemId) {
var windowboxid = openWindowBox(500, 'windowTitle', 'windowToken');
$.post('[HOME_URL]/ajax/[ADDON_NAME]/[AJAX_PAGE]', {
    item: itemId
}, function (data) {
    $('#' + windowboxid + 'holder').html(data);
});
}    
    

Yes No Dialogs:

openConfirmBox(windowAction, windowTitle, addonName, windowWarning): Post action

This method is for openning a popup window that is for asking a yes or no consent.

This method posts the yes action to your action.phtml page with the windowAction you specified.

If you have any values to send for your action, you can use id, item, content or query.

This method uses these variables:

Here is an example of a yes or no dialog with post action:

function openYesNoDialog(item) {
var windowboxid = openConfirmBox('boxAction', 'boxTitle', 'addonName', 'extraText');
document.getElementById(windowboxid + '_item').value = item;
}
    

openConfirmBoxScript(windowAction, windowTitle, addonName, windowWarning, actionScript): Script action

This method is for openning a popup window that is for asking a yes or no consent.

This method handles the yes action with the script you pass with the arguments.

If you have any values to send for your action, you can use id, item, content or query.

This method uses these variables:

Here is an example of a yes or no dialog with script action:

function openYesNoDialogWithScript(item) {
var windowboxid = openConfirmBoxScript('boxAction', 'boxTitle', 'addonName', 'extraText', 'DoSomething();');
document.getElementById(windowboxid + '_item').value = item;
}
function DoSomething() {
//handle your action here
}
    

Public Variables:

There are some variables in Horuph that are filled automatically and they are accessible throughout the application.

Site variables:

UserActions Class:

You can use the $userActions object to access the user data inside your project.

Here are the methods available in this object to access the user:

$userActions->userByID($userid)->userName;
$userActions->userByID($userid)->fullName;
$userActions->userByID($userid)->userMail;
$userActions->userByID($userid)->userCell;
$userActions->userByID($userid)->userImage;
$userActions->userByID($userid)->userToken;
                

$userActions->userByToken($token)->userID;
$userActions->userByToken($token)->userName;
$userActions->userByToken($token)->fullName;
$userActions->userByToken($token)->userMail;
$userActions->userByToken($token)->userCell;
$userActions->userByToken($token)->userImage;
                

$userActions->userByMail($mail)->userID;
$userActions->userByMail($mail)->userName;
$userActions->userByMail($mail)->fullName;
$userActions->userByMail($mail)->userCell;
$userActions->userByMail($mail)->userImage;
$userActions->userByMail($mail)->userToken;
                

Post and Query variables:

These variables get set automatically if passed by either query or forms.

These variables are used to pass data through out the application.

Methods:

These methods are made to ease your programming.

General Methods:

GetPackText(language_identifier, addon_name, string_token)

This method can access your language pack's texts with your token.

This method uses three variables:

URLGenerator(language_identifier, addon_name, data, id, item, content, query, alert, page)

This method generates a url string with all the data that needs to get passed through query. We use this method for calling urls in order to accommodate all the urls reffering to this page, while using url mapping techniques.

This method uses these variables:

FileUploadReady(addonName, inputName, previousValue)

This method creates input field for image upload and shows a preview of the uploaded image instead of the input field.

This method uses three variables:

FileUpload(inputName, folderName, fileType)

This method uploads file to server.

This method uses three variables:

TextMinimizer(text, length)

This method limit the string you give to the length that you specify.

This method uses these variables:

Page Redirection Methods:

Redirect(url)

This method makes redirecting pages easy.

RedirectWithAlert(alert)

This method redirects to the current page with a specified alert.

SQL Database Methods:

ExecByConnectionString(query, database_location)

This method is makes database transaction easy if you are using SQLite database.

This method uses these variables:

Cartable Addon:

This addon is for managing your cartable. You don't need to code extra pages for your console to manage your cartable anymore. Implementing this addon will do the job easily.

Here are the steps you need to work with this addon:

Add this dependency to your addon:

karen install --addon gearback/cartable
            

Add Cartable via Addon Manager:

You can add this dependency with the addon manager in your site:

• First open addons from the top administration bar by clicking on the apps icon.
• Next click on the extension icon at the bottom of window to add new addons.
• In the addons page, click on install addon button on top.
• Search for cartable and click on install on the found item.
• Agree to the addon terms and click install.

Add cartable to your addon's console:

Create a folder inside your addon's console in core, named "cartable".

Add a file named _index.phtml in this cartable directroy.

This file should contain a JSON formatted text to identify your cartable pages.

The fields of this JSON are listed here:

page This field contains the name of the page that must be shown for each cartable item. This page is located inside your console's cartable directory, inside a folder named forms.

The final location of this page is: core/addons/[ADDON NAME]/console/cartable/forms/[PAGE].phtml

title This field contains the name of your cartable.

description This field contains the description for your cartable.

user_related This field contains either 0 or 1. Pass a value of 1 if you want to show the user that submitted this cartable item on top.

alert This field contains a dynamically produced integer to show the count of cartable items that need verification.

database This object contains information on your database and the query to show the cartable items.

Here are listed the information for this field:

type This field contains the type of your database file, like sqlserver, sqlite or mysql.

name This field contains the name of your database file that is located inside your addon's data directory.

auth You only need to add this field if you are using SQL Server.

This field contains auth array of your SQL server authentication.

It is recommended to keep your authentication array in a PHP variable inside your addon's public folder, in default.phtml.

queries In this field you'll need to specify the queries that the addon needs to list and search your database for data that needs verification.

For the search query, use [searchquery] for finding the result.

Here is an example of the _index.phtml file located in core/addons/[ADDON NAME]/console/cartable/:

{
"cartables": [
        { 
            "page": "cartable_page",
            "title": "cartable_page_title", 
            "description": "cartable_page_description", 
            "user_related": 1, 
            "database": { 
                "type": "sqlserver", 
                "name": "db.db3",
                "auth": <?php echo(json_encode($db_auth_array)); ?>,
                "queries": {
                    "list": "SELECT ID,name FROM table_name WHERE isvalid = 0 ORDER BY ID",
                    "search": "SELECT ID,name FROM table_name WHERE (name || desc) LIKE [searchquery] ORDER BY ID"
                    } 
                },
            "alert": <?php echo(ReadFirstRecordByConnectionString("SELECT COUNT(*) FROM table_name WHERE isvalid = 0", "addons/addon_name/db.db3")); ?>
        }
    ]
}
    

Report Addon:

This addon is for managing your reports. You don't need to code extra pages for the report function throughout you application anymore. Implementing this addon will do the job easily.

Here are the steps you need to work with this addon:

Add this dependency to your addon:

karen install --addon gearback/reports
            

Add Cartable via Addon Manager:

You can add this dependency with the addon manager in your site:

• First open addons from the top administration bar by clicking on the apps icon.
• Next click on the extension icon at the bottom of window to add new addons.
• In the addons page, click on install addon button on top.
• Search for reports and click on install on the found item.
• Agree to the addon terms and click install.

Add report to your addon's console:

Create a folder inside your addon's console in core, named "reports".

Add a file named _index.phtml in this reports directroy.

This file should contain a JSON formatted text to identify your report items.

The fields of this JSON are listed here:

form This field contains the name of the form that must be shown for each report item. This page is located inside your console's reports directory, inside a folder named forms.

The final location of this page is: core/addons/[ADDON NAME]/console/reports/forms/[PAGE].phtml

warning This field contains either false or true. Pass a value of false if you don't want to send waring to the reported user.

callquery This field contains a string value that is the query to show the reported item. This item is reachable with a token name [appparameter].

calldb This field contains the type of your database file, like sqlserver, sqlite or mysql.

Here is an example of the _index.phtml file located in core/addons/[ADDON NAME]/console/reports/:

{
    "reports": [
        { "form": "reportFormName", "warning": ture, "callquery": "SELECT name FROM table_name WHERE token = '[appparameter]'", "calldb": "sqlite" }
    ]
}

Write report reasons in your report console:

Next, navigate to your site and open addons by clicking on apps in the administeration toolbar.

Click on the reports console.

You will see a list of the report types you created in the previous step.

Click on report options to add and edit the report details for your data.

Add the report button in your code:

Where ever you may need a report button for your data, you can use it like this example:

<a class="hrphreportbt" data-parameter="<?php echo($_content); ?>" data-app="addon_name" data-report="report_form" data-title="report_title">Report</a>

Here are the data used in this report button:

Form Requirements:

This is an example of using Horuph tools to create required inputs in your forms:

Each input that is required in your form must have a class named req-min.

The next and only step to make handle these necessary inputs, is to call validateForm method in the script of your page that checks the required inputs on the submit button click.

Here is an example of an HTML page containing a form with required fields:

<form class="form" id="formId" method="POST">
<div class="he-table he-w-100">
    <div class="he-row">
        <div class="he-cell-text"><?php echo(GetPackText($langShort, "title")); ?>:</div>
        <div class="he-cell-input">
            <input name="name" type="text" class="he-w-100 req-min" minlength="3" maxlength="100">
        </div>
    </div>
    <div class="he-row">
        <div class="he-cell-text"><?php echo(GetPackText($langShort, "question", "featurerating")); ?>:</div>
        <div class="he-cell-input">
            <input name="address" type="text" class="he-w-100 req-min" minlength="3" maxlength="200">
        </div>
    </div>
</div>
<div class="he-form-buttons">
    <input id="formSubmitBtn" type="submit" value="Submit" class="he-button" />
</div>
</form>
<script type="text/javascript">$(function () { validateForm('formId', 'formSubmitBtn'); });</script>    
    

* Please make sure that you specify minlength and maxlength in your input tag.

These are the variables used in this example that you need to change according to your addon:

This is the class used for identifying the required inputs:

This is the method used for validating the form on submit:

validateForm(formId, formSubmitButtonId)

This method takes these variables:

Uploading Images:

This is a complete example of how to upload images with the help of horuph functions.

All you need to do is call a PHP method that will create the file input and handle the preview of the uploaded image.

These methods will automatically manage your upload process.

This process consists of uploading the image to server, showing the image thumbnail if previously uploaded instead of the upload button and a remove button next to the thumbnail image to remove the uploaded image.

Here are the steps needed for uploading images:

• Input field name:

  First you need to choose a name for your input type file.

• PHP variable to hold your image source:

  Then you need a PHP variable that points to the uploaded image location. This variable is empty in case there was no image uploaded previously.

• Prepare input field:

  Just call the FileUploadReady method to prepare your input and preview handling.

• Handle uploading to server in your action file:

  The last step is to upload the image to server using FileUpload method in your submit action.

Here is an example of file upload HTML structure:

//your html file
<div class="he-row">
    <div class="he-cell-text">Icon:</div>
    <div class="he-cell-input">
        <?php FileUploadReady("addonName", "appicon", $appicon); ?>
    </div>
</div>

//your server side
$appicon = FileUpload("appicon", "addonName", "image");
    

Resizing Images:

Horuph has a wonderful tool for resizing and cropping images that makes your coding easier and faster.

To resize your image, all you need to do is use this URL structure with your uploaded image location:

[homeUrl] / img / [maxWidth]X[maxHeight]_[resizeType] / [addon][imagePath]

Here are the variables that need to change:

Here is an example of a URL to resize the image:

<img src="<?php echo($homeUrl); ?>/img/100x100_crop/addonName/<?php echo($imagePath); ?>">
    

Version Structure:

For the best practice, we recommend using this structure for your addon versioning.

By using this format, Horuph can better handle your updates and requirements.

An example for the prefered addon versioning is 2.5.100

Addon versioning in Horuph consists of three parts. Here is the structure:

VERSION_NUMBER . SUB_VERSION_NUMBER . BUILD_NUMBER

Version number The version number can be any number you desire.

Sub version number The sub version number must be a one digit number.

Build number The build number must be a three digit number.

Getting your addon ready for publishing

Publishing your addons is very easy and is done in only a few steps.

• Pack your addon:

  Packing your addon is done via karen in your terminal.

  You can see the command to pack your addon in the Karen's Pack Tutorial.

• Complete your addon detail:

  After you pack your extension, open the zip file that was extracted.

  There is a languages folder inside your addon's directory in the packed folder.

  Inside this languages folder, there are two automatically generated JSONs for Farsi and English that contain the publishing details for your addon.

  If you need to change these texts or add more languages for your publishing details, you can do it here.

• Change the terms for your addon:

  In the same folder as your languages, there is another folder named terms in your addon's packed folder.

  Inside this terms folder, there are two automatically generated HTML files for Farsi and English that contain the terms of publishing for your addon.

  If you need to change these html files or add more languages for your publishing terms, you can do it here.