Directory Component, Plugin and module

[datahell]

The Directory system consists of the Directory Component, the Directory plugin and the Directory Category module. With Directory you can create lists of different content types (hotels, restaurants, coffee shops, villas, professionals, etc). You can organize the listings into categories. Categories are mostly used for content grouping and only used in frontend with module Directory Category. Each category may have a different template, meaning a different layout and style. The component comes with 2 templates, which you can copy and create your own custom ones. Directory uses an XML API system which allows the listings to be displayed in any site(s)! So, you can have installed Directory component in site a.com and, use the Directory plugin to display the listings at sites b.com, c.com, d.com. The plugin creates a full page which may have image, description, additional elements (grouped), image gallery, contact form, map, and more. For creating the category page use the Directory Category module.

1. Directory component (data entry)
Component Directory is only used to add your data. It doesn't have an HTML interface to show them to the public, it has an XML API system instead. To actually display the data you use the plugin. But we will talk about this later. So, use the component Directory from Elxis administration section to add your listings. First, separate your listings into categories. Let's say you want to list the Coffee shops in your area. So, create a category named "Coffee shops". When you create a category the component asks you to pick a template. There are 2 templates by default (you can create unlimited ones): Places and Business. Pick the one you like more for this type of listings.

Now you can add a listing, or not yet? Directory has a number of standard information fields like Title, Sub-title, Image, Coordinates, Gallery, Address, Country, City, E-mail, Stars, etc. But you are not limited into the standard fields, you can add unlimited others! To do so go to Additional elements section. You can create any additional information element for your listings like "Colour", "Weight", "Pet friendly", "Apartment type", etc, what ever you want. These elements can be TEXT fields, SELECT fields, YES/NO fields, or URL/LINK fields. You can also group these elements in order to be displayed together. For instance for the Coffee Shop case, you might want to create elements like: "Coffee types available", "Overall rating", "Suitable for disabled", etc.. When you create your additional elements and listings you can go to add a new listing.

1a. Add a listing
Select Directory > Listings > click New. There is a number of standard informational fields. More fields, including your custom additional elements, can be found on tab Additional info. If you don't fill-in a field then this field will not be visible in front-end. So, fill-in only the fields that are relative to this specific list type (the coffee shop for example). Some special fields:
Gallery: Create a folder in Media Manager under path media/images/dirgalleries/, and name it something relevant to the listing, eg starbucks_athens. Upload your images there. You can select that folder when you add/edit a listing and Directory will automatically create an image gallery.
YouTube Video ID: To display a video from YouTube.
Coordinates: Comma separated latitude and longitude. Directory will create a map of the spot using Open Street maps. A link for drive directions will also be displayed for Google maps.
Contact form: If set to Yes AND if you have provided a valid contact E-mail for this listing, Directory will display a contact form.
Save your listing.

Before proceeding further check component's parameters. Directory > Settings > Tab parameters. Copy the value of the Encryption key parameter. We will need it later on. If you want you can change it to anything you want.

2. Directory plugin (display a listing)
Component directory has no public interface, to display a listing you must use the Directory plugin. You can install this plugin on the same or on ANY Elxis site you want. Meaning that you can display your listings in multiple sites! Install the plugin and edit it. Make it published and go to tab Parameters.

2a. Plugin parameters
API server URL: The URL of the site with the Directory component installed. Example: https://www.example.com
Encryption key: As you have it in component Directory
Enabled languages: Comma separated list of enabled languages for the API server. API server MUST SUPPORT THEM else you will get error! (example: en,it,el,de,ru ). Leave empty to query the API server always in default language.
Use cache: If YES, the plugin will use a cached version of the data making it run much faster. The data will be refreshed every 6 hours. We strongly recommend to set this to YES. Set it to NO only for testing purposes, or when you want to display actual data or to refresh the cache immediately. After testing switch cache back to YES.
Province/District: Show this in contact form?
Municipality/Council: Show this in contact form?
Save the plugin.

We assume you want to display multiple listings from the same Directory category. So we will proceed to steps 2b and 2c.

2b. Create a module position for the category page
Extensions > Module positions > New
Set the position name to something relevant to the listings category. For example: dir_coffees
Save it.

2c. Create content category
Elxis administration > Content > New category

