Requirements

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

Install

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

1. Prepare

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

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

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

iv. 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';

					

v. 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


Troubleshooting Install

If for some reason you have problems installing Directory Plus, please double-check the following items:

  • Make sure that the .htaccess file is uploaded correctly. This is a hidden file so sometimes it doesn't get uploaded depending on your system settings. Check that this file is present in the directory where you installed the script
  • Check if your MySQL version is at least v.5.6
  • Check if your PHP version is at least v.5.5
  • Check if mod_rewrite is enabled. Please ask your host to enable mod_rewrite
  • Configure a SMTP credential. All messaging functionality such as confirmation emails, new user registration notification, forgot password functionality, etc, requires proper SMTP configuration. I recommend using a throw-away SMTP credential which you create just for the site messaging functionality. To configure SMTP, go to "Admin Area" -> "Site Settings" -> "Email" tab

How to Update

If you have Directory Plus already installed and want to update when a new version comes out, you have 2 options:

1. Option 1

Just download the latest zip file from your Codecanyon dashboard, unzip the package and upload all files to your server which will replace the old existing ones except the:

  • '/pictures/' folder
  • '/assets/' folder
  • '/inc/config.php' file
  • '/inc/my.functions.php' file

2. Option 2

Just download the latest zip file from your Codecanyon dashboard, unzip the package, find the 'updates_[random_string]/directoryplus_x.xx_update' where x.xx corresponds to the version number you are updating to, then upload the contents to your server. The directoryplus_x.xx_update folder contains only the modified files for the x.xx update.

Please note that using this update method, you need to apply each update sequentially. For example, if you want to update from v.3.22 to v.3.25, you need to apply the directoryplus_3.23_update, then the directoryplus_3.24_update and after that, the directoryplus_3.25_update, in this order.

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, Carto, Stamen 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 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 want to use TomTom as your map provider, you need to download the "Maps SDK for Web with vector maps" from https://developer.tomtom.com/maps-sdk-web/ and extract it into the 'assets/js/sdk-tomtom' folder in 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. You can obtain SMTP credentials from your hosting provider or email provider. If you want to use SSL/TLS secure emails you need to include tls:// or ssl:// in the SMTP server field, for example tls://smtp.yoursite.com.

Starting from v.3.30, including the tls:// protocol in the server field is not necessary, just enter smtp.yoursite.com and the encryption will default to TLS. If TLS doesn't work for your server, you can try SSL by following these steps (requires v.3.30 or newer):

1.Edit your inc/my.functions.php file, edit(if exists) or include this line:


$cfg_smtp_encryption = 'ssl';

2.In the admin area, on the SMTP settings tab, try port 465 or 587 and verify that the email delivery is working. If the email is not working, please make sure that the setting in Admin -> Site Settings -> Email -> Admin Email has the same domain as the SMTP user. The Admin -> Site Settings -> Email -> Admin Email value is used as the "From" email address in all emails sent to users by the script and some SMTP servers will refuse sending emails where the from domain is different from the SMTP user's domain.


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" 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.


XML Sitemaps

To initialize the sitemap, please to go Admin Area -> Tools, then click on the execute button next to the "Regenerate sitemap.xml" tool. Next, on the same screen, you can submit the sitemap to Google by clicking on the execute button next to "Submit sitemap.xml to Google".


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;
  4. next, click on the "Permissons" tab, "Edit" button, then make sure the "Request email address from users" checkbox is checked

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.


To change the site logo, please upload your logo in two versions to assets/imgs/logo.png and assets/imgs/logo-white.png. The logo.png version will be used on white backgrounds while the logo-white.png needs to be in lighter colors because it will be used on darker backgrounds such as on top of the hero image on the homepage.


Child Theme

Child Themes allows you to change your directory's appearance without affecting future updates.

If you have made template modifications and want to keep them, rename the modified template files by appending the '-child' suffix.

For example, if you want to edit the templates/tpl-home.php, make a copy of the file and rename it to templates/tpl-home-child.php and edit this file instead. Another example, if you want to edit the templates/header.php, make a copy of the file and rename it to templates/header-child.php and edit this file instead.

In the examples above, the script will try to load templates/tpl-home-child.php first, if it finds that file, it will use it and ignore templates/tpl-home.php. Same for templates/header-child.php, if it finds that file, it will use it and completely ignore the original templates/header.php file.


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 interface text displayed in the browser can be translated. Prior to v.3.21, Directory Plus used PHP files to handle translations. From v.3.21, all translations can be edited in the Admin Area.

Prior to v.3.21

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.

From v.3.21

To edit/modify the translation of interface text, go to Admin Area, then Language menu. On the Language page, first select the language that you want to modify. Next, choose the template where you want to modify the text. For example, if you want to modify text on the homepage, select the 'public;home' template, then click on the 'Load vars' button.

Apart from selecting a specific template, you can also select the 'public;global' template which stores common text used in several pages.

It's also possible to create a new language by clicking on the "Create Language" button and selecting the language you want to create. This will create a duplicate of the English language text for the language you selected. Then select the newly created language and load the template vars to translate from English to the language you have just created.

How Tos


Change Logo

To change the site logo, please upload your logo in two versions to assets/imgs/logo.png and assets/imgs/logo-white.png. The logo.png version will be used on white backgrounds while the logo-white.png needs to be in lighter colors because it will be used on darker backgrounds such as on top of the hero image on the homepage.


Disable Search Autocomplete For Cities

By default, the search form in Directory Plus let users find the city by presenting suggestions while the user type the name of the city. To disable this behavior and show just a drop down of cities, go to "Admin Area" -> "Site Settings" -> "General" tab, scroll down and find the input field labelled "Use Select2" and set it to "No".


Show language switcher

The language switcher widget allows users to select their preferred website language. To define which languages you want to make available for the user to pick, go to "Admin Area" -> "Site Settings" -> "General" tab, scroll down and find the input field labelled Languages (Ex: en,es,de)

In this field, enter a comma separated list of language codes in ISO-639-1 (2-letter) format without any space character before or after the comma.

Example:

en,fr,de,pt

In the example above, the language switcher will show a drop down with English, French, German and Portuguese options. Please note that for each language you enter in the options field, it needs to have the corresponding translation folder in the language/* folder. In the example above, you need to have the folders:

language/en
language/fr
language/de
language/pt


Change Listing Ownership

You can change the owner of each listing by going to "Admin Area" -> "Listings", then in the list of listings, click on the "Expand" button next to the listing you want to change ownership. After clicking on the "Expand" button, click on the pencil icon next to "Transfer to user id" and enter the id of the user that you want to define as owner of this listing.

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 and ask them to inform you its location.

Common situations that trigger the HTTP 500 Server Error are:

  • The 'inc/config.php' file contains syntax error.
  • 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

Please send all technical support requests through the Support Form on Codecanyon



























Top