DirectoryApp User Guide - Codebasedev

###

# DirectoryApp 2017
User Guide

Demo
User Guide
Buy Now $29

This page contains instructions on how to install and set up Codebase DirectoryApp PHP Script on your hosting account.

# Requirements

- PHP 5.5+
- MySQL 5.6.* or MariaDB 10.0

# Install

1. Create a MySQL (or MariaDB) database for DirectoryApp on your web server(i.e. via cpanel);

2. Add a user with all privileges to this database you've just created;

3. Download and extract the DirectoryApp package if you haven't already;

4. Find the file `inc/config.php`, then open it with a text editor. Then edit the lines in the example below with your host, database name, user and password information;

example:

    $db_host      = 'localhost';
    $db_name      = 'YOUR_DATABASE_NAME';
    $db_user      = 'YOUR DATABASE USERNAME';
    $db_user_pass = 'USERNAME_PASSWORD';

5. Also edit this line below entering the URL where the script will be installed on your server:

    $baseurl = 'http://yoursite.com';

## Social Login Configuration - Facebook and Twitter

To allow users to sign up and login to your site using their Facebook and/or Twitter accounts you must create API keys. To create API keys, you must create an app on Facebook and on Twitter too.

Create a Facebook app

1. Go to the Facebook Developers site and login with your Facebook account;
2. then click on the "Add a new app" button and choose the option "WWW Website";
3. follow the instructions, enter your site URL, then on the bottom of the screen click on "Skip to Developer Dashboard";
4. on the Developer Dashboard, click on the link to the app you have just created to view its App ID and App secret;
5. on your app page, click on "Add Product" on the left menu, then choose "Facebook Login";
6. set "Client OAuth Login", "Web OAuth Login" and "Embedded Browser OAuth Login" all to "yes":
7. in the "Valid OAuth redirect URIs" enter, replacing `yoursite.com` with your own site:
   `http://yoursite.com/`

   If that doesn't work, try this url instead:

   `http://yoursite.com/vendor/hybridauth/hybridauth/hybridauth/?hauth_done=Facebook`
8. finally, click on "App Review" on the left menu and then switch your app to Public Mode.

Create a Twitter app

1. Go to the Twitter Apps site and login with your Twitter account;
2. then click on the "Create New App" button and enter the details requested in the form. Enter your website URL in the "Callback URL" field;
3. after submitting the form, click on the "Keys and Access Tokens" tab to view your API key/secret pair;

For v.1.04

The steps below within the yellow background are only necessary for Directory App v1.04 and below. Starting from version 1.05, the Facebook and Twitter keys are set in the admin area ("Site settings > APIs").

Now having successfully created both apps and generating valid API keys, find the file `vendor/hybridauth/hybridauth/hybridauth/config.php` and edit the lines as indicated below:

example:
replace `http://yoursite.com` with the URL where you installed the script.

    	"base_url" => "http://yoursite.com/vendor/hybridauth/hybridauth/hybridauth/",

Now edit the lines below to include your Facebook App Id and secret and also your Twitter App Key and secret.

    	"Facebook" => array(
    		"enabled" => true,
    		"keys" => array("id" => "YOUR_FACEBOOK_APP_ID", "secret" => "YOUR_FACEBOOK_SECRET"),
    		"trustForwarded" => false
    	),
    	"Twitter" => array(
    		"enabled" => true,
    		"keys" => array("key" => "YOUR_TWITTER_KEY", "secret" => "YOUR_TWITTER_SECRET"),
    		"includeEmail" => false
    	),

## Upload