Name it whatever you like ("Coffee Shops").
Go to tab "Parameters". Set (important):
Page style: Print: Hide
Page style: Inner modules position: dir_coffees
Page style: Pagination: Hide
Subcategories: Hide
Featured articles: Featured number: 0 important!
Short articles: Short articles number: 0 important!
Link articles: Links number : 0 important!
Comments: No
Click "Save".

2d. Integrate plugin Directory.
Content > Articles > Click "Add"
Provide Title, SEO title, Subtitle, META keys, nothing else.
Select category: Coffee Shops (or whatever).
Publish it.
Tab "Articles Body": In main text type: {directory}XX{/directory}
where XX the listing ID of the coffee shop as is in Directory component. Foe example {directory}1{/directory}
Tab "Parameters": Hide EVERYTHING! (title, author, image, date, etc). The whole page will be created by the plugin with the data from directory, so we don't want any data from the local site.
Save the article.

3. Module Directory category
Install on the site with the plugin the Directory category module. Click to edit it.
Set a relative title for the module (eg Directory Coffee shops) and set Show title = No
Set Position: dir_coffees
Tab Parameters:
Category ID: The ID of the category for the Coffee shops as you have it in Directory component (not the local Elxis content category). Example: 1.
I strongly recommend using Cache. Disable cache only for testing purposes.
Click Save/Apply.

4. Testing
We are ready to see what we done. Go to the Elxis content category page. You should see the title of the category and below the output of the Directory Category module listing the listings of this category. The Directory module detects the articles that have listings of this category integrated and creates automatically links to them. So, you can click an item and go to the listing page. There you will see the whole page been generated by the Directory plugin. You can add more listings to this category and they will be displayed in the module automatically. However you must each time also create an Elxis article to integrated the plugin with the new listing (just the tilte, seo title and sub title as described in step 2d).

5. Templates
Directory comes with 2 templates preinstalled, Places and Business, but you can create more. Templates control the style and layout of the page. You will find the templates under this path:
components/com_directory/inc/templates/
A template consists of just 2 files with the same name, a PHP file and a CSS file. For example: restaurants.php and restaurants.css

Please do not edit the default templates, copy them instead and rename them to what ever you want. You just created a new template! You can now open it and edit it as you wish. You can change the HTML, the CSS, you can add more data into it, whatever you want.
When you select a template for a Directory category all listings belonging to this category will have the same template. If this template/style does not exist in the remote site (the one with the Directory plugin) the plugin will automatically load it from the mother site.

6. Cache
Directory uses cache a lot because of the remote calls to the XML API. It also caches the templates. If you have made changes and you don't see them in public section you can either wait a few hours for the cache to be expired or delete cache to immediately force update of display.

7. Support
Directory system may sound difficult to use at first, especially if you are an Elxis newbie. So, if you have questions post them below and I will help you getting started.

[seadhna]

Hi datahell, this is great! Very useful for many uses! Amazing work.
Do you have any plans to integrate into Elxis Search - to be able to filter searches by 'additional elements' would be super!!
In the listings would PDF file upload be possible on the GENERAL tab, after image upload? (e.g. menu PDFs for restaurants, or list of prices for other kinds of businesses).

[datahell]

This is a first release, improvements can be done in the future.
Regarding file upload (PDF, etc): I thought about file upload but I decided not to do so for 2 reasons: 1. Can be done in a later version, 2. Can be done elsewhere.

PDF or any file workaround
Create an additional element of type URL. You can name it Restaurant Menu PDF, or whatever. When you add/edit your listing set the value to the URL of the PDF, or other, file (zip, image, anything). Normally that's enough, you are done. If you want special styling (eg a PDF icon) you can do so in your template's PHP file. Example follows:

Code: [Select]

if ($ex['type'] == 'URL') {
if (preg_match('@(\.pdf)$@i', $ex['value'])) {
$html .= '<a href="'.$ex['value'].'" title="'.$ex['title'].'" target="_blank"><i class="fas fa-file-pdf"></i> '.$ex['title'].'</a>';
} else {
$html .= '<a href="'.$ex['value'].'" title="'.$ex['title'].'" target="_blank">'.$ex['title'].'</a>';
}
}

[seadhna]

Yes! The URL option is a good solution for now. Thanks!

[Dimitris Kanatas]

