FAQ, Tutorials & Customization Of The Theme.

How to import dummy data.

The zip file you downloaded contains an xml file that can be used to import dummy data to your wordpress installation. Some users prefer this approach as it gives them a good starting point and the ability to easily change the data to their needs without having to create all the pages by hand.

NOTE: importing the dummy data in existing wordpress installations with some data already can cause problems so make sure you have a clean wordpress installation before doing this.

If you see any failed to import error do not worry, everything is fine.

1 Delete all the pages and posts as well as any categories other than the default “Uncategorized” category
2 Go to Tools » Import and select the option “Wordpress” (at this point Wordpress might ask you to install the Import Plugin, confirm)
3 Click the button “browse” and select the file “dummy_data.xml” contained in the downloaded zip
4 Click the button “Upload file and import”
5 Check the option “Download and import file attachments”
6 Click the button “Submit” and all the dummy data should be imported

How to customize the skin of the theme.

1 In your WordPress admin, navigate to "Appearance > Customize" or click the "Customize layout" button into the admin bar on top of the screen.
2 To customize the skin click on "Theme Skin" and select a skin from the list.
3 If you wish to create your own skin, click on Theme Skin and select the option "enable custom controls".
4 To continue with the customization of the colors click on "Colors" and new settings will be displayed, from there you can change colors of the theme.

How to translate the theme.

TThis theme is ready for localization via .po/.mo files

If you are not familiar with translating Wordpress themes, I recommend reading this article:http://codex.wordpress.org/Translating_WordPress

1 Open file wp-config.php of your wordpress installation and change the language value, the language of this file must match to your translation;
2 Find the our theme folder and open it
3 Duplicate default.po and default.mo
4 Rename your copy of default.po and default.mo example: fr_FR.po/mo for France, en_EN.po/mo for English, he_HE.po/mo for hebraic, and so on.
5 Download poedit http://www.poedit.net/download.php
6 Open your file with the POEdit software
7 Translate your file
8 Save your file.

How to add multi ratings to your listings

Introduced with update 1.5.4 the theme now supports multi ratings for listings. To enable multiratings you MUST install the GD Star Rating plugin which can be found here http://wordpress.org/plugins/gd-star-rating/. Once installed follow these steps to enable it.

1 You must install and activate the GD Star Rating Plugin First.
2 Navigate to Theme Options -> Listings Settings -> General Settings
3 Disable the "Enable Ratings System" if enabled
4 Enable the option "Enable Multi Ratings System"
5 Navigate to GD Star Rating -> Settings and disable the option "Post And Page Review Rating." into the "Features Tab"
6 Navigate to GD Star Rating -> Settings -> Articles and disable all the "Auto insert rating code:" options
7 Navigate to GD Star Rating -> Multi Sets and create a new multi rating settings
8 While creating the new multi set, you must disable the auto insertion of the plugin, make sure the "Auto Insertion" option is set to "No"
9 Save the multi set rating and get the ID number, if it's your first multi set, it should be 1
10 Navigate to Theme Options -> Listings Settings -> General Settings, locate the option "Multi Set ID Number" and enter the ID number of the set that you just created.
11 Save the options. You should now see the multi rating box inside the single listings pages.

Note that we can't provide any support for this plugin. We only have added integration for its features.


How to Restore The Advanced Custom Fields Plugin Interface

Atlas uses the Advanced Custom Fields Plugin to generate metaboxes and custom fields for many parts of the theme. The interface of the plugin has been disabled to avoid making damage to the fields of the theme. However if you are an advanced user and you know how to use this plugin, you might want to enable the interface back.

PLEASE NOTE: I do not offer support for this plugin. Support for the plugin is provided through the support forum of the author here http://www.advancedcustomfields.com/.

1 Open file functions.php
2 Search and delete the following line
define( 'ACF_LITE', true );
3 Save the file
4 You should now see the "Custom Fields" menu into your WordPress Dashboard.

How to Add Additional Fields For Your Listings

