Requirements

  • PHP 5.5+
  • MySQL 5.6+ or MariaDB 10.0+

Install

Follow the steps bellow to instal Directory Plus on your site.

1. Prepare

1. Create a MySQL database for Directory Plus on your web server

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

3. Download and extract the Directory Plus package if you haven't already

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


$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';

					

2. Upload

  • If you want to integrate Directory Plus into the root of your domain (e.g. http://example.com/), move or upload all contents of the unzipped Directory Plus script (excluding the Directory Plus directory itself) into the root directory of your web server.
  • If you want to have your Directory Plus 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 Directory Plus package to the directory via FTP.

Note: When uploading, make sure the files have appropriate permissions, usually 644 for files and 755 for folders. Depending on your hosting account, it could be necessary to change these values.

3a. Run install script

Go to http://example.com/install.php and enter your email and a password. This credential will be used to access the admin area later on. Click the "install" button and wait a few seconds (could take about 1 minute). This will install the databases on your MySQL server.

3b. Manual Install (optional)

If for some reason you prefer to manually install Directory Plus, instead of running the install script in step 3a., you can just import the directoryplus_VERSION.sql file into your database and the installation is done. Please note that if you choose the manual install, the initial credentials to access the admin area are:

user: admin@example.com
pass: 1234

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/sign-in

Change admin's password and email

If you manually installed Directory Plus, you may want to change the default email and password. To change your password, click on the User button at the top right and then Dashboard in the drop down menu. In the dashboard area, find the Change Password menu item on the left.

Enter your old password 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 on the left sidebar. 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="fas fa-icon" aria-hidden="true"></i>

On this page you can also edit and delete categories.

Plans

In order to accept payments from users wanting to list their items 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 or Stripe as the payment gateway.

Click on the Create Plan button. You can create unlimited plans of 6 different plan types:

  • Free: this option lets you define free listings plans. You can then limit the number of days that each item 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;
  • Annual: This is the option for annual recurring payments.
  • Annual 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 and you must create at least one city.

Check in the 'sql' folder if you find cities_xx_export.sql where 'xx' represents your country code and use phpmyadmin to import that into your database tables so you don't have to manually enter all cities/states/provinces/countries yourself. Contact me for cities for other countries, I can generate a sql file with cities for several countries.

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 default values for settings used by Directory Plus. Each field is self-explanatory, but if you need more clarification, please contact me.

Map Providers

Directory Plus allows you to choose between a few map providers: Mapbox, OpenStreetMap, Wikimedia, TomTom, HERE and Google Maps. Google Maps is not recommended since June 2018 when its free usage limit was reduced from 750,000 map views a month to only 28,000 map views a month (less than 1,000 map views a day). Google also requires a credit card to access their API. Other map providers also have free usage limits. Please check with each one what are their limits.

You can select multiple map providers. In this case, on every page load where there is a map, a random provider will be selected and used by Directory Plus.

Mapbox, TomTom, HERE and Google Maps all require API keys which you can enter in the "Site Settings" > APIs tab.

Note: If you decide to use TomTom as your map provider, you need to download the "Maps SDK for Web with vector maps" on https://developer.tomtom.com/maps-sdk-web/ and extract it into the 'lib/sdk-tomtom' folder of Directory Plus. (please create the 'sdk-tomtom' folder in this case).

Site Settings: Email Tab

The Email Tab lets you define your SMTP credentials and server. Please note that if you want to use SSL/TLS secure emails you need to include 'tls://' in the SMTP server field, for example 'tls://smtp.gmail.com'.

Site Settings: APIs Tab

In the APIs Tab you can define all API keys that you intend to use. The Facebook and Twitter APIs are used for the social login functionality. Then you have the APIs keys used for some of the map providers. Finally, you can also find in this section the field to define your Disqus integration shortname.

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.

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 "Developers" and then 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 pencil 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.

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 (Reviewed on March 2018)

  1. Go to the developers.facebook.com/apps site and login with your Facebook account;
  2. Click on the "Add a New App" button:



  3. Enter a display name for you app and then click "Create App ID":



  4. On the "Add a Product" page, choose the product "Facebook Login":



  5. Next, choose "WWW Web" as the platform for your app:



  6. Next, under "1. Tell Us about Your Website", enter your site URL in the appropriate input field, click "Save" and "Continue":



  7. Ignore the rest of the settings on this screen (Set Up the Facebook SDK for Javascript, etc), then click on PRODUCTS > Facebook Login > Settings on the left menu and enter the correct urls in Valid OAuth redirect URIs field. Make sure to enter both https and non-https versions. Also check the image below which options should be enabled or disabled. If you cannot toggle an option, make sure you have first entered your install URL in the Valid OAuth redirect URIs and click "Save Changes". The Valid OAuth redirect URIs field should contain
    https://yoursite.com/vendor/hybridauth/hybridauth/hybridauth/?hauth_done=Facebook Replace yoursite.com with the URL where you installed Directory Plus.



  8. Finally, click on "App Review" on the left menu and then switch your app to Public Mode.



  9. To view and copy your API key/secret pair, go to "Settings" > "Basic":



  10. Then paste the API key/secret pair in the appropriate fields on the Directory Plus Admin Dashboard under "Site Settings" > "APIs" tab.

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 https://YOURSITE/vendor/hybridauth/hybridauth/hybridauth/ in the "Callback URL" field (please also adjust http/https to match your use case);
  3. after submitting the form, click on the "Keys and Access Tokens" tab to view your API key/secret pair;

GDPR

To enable GDPR tools, you need to edit the file located in 'inc/my.functions.php'. Open the file in a text editor and find the variable $cfg_gdpr_on. By default it is set to false. To enable it, set the value to true:


$cfg_gdpr_on = true;

By enabling this feature, a link will be visible in the user's dashboard where he can download a JSON file containing all personal data.

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

Directory Plus 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. Directory Plus 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.

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.

my.functions.php Configuration

You can configure additional functionality editing the my.functions.php file located inside the inc/ folder. These are basically settings that haven't been implemented in the admin area but are planned to be included in the future.

Please take a look at the file to find out what features you can control using this file.

When upgrading your site, keep your custom my.config.php file and don't use the one in the upgrade files if you want to keep your settings.

Templates

Directory Plus uses a very simple structure for templates that makes it easier to customize the look and feel of your installation. The default template for Directory Plus uses the Bootstrap 4 framework extensively with very few custom styles. This makes it easier for other designers to understand the site layout.

All the templates that control the look and feel of your site can be found in the /templates folder. The CSS file (styles.css) is located in the /templates/css folder.

Front end templates

  • footer.php - the footer file, contains the footer links and calls to sitewide javascript and css files
  • header.php - header template, contains the navigation bar
  • head.php - this file contains meta tags, calls to css and javascript, it is included withing the <head> tag of all pages
  • tpl-categories.php - this template is used to display the page http://example.com/categories
  • tpl-claim.php - this template is used to display the page http://example.com/claim
  • tpl-contact.php - this template is used to display the page http://example.com/contact
  • tpl-coupon.php - this template is used to display the page http://example.com/coupon/*
  • tpl-coupons.php - this template is used to display the page http://example.com/coupons/*
  • tpl-home.php - this template is used to display the home page of your site http://example.com
  • tpl-listing.php - this template is used to display the single listing page http://example.com/listing/*
  • tpl-listings.php - this template is used to display the listings results page http://example.com/listings/*
  • tpl-msg.php - this template is used to display error and operation result messages http://example.com/msg*
  • tpl-post.php - this template is used to display the single post page http://example.com/post
  • tpl-posts.php - this template is used to display the list of posts (blog) http://example.com/posts
  • tpl-profile.php - this template is used to display the page http://example.com/profile
  • tpl-search.php - this template is used to display the search results page. http://example.com/search/*

As demonstrated above, the naming convention makes it very easy to locate which file you need to edit in order to change the look and feel of any page on your site.

User dashboard templates

Similar to the front-end templates, changing how the user dashboard area looks is very intuitive. All user dashboard templates are located in the /templates/user-templates folder.

Admin templates

And if you want to change the admin area look, the templates for the admin section are located in the /templates/admin-templates folder.

Translation

All text displayed in the browser can be translated. Directory Plus uses 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 /language folder. Inside this folder you can find one folder for each different language.

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 within the double quotes.

Troubleshooting

(HTTP) 500 Internal Server Error

A HTTP 500 Internal Server Error is a generic error message so to troubleshoot this type of error you need to see the actual error that was logged in the error log file. The error log files are usually created in the folder where the error occurred so you can access them using FTP to see what is the actual error message that generated the generic HTTP 500 Server Error. If you can't find the error log file, please contact your hosting provider to inform you its location.

Common situations that trigger the HTTP 500 Server Error are:

  • Old PHP version on your host. You need at least PHP 5.5+. 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. This could happen if you edit the .htaccess file
  • Wrong file permissions. Depending on your hosting account, it may require different permissions. Usually the permissions need to be set to 644 for files and 755 for folders. Check with your host what should be the appropriate permissions
  • 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 login errors are usually related to the return url value you entered for your app you created on the Facebook App Dashboard. Please make sure you have defined the return url as: https://YOURSITE.com/vendor/hybridauth/hybridauth/hybridauth/?hauth_done=Facebook. Also make sure that you are using the https if your site is https or http if your site is http.

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



























Top