- If you want to integrate DirectoryApp into the root of your domain (e.g. http://example.com/), move or upload all contents of the unzipped DirectoryApp script (excluding the DirectoryApp directory itself) into the root directory of your web server.
- If you want to have your DirectoryApp installation in its own subdirectory on your website (e.g. http://example.com/directory/), create the directory on your server and upload the contents of the unzipped DirectoryApp package to the directory via FTP.

Note: When uploading, make sure the files have appropriate permissions settings such as 644 for files and 755 for folders. Depending on your hosting account, it could be necessary to change them. Check with your host what are the required file permisions.

# Import into MySQL

After uploading all files, now it's time to populate your database.

1. Log into your web host Control Panel(i.e.: cpanel);

2. Navigate to the "Databases" section, and select "phpMyAdmin."

3. In phpMyAdmin you will see a list of your databases on the left side. Select the database you created previously.

4. Once the database you created is selected, click the "Import" tab at the top.

5. In this sub-section, a "browse" button will appear. Select this, and choose the directoryapp_VERSION.sql file on your computer and click "Go".

6. Your database now will have imported all the necessary tables to run the site.

# Initial Configuration

With the database populated and the script uploaded, it's time to set the initial configuration.

Login as admin at `http://example.com/user/login` using:

user: admin@example.com
pass: 1234

Note: replace http://example.com/ with the URL where you uploaded the script.

## Change admin's password and email

Logged in as admin, access the user dashboard at `http://example.com/user` then click on "Change Password" on the left menu. You can also access the user dashboard by clicking on the top right button labeled "Admin" and select "Dashboard".

Enter your old password `1234` and the new one to change your password.

Still in the User Dashboard, click on the "My Profile" menu link and change the default email address to an email you plan to use to manage your site.

## Admin Area

Before going live, it's necessary to configure some settings in the admin area. You can access the admin area by clicking on the top right button labeled "Admin" and select "Admin Area" while logged as Admin.

## Categories

Click on Categories. Create at least one category. In the "Icon font tag" input field you can enter the html code for an icon for this category, for example, those provided by Fontawesome: `<i class="fa fa-cog" aria-hidden="true"></i>`

On this page you can also edit and delete categories.

I have an SQL file containing about 500 categories ready to be imported into the categories table so you don't have to create categories manually. I can send you for free, just ask me. It's in english but if you want it in other language, you can use that as a starter, then just translate that and import into your database.

## Plans

In order to accept payments from users wanting to list their business on your site, you must create at least one pricing plan, even if it's a free plan. Click on Plans on the left menu. The Plans page lets you create different pricing plans to monetize your site using Paypal as the payment gateway.

Click on the "Create Plan" button. You can create 6 different plan types:

- Free: this option lets you define free listings plans. You can then limit the number of days that each business will be listed on your site(optional). After this period, the listing will not show on the listings page;
- Free featured: identical to the Free plan except that the listing will appear fixed on top before any non-featured listing;
- One time payment: This options lets you define non-recurring billing plans. You can define the number of days each listing will be live before expiring.
- One time payment featured: identical to the plan above except that the listing will appear fixed on top before any non-featured listing;
- Monthly: This is the option for monthly recurring payments.
- Monthly featured: identical to the plan above except that the listing will appear fixed on top before any non-featured listing;

## Locations

On the Locations page you can define cities, states and countries. Every business is required to inform the city where it is located so you must create at least one city.

We have a database including all the US cities. Please find the cities.sql and use phpmyadmin to import that into your 'cities' table. Contact us if you need help setting this up.

## Site Settings

On the Site Settings page, you can define some aspects that control your site's functionality. On this page, you will find 4 tabs:

- General tab
- Email tab
- APIs tab
- Payment tab

## Site Settings: General Tab

The General Tab lets you define some of the most important aspects of your site such as your site name, localization variables and other default values. Each input field display relevant information about what values are expected by the system.

## Site Settings: Email Tab

The Email Tab lets you define email related data.

## Site Settings: APIs Tab

In the APIs Tab you can define your Google Maps API key, Facebook App key and Twitter App key. The Facebook and Twitter keys are used for the social login functionality.

## Site Settings: Payment Tab

Paypal

On the Payment tab you can define all Paypal settings. The "sandbox" mode is enabled by default. When you are ready to go live, please make sure to switch the Paypal mode to "Live" if you plan to use Paypal.

It's also important to enter your own Paypal merchant id in the appropriate field, as well as other Paypal related settings displayed on this panel.

In the Notify URL field, please enter the url to the IPN handler file:

`http://yoursite.com/ipn-handler` or
`http://yoursite.com/payment_gateways/paypal.php`

Any of the files above will work because they are the same.

Stripe

Stripe settings can also be defined in the Site Settings: Payment Tab, please fill the form with your relevant Stripe details:

- Test Secret Key
- Test Publishable Key
- Live Secret Key
- Live Publishable Key
- (data-currency)
- Currency symbol
- (data-image) *optional
- (data-description) *optional

You can find your Stripe test/live keys by logging into your Stripe account, then going to the Dashboard https://dashboard.stripe.com/, click on the API menu link and it will display your API keys.

Additionally, you have to define the "webhook url" also in your Stripe account's dashboard. Click on the "webhooks" menu link on your dashboard menu, then at the top, find the "Settings" link, click on it, then click on the "Add endpoint" button and enter the URL to your Stripe webhook file which is located in:

`http://yoursite.com/payment_gateways/stripe.php`

## Email templates

On the Emails page you can edit the email templates that will be used when sending emails to your users after specific events such as the sign up email, the email sent after payment is confirmed, etc.

Click on the icon to edit each email template.

The email templates uses %placeholders% that get replaced by dynamic content. For example, the %username% placeholder will be replaced by the user's first name when the email is sent.

# Site Management

Now that you have your site up and running, it's time to learn how to manage it using the Admin Area.

## Listings

The Listings page shows all the listings submitted by users. Here you can approve, delete, promote/feature, mark as paid and edit each listing with the click of a button.

## Reviews

The Reviews page shows all the reviews submitted by users. Here you can approve and delete each listing with the click of a button. Use the Expand button to read the review text.

## Users

The Users page shows all the users registered on your site. Here you can view the email addresses of each users and also delete user accounts.

## Pages

DirectoryApp allows you to create unlimited pages such as "About Us", "Privacy Policy". In the Admin Area, click on the Pages link on the left menu. You will then see a list of all the pages that have been created. DirectoryApp ships with 2 pages already created as examples, an "About Us" page and a "Privacy Policy" page. You can edit or delete these pages if you don't plan on using them.

DirectoryApp includes a special contact page which provides form-to-mail functionality. Use/edit that page instead of creating a contact page in the Admin Area.

## Building menus with links to pages

When you create pages, you can group them using a common "Group Name". Then you can automatically show a list of links to this group of pages anywhere in your template files by using the following code:

    <?= show_menu('page_group_name'); ?>

Change `page_group_name` to the "Group Name" you entered when creating your pages. This PHP code will output a list of links `<ul>` to the pages in the same group.

## Transactions

The Transactions page shows all the transactions processed by Paypal. It logs the most relevant Paypal notifications (IPN) so that you are able to view in real time whether the payment was actually processed.

## Tools

The Tools page currently includes only one tool: "Deactivate expired listings". This tools will scan the database and deactivate expired listings. It will not delete from the database, it will just mark it as expired so that the listings will not show up to users.

# Templates

Customizing the look and feel of your DirectoryApp installation is very straighforward. All the templates that control the look and feel of your site can be found in the /templates folder. The CSS file is located in the /templates/css folder. Additionally, there is a _user_styles.css stylesheet located in the /templates/user_templates/ folder that contains styles used in the user's dashboard area.

## Front end templates

- _header.php - the footer file, contains the footer links and calls to sitewide javascript and css files;
- _header.php - header template, contains the navigation bar. Used in most pages;
- _html_head.php - this file contains meta tags, calls to css and javascript that must be put in the `<head> tag;`
- favicon.inc.php - favicon code;
- tpl_all-categories.php - this template is used to display the page `http://example.com/all-categories`
- tpl_contact.php - this template is used to display the page `http://example.com/_contact`
- tpl_index.php - this template is used to display the home page of your site
- tpl_list.php - this template is used to display the city/state/country/category/neighborhood business listings such as `http://example/us/list/auto/n-0-1-1`, that is, any page that contains /list/ in its URL;
- tpl_msg.php - this template is used to display error pages, warnings, etc.;
- tpl_page.php - this template is used to display pages created by you in the Admin Area;
- tpl_place.php - this template is used to display each business page;
- tpl_place_404.php - this template is used to display an 404 place not found page;
- tpl_profile.php - this template is used to display the user public profile page;
- tpl_searchresults.php - this template is used to display the search results page.

## User dashboard templates

These are the templates used in the user dashboard area. If you want to change the look and feel of the user dashboard area, most of the time editing just a few templates are required. These templates are:

- _user_footer.php - user dashboard footer file used in all pages;
- _user_header.php - user dashboard header file used in all pages;
- _user_menu.php - template for the user menu;
- _user_styles.php - css file for rules only used in the user dashboard area.

# Translation

All text displayed in the browser can be translated. DirectoryApp uses simple PHP files to handle translation that are very easy to edit even for users unfamiliar with PHP.

Translation files are separated by pages. This means, each translation file generally corresponds to a specific page, similar to templates.

Translation files can be found in the /translations folder and the /translations/user_translations and /translations/admin_translations folders.

To edit the translations files you need a simple text editor, like Notepad. Translations files have a simple pattern:

    $txt_var_name    = "text or phrase to be translated";
    $txt_another_var = "another text or phrase to be translated";
    $txt_yet_another = "yet another text or phrase to be translated";

A translation file contains several lines following the above pattern. You need to translate the text inside the double quotes.

Don't translate the lines that don't start with a $ sign, such as lines starting with double forward slashes `// some text...`. These are comments and don't need to be translated.
Don't translate words enclosed in % signs, such as `%place_name%`. These are placeholders that will be used by the script to replace them with variables.

# Troubleshooting

In case you try to access your site and it returns an HTTP 500 Internal Server Error, the possible causes and solutions are:

Old PHP version on your host:
DirectoryApp requires at least PHP 5.5+. If your hosting package uses an older PHP version, you may experience the 500 Internal Error.
Solution: Most hosting services allow clients to upgrade their PHP version usually through a setting on cpanel or adding some line to the .htaccess file. Please ask your host how to upgrade your PHP version.

Incompatible rules in the .htaccess file:
As of version 1.03, DirectoryApp includes alternative .htaccess files for popular hosts such as Godaddy, Dreamhost and Hostinger. For example, if you are using Godaddy, delete the .htaccess file then find the file .htaccess.godaddy and rename it to .htaccess and see if it works. Do the same for the htaccess files inside the /user and /admin folders

Wrong file permissions:
Depending on your hosting account, it may require different permissions. Something like: 644 for files and 755 for folders. Check with your host what should be the appropriate permissions;

On most web hosts, the required permission level for folders is '755' and for files is '644'. Sometimes when you upload the whole zip file and unzip it there using shell commands or other similar tools, the files and folder permissions can be set to something like '775' for folders and '664' for files causing the server to trigger HTTP 500 Internal Server errors.

To quickly change all files and folder permissions using your web host shell access you can enter these commands:

    find name_of_your_folder -type d -exec chmod 755 {} \;

    find name_of_your_folder -type f -exec chmod 644 {} \;

## MySQL Import Errors

If you experience errors while trying to import the SQL file when setting up the script, please make sure your MySQL version is at least 5.6.4

## Facebook Login Errors

Facebook recently changed their API and this requires a modification to one configuration file in DirectoryApp. Since v.1.04, this modification is included by default but if you have an earlier version of DirectoryApp, the suggested approach is to upgrade the script or download the config file here (instructions included in the zip).

# Help and Support

If you can't find a solution to your question here, support is fast and I can also help you integrate the script on your site. Don't hesitate to send an email whenever you need help at admin@codebasedev.com

# Credits

Icons made by Freepik from www.flaticon.com