Atlas uses the Advanced Custom Fields Plugin to generate metaboxes and custom fields for many parts of the theme. By using the plugin you can also add additional fields for your listings and you can show these fields on the frontend submission form.

NOTE: the following tutorial will show you how to add new fields on the backend and frontend submission form. It will not show how to display the fields into the listing. To show the custom fields values on the single listing page please follow the tutorial "How to show custom fields for listings".


How to show custom fields for listings

If you have created new custom fields with the tutorial up here, you might want to display the values of those fields on the single listing page on your website.

Since the theme uses the Advanced Custom Fields Plugin to add those fields, all you need to do is just follow the documentation on the official website here http://www.advancedcustomfields.com/resources/getting-started/displaying-custom-field-values-in-your-theme/

You will need to use the php function the_field(); to display the custom field values. The file where you might want to add that function is single-listings.php around line 90.


How to upgrade the theme

The easiest way to update the theme is to re-download the package from themeforest, unzip it, locate the atlas.zip file and unzip it. Login via FTP on your server and overwrite the existing atlas theme folder.

Note: by doing this you will lose your changes and customization to any file that you might have changed. It is good practice to use child themes when making modifications to theme files. It is also recommended to make a backup of your changes before upgrading.

We can't be held responsible for any damage/data-loss that you might cause during the upgrade process of your theme.


How to use the search form fields builder.

Added with version 1.4, the theme now comes with an integrated search builder that helps you in adding your custom fields.

Understanding the logic of the search fields.

It is important that you understand what is the logic behind the search form and the fields before you think that the search form doesn't work.

  1. The advanced search form only looks for your listings. It doesn't look for addresses on the map. Meaning the search query only looks in your database.
  2. The first text input field looks for the listing title and the listing content.
  3. The listing category and location fields, uses the operator "IN" meaning they search for the listings that are INTO those taxonomies.
  4. The featured/not featured options check for the value of the featured listing option that you can set for each field. They uses the "meta_key" value of the listings custom field.
Adding New Fields Through The Search Form Fields Builder.
  1. Your theme version must be 1.4 or greater.
  2. Navigate to "Theme Options" -> "Search Form Fields" -> "Custom Search Fields" to access the fields builder.
  3. Press the "Add New Field" button, a popup will display just above the button from where you can select the type of field that you want to add.
  4. Select the kind of field that you wish to add and follow the instructions of each field.
Using the author field

The author field allows you to display a field where the user can select from which authors he wants to search for the listings.

To use the field, select it from the options of the search builder and fill in the deatils.

Using the HTML field

The html field is a useful field that allows you to insert any kind of html content, it is extremely useful when you'd like to modify the appearance of the from.

To use the field, select it from the options and then insert your custom html content.

Using the Meta Key field

The metakey field is one of the most powerful field of the search builder. It gives you extreme flexibility on what listing custom field the search form should look for.

The most important option that you need to fill in the "meta key" option, this is where you insert the value of the custom field that the search form will be looking for.