Γεια σας! Μπορείτε να μου δώσετε ένα παράδειγμα για τις ρυθμίσεις μιας και σε μένα εμφανίζει:

Could not get data from Directory API server! SSL connection timeout

Δηλαδή παράδειγμα:

Κλειδί: Mn32.........

Και

URL διακομιστή API https://forum.elxis.org

Κλειδί κρυπτογράφησης: Mn32...........

Σωστά;

[datahell]

API Server URL: The URL of the site you have Directory component installed (without trailing slash), not elxis forums. Note that the site must be online in order for the API server to work.
Do not post encryption key in public.

[chongbing]

Hi datahell,

The introduction seems good. Because I don’t know how it will actually work, can I ask if there is an online demo that I can watch?  Thank you.

[datahell]

The content looks similar to the standard Elxis articles pages. So, there is nothing special to see. However a few of the advantages of Directory are:
- You can create your own template and make a totally custom layout/style for Directory pages.
- You can have custom data elements listed in groups as you like.
- You can share the content between multiple sites.
- It has built-in support for things like map, gallery, youtube, etc, without the need of a plugin.

[seadhna]

Hi datahell,
can you think of any way to add listings in bulk? Any kind of CSV import for example?

[sdr]

How to translate the "categories"?

[datahell]

You don't need to translate the categories because they don't get displayed anywhere.

[Dimitris Kanatas]

API Server URL: The URL of the site you have Directory component installed (without trailing slash), not elxis forums. Note that the site must be online in order for the API server to work.
Do not post encryption key in public.

Καλημέρα Γιάννη!

Κάτι πρέπει να συμβαίνει λάθος γιατί ενώ τα βήματα γίνονται όπως τα περιγράφεις μου εμφανίζει μήνυμα:

Could not get data from Directory API server! SSL connection timeout

[datahell]

Έχει κάποιο θέμα η php (βιβλιοθήκη CURL) με πιστοποιητικά SSL. Δηλαδή δεν μπορεί να φορτώσει κάτι με σύνδεση HTTPS. Θα πρέπει να κάνω τοπικά debug για να προτείνω λύση.

Άσχετο: έχετε κάνει πολύ ωραία δουλειά στο site, μπράβο σας. Πολύ οργανωμένο περιεχόμενο!

[Dimitris Kanatas]

Γιάννη είμαι στην php 7.4.33 αλλά αν ανεβάσω την έκδοση στην 8.x χάνω όλο το site.

Άσχετο: Σε ευχαριστούμε.... προσπαθούμε ότι μπορούμε πραγματικά στον ελεύθερο μας χρόνο γιατί έχουμε τόσο τρέξιμο τα πρωϊνά που μόνο τα απόγευματα το φτιάχνουμε... με μεράκι!

[datahell]

Λοιπόν, μπορώ απομακρυσμένα να συνδεθώ στο Directory component στο site σου χωρίς πρόβλημα. Φυσικά αυτό χωρίς επιτυχές login γιατί δεν ξέρω το κλειδί κρυπτογράφησης του Directory. Ωστόσο το σύστημα δουλεύει άψογα. Άρα το πρόβλημά σου είναι καθαρά η βιβλιοθήκη CURL στην PHP σου. Για να λυθεί το πρόβλημα θέλει τοπικά debug ώστε να βρω ποιος συνδυασμός δουλεύει παρακάμπτει το πρόβλημα στο site σου.

Τι μπορείς να δοκιμάσεις στον κώδικα του plugin Directory.


1. Κατέβασε το πιστοποιητικό SSL από εδώ (ή δες την σελίδα), ανέβασε το στο site σου και χρησιμοποίησε το στο plugin:
curl_setopt($ch, CURLOPT_CAINFO, '/full/path/to/cacert.pem');
Αλλάζεις επίσης το CURLOPT_SSL_VERIFYPEER από false σε true:
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);

2. Σβήνεις την γραμμή CURLOPT_CAINFO που πρόσθεσες πριν και ξανακάνεις το CURLOPT_SSL_VERIFYPEER σε false.
Κάτω από αυτό:
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
Προσθέτεις αυτό:
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);

Δες αν έχεις διαφορετικά μηνύματα σφάλματος ή αν άλλαξε κάτι ή αν δούλεψε με κάποιο συνδυασμό.
Δεν μπορώ να κάνω κάτι άλλο από εδώ.