Note: the metakey value is the field name of the listing custom field. (It isn't the field label - label and name are 2 different things) How to retrieve the field name? Easy, when you create a custom field, the field name is just right here (click for a screenshot). So, the field of the search builder, will look like this (click for screenshot)

If your search field is a selectable field (select, multi-select, radio, checkbox), you need to add the options of the form. To add options simply follow the following format:

field_value=Option Label

"field_value" stands for the option that your custom listing field might have, it's also the value that the search form will look for.

"Option Label" is the name of the option that the user will see into the search form. To add multiple options simply add the symbol % in the middle of each option.

Example: test1=label1%test2=label2


How to manually customize the search form.

NOTE: this tutorial is for advanced users only.

First of all you need to open file theme-setup.php in folder /framework/functions/ - scroll down the file and you will see a function like this

/* 
 * Register search form fields
 */
if(!function_exists('tdp_search_fields')) {
    function tdp_search_fields() {
        $args = array();
        $args['form'] = array('action' => get_field('search_results_page','option'));
        
        $args['wp_query'] = array(
            'post_type' => 'listing',
            'posts_per_page' => get_field('results_per_page','option'),
            'order' => 'DESC',
            'orderby' => 'date'
        );
     
        $args['fields'][] = array(
            'type' => 'search',
            'label' => __('Search For Listings','atlas'),
            'placeholder' => __('What are you looking for ?','atlas'),
            'value' => ''
        );

        $args['fields'][] = array(
            'type' => 'taxonomy',
            'label' => __('Listing Category','atlas'),
            'taxonomy' => 'listings_categories',
            'format' => 'select',
            'operator' => 'IN'
        );

        $args['fields'][] = array(
            'type' => 'taxonomy',
            'label' => __('Listing Location','atlas'),
            'taxonomy' => 'listings_location',
            'format' => 'select',
            'operator' => 'IN'
        );

        $args['fields'][] = array(
            'type' => 'meta_key',
            'label' => '',
            'meta_key' => 'listing_is_featured',
            'format' => 'radio',
            'values' => array('' => __('Display All Listings','atlas'), '1' => __('Display Only Featured Listings','atlas') ),
            'compare' => 'LIKE'
        );
     
        $args['fields'][] = array(
            'type' => 'submit',
            'value' => __('Search For Listings','atlas')
        );
        return $args;
    }
}

There are two essential components to any arguments array:

  1. WP_Query Arguments – Established with the ‘wp_query’ key, these arguments set the defaults for your search’s WP_Query object. Any arguments accepted by WP_Query may be passed here.
  2. Fields – Fields can be added to your search form by creating & extending the ‘fields’ key of your arguments array. Each value in the ‘fields’ array contains an array storing arguments for that field. Fields will be generated on the page in the order they are defined. Please refer to the Fields documentation for more in-depth instructions on establishing your form fields.

It's highly recommended NOT TO modify the "form" and "wp_query" $args of the function.


Field Types

Fields can be added to your search form by creating & extending the ‘fields’ key of your arguments array. Each value in the ‘fields’ array contains an array storing arguments for that field. Fields will be generated on the page in the order they are defined.

There are a variety of field types available for use in your search forms. They are:

  • author
  • date
  • generic
  • html
  • meta_key
  • order
  • orderby
  • posts_per_page
  • post_type
  • search
  • submit
  • taxonomy

Field types are defined by passing the ‘type’ argument within the field’s arguments array.

Example: Creating a taxonomy field

$args['fields'][] = array('type' => 'taxonomy');

Fields Format

Fields can be constructed in a variety of formats, such as: text inputs, select boxes, checkboxes, radio buttons, and multi-select. You can specify a field’s format by passing a ‘format’ parameter to the field’s arguments:

$args['fields'][] = array('type' => 'taxonomy', 'format' => 'select');

The above code will create a taxonomy field as a select box. For more information, consult the documentation on field formats & parameters.


author field

A field used for searching posts by author.

Parameters

label
(string)   
Default: None
format
(string)   'select', 'multi-select', 'checkbox', 'radio', 'text', 'hidden'
Default: select
default
(string)   
Context: A user ID number
Default: None
authors
(array)   An array of integers (author IDs)
Default: An array of all users (ID => name)

date field

Parameters

label
(string)   
Default: None
format
(string)   'select', 'multi-select', 'checkbox', 'radio', 'text', 'hidden'
Default: select
date_type
(string)   'year', 'month', 'day'
Default: year
date_format
(string)   A valid PHP date format string. See this page for details.
Default: Varies by date_type. (year: 'Y', month: 'M Y', day: 'M j, Y')
values
(array)   
Default: Varies by date_type. An array of all [years/months/days] in which content has been published.
default
(string)   
Default: None

meta_key field

A field used for searching posts by post meta.

Parameters

label
(string)   
Default: None
format
(string)   'select', 'multi-select', 'checkbox', 'radio', 'text', 'hidden'
Default: select
meta_key
(string) (required)   
Default: None
values
(array) (required)   
Default: None
compare
(string)    '=', '!=', '>', '>=', '<', '<=', 'LIKE', 'NOT LIKE', 'IN', 'NOT IN', 'BETWEEN', 'NOT BETWEEN', 'EXISTS', 'NOT EXISTS'
Default: '='
default
(string)   
Default: None

search

A field used for standard keyword-based search queries.  Search fields are always implemented as text fields.

Parameters

label
(string)   
Default: None
format
(string)   'select', 'multi-select', 'checkbox', 'radio', 'text', 'hidden'
Default: text
value
(string)   
Default: None
placeholder
(string)   
Default: None

submit

Displays a submit button for the search form.

Parameters

label
(string)   
Default: None
value
(string)   
Default: Search

taxonomy

A field used for searching posts by specified terms in a given taxonomy.

Parameters

label
(string)   
Default: None
format
(string)   'select', 'multi-select', 'checkbox', 'radio', 'text', 'hidden'
Default: select
taxonomy
(string)   Taxonomy slug (ie 'category', 'post_tag')
Default: category
term_format
(string)   'ID', 'slug', 'name'
Default: 'slug'
terms
(array)   Array of term values, in the format specified by term_format (either ID, slug, or name)
Default: All terms belonging to the given taxonomy
operator
(string)   'IN', 'NOT IN', 'AND'
Default: AND
term_args
(array)   
Default: array('hide_empty' => false )
default
(string)   
Default: None

New Listings Shortcodes

Since update 1.6 the theme now includes new additional shortcodes. To use the new shortcodes make sure you've using the latest version of the theme and it's plugins.

  1. Listings Search Form: use the shortcode [listings_search_form] to display the search form anywhere you'd like into the theme. The shortcode does not have any parameters.
  2. Listings By Category: use the shortcode [listings_by_category category_id="1" amount="3"] to display listings from a specific category through a grid layout. The shortcodes uses the category_id and amount parameters.

    Set the category_id parameter to display a specific category. You can get the category id from Listings -> Listings Categories, edit a category and into your url bar you'll see the category ID number.

    Set the amount parameter to choose how many listings you'd like to display from that category.
  3. Listings Categories Lists: use the shortcode [listings_categories_list] to display a list of all your main parent categories. The shortcode does not have any parameter.

How To Use the Ajax Map

Since update 1.6 the theme now includes a new faster ajax map. The map loads all the listings through json, this map mode is useful if you have a lot of listings on your websites and you want to speed up the loading of your website.

The ajax map once enabled, will require few more settings to be filled in order to make it work.

  1. Navigate to Theme Options -> Listings Settings -> General Settings and enable the option "Enable Ajax System" at the top.
  2. The ajax map supports new geolocation customization options. Navigate to the "Main Settings" tab of the same Listings Settings page and customize the options "Geolocation Text" and "Geolocation Custom Pin Image"
  3. The Ajax map requires a fixed address center. Navigate to Theme Options -> Map Start Point and set a custom address at the option "Custom Map Center"
  4. Adjust the "Geolocation Zoom" into the same page.

How To Display Listings Categories Child Categories into listings categories/location pages

Since update 1.6 the theme now includes a new option to display child categories of a main category when viewing it's parent category page. The same applies to the locations.

  1. Navigate to Theme Options -> Listings Settings -> General Settings and enable the option "Current Taxonomy Child Categories/Locations". This will show a list of child categories at the top of the listings if a category has child categories.
  2. Alternatively you can also show the child categories into a widget in the sidebar. Navigate to "Appearance -> Widgets" and add the "Listings Child Categories" widget to the "Listings Sidebar". The widget will automatically display ONLY if current main category page is being displayed and has child categories.

How To Use Megamenu

Since update 1.6 the theme now includes a new megamenu support.

  1. Navigate to "Appearance -> Menus", click on the "Screen Options" button at the top of the screen and enable the "CSS Classes" option.
  2. To add a megamenu you need to set a custom css class for the parent menu item, in the example below we've added the class "megamenu" and "columns-4" to setup a megamenu with 4 columns. You can change the columns number to from a range of 2-4 to change the amount of columns that you want to use into the megamenu.