Resource icon

XenPorta User Guide and FAQ

Overview Reviews (3) Discussion
Status
Not open for further replies.
Saeed

Saeed

Well-known member
Saeed submitted a new resource:

XenPorta User Guide and FAQ (version 1.5) - A simple user guide for XenPorta

XenPorta User Guide and FAQ​

Authors: Saeed, RobParker

This user guide is meant to help answer some of the most commonly asked questions about the XenForo portal add-on XenPorta by Jason Axelrod (Jaxel). With dozens of users having installed XenPorta, this is one of the best portals currently available for XenForo. Although this brilliant add-on is available for free, your support is definitely appreciated. So if you use this add-on and find it useful, you may want to consider donating an amount of your choosing to the developer.

With the original add-on thread having gone beyond 200+ pages, mostly with questions pertaining to the same problems repeatedly, the two of us, (RobParker and myself) thought of listing down in one place all the frequently encountered issues users have been seen to face after installing the portal, along with their solutions. We shall try to keep this guide updated over time.

In case you would like any addition made to the guide, feel free to send either of us a message and we shall have a look at it.

To make it easy to read and navigate through the guide, it has been divided into the following sections:
Read more about this resource...
 
Installation instructions for XenPorta 1.5 and 1.5+ [originally posted here]

Instructions for first time installation:
  • Download the attached .zip package, and extract its contents.
  • Upload the entire contents to the root of your XenForo installation via FTP.
  • In your XenForo Admin Control Panel (ACP), go to “Install Add-on” and install from file on server: library/EWRporta/addon-EWRporta.xml
  • In your ACP, go to Home > Options > [8wayRun.Com] XenPorta (Portal) and configure the given options.
  • Once installed you should see a “XenPorta” option in the left column of your ACP.
  • To add modules to the portal, click on “Blocks” and install the desired blocks as described below in How do I add extra blocks?
  • To customise the layout, drag and drop the modules you wish to display into the positions where you want them to show. Do not forget to press “Save changes” to save your configuration. In 1.5 the layout functionality has been greatly increased and instructions can be found below in What are Layouts?
----------------------------------------------------------------------------------------------------​

Instructions for upgrading XenPorta 1.4 to 1.5+:

Please note that XenPorta 1.5 is a complete overhaul of XenPorta and because of this, all previous versions of XenPorta must be UNINSTALLED before upgrading to the new version. To do so, proceed as follows:
  • In your XenForo Admin Control Panel (ACP), go to Home > List Add-ons > [8wayRun.Com] XenPorta (Portal) and under “Controls”, click “Uninstall”.
  • Before uploading the new files, delete all XenPorta files (or folders) from the /js and /library folders of your XenForo installation. These are:
    • /js/8wayrun
    • /library/EWRporta
  • Finally, make sure to drop all XenPorta tables from your database.
  • Download the attached .zip package, and extract its contents.
  • Upload the entire contents to the root of your XenForo installation via FTP.
  • In your XenForo Admin Control Panel (ACP), go to “Install Add-on” and install from file on server: library/EWRporta/addon-EWRporta.xml
  • In your ACP, go to Home > Options > [8wayRun.Com] XenPorta (Portal) and configure the given options.
  • Once installed you should see a “XenPorta” option in the left column of your ACP.
  • To add modules to the portal, click on “Blocks” and install the desired blocks as described below in How do I add extra blocks?
  • To customise the layout, drag and drop the modules you wish to display into the positions where you want them to show. Do not forget to press “Save changes” to save your configuration. In 1.5 the layout functionality has been greatly increased and instructions can be found below in What are Layouts?
----------------------------------------------------------------------------------------------------​

Installation instructions for XenPorta 1.4
  • Download the attached .zip package, and extract its contents.
  • Upload the entire contents to the root of your XenForo installation via FTP.
  • In your XenForo Admin Control Panel (ACP), go to “Install Add-on” and install from file on server: library/EWRporta/addon-EWRporta.xml
  • In your ACP, go to Home > Options > [8wayRun.Com] XenPorta (Portal) and configure the given options.
  • In your ACP, configure your user group permissions at Users > User Group Permissions, allowing yourself permissions to administrate the portal.
  • Navigate to your portal page at http://domain.com/portal. If your permissions are set properly, you should see two links:
    • Administrate Modules
    • Customize this page
  • If you can see these links, you have correctly configured the permissions for yourself and can administrate the portal.
  • To add modules to the portal, click on “Administrate Modules”. In the grid that appears, drag and drop the modules you wish to display into the positions where you want them to show. Do not forget to press “Update Module Order” to save your configuration.
  • The “Customize This Page” allows user groups who have been granted permission to customize the portal to rearrange the modules to a setting of their own liking. Any customization made by a member affects him only and does not override the default layout of the portal as set by the Administrator.
----------------------------------------------------------------------------------------------------​

General upgrade instructions
  1. Upload the files for the newer version into their respective /library and /js folders of your XenForo installation.
  2. Go to Home > List Add-ons > [8wayRun.Com] XenPorta (Portal) and under “Controls”, click “Upgrade”.
  3. Now in the text box for “Upgrade from file on server:”, put: library/EWRporta/addon-EWRporta.xml and press “Upgrade Add-on”.
 
Change log for the current stable version of XenPorta​
​
Version 1.5.2 Changelog
  • Moved images from the JS directory to STYLES. This is for CDNs.
  • Added "category" feature so that articles can be tagged and sorted.
  • Articles and categories can now have their own custom layouts.
----------------------------------------------------------------------------------------------------​

Version 1.5.1 Changelog
  • Added support for XenForo 1.1 functions such as ignore/warn on article pages.
  • Threads can now be viewed with their default format by appending ?format=default to the URL.
  • Fixed a bug where blocks would appear twice on article pages (they will now appear above the page-nav).
  • Removed portal canonicalization (caused issues for people who didn't use the index controller option).
  • EWRporta_ViewPublic_ArticleView class has become redundant and can be deleted.
​
----------------------------------------------------------------------------------------------------​
Version 1.5.0 Changelog

This is a COMPLETE OVERHAUL of XenPorta... because of this, all previous versions of XenPorta MUST be uninstalled before installing this new version. As well, don't forget to remove the appropriate files from the /js and /library folders before uploading the new files. IN ADDITION, check your database and make sure all EWRporta tables have been dropped.

The entire administration of XenPorta has been moved out of the public controller and into the admin controller. The new sections for modifying your XenPorta settings can be found in your adminCP for any administrators with the "option" and "node" permissions. If you are running your forums in debug mode, you may also edit blocks and their options directly if you have the "addOn" permission... as well as create new blocks as needed.

Template locations for all blocks have changed. In the past, it would have been at "EWRporta_Blocks_RecentNews" (for the RecentNews block). Now its at "EWRblock_RecentNews"; you can have multiple templates for each block. Any templates, admin_templates, listeners or phrases (yes, blocks can now be phrased!) that begins with "EWRblock_RecentNews" will be linked to that block and tied directly to it; it will be exported/imported, installed/uninstalled with that block.
  • Block: Amazon - block has been added. Here you can input Amazon product IDs with your Amazon affiliate tracking ID and hopefully make some extra revenue for your website.
  • Block: Donations - block has been added. I was originally planning on making this a $10 premium block; but I've decided to leave it for free as an example of what you could do with this new block system in XenPorta. If you still want to donate though, I would appreciate it!
  • Block: EventsStream - block has been added. You can enter the ID of your XenAtendo event, and when it goes live, the stream embed will be placed in this block. Only ONE event stream will be shown at a time, following an top down hierarchy. For instance, if you list TWO events, and the second event is a 24/7 stream, it will be shown automatically when the first event is not live.
  • Block: OnlineUsers - option has been added to disable "staff online now".
  • Block: RecentNews - promotion system has been completely changed. Now when you promote a thread, you can specifically select what type of preview icon you wish for it to have. The "date" block will no longer be shifted around automatically... it is instead an option for this block.
  • Block: RecentSlider - option has been added to slide down news excerpts.
There are several new options in the XenPorta AdminCP for Globalizing Layouts and Custom Layouts... I will not explain these features here, as they are explained in the AdminCP.

You will need to add these template edits manually if you plan on Globalizing Thread and Forum Layouts respectively... as these hooks do not yet exist in XenForo and I'm having trouble convincing Kier to add them.

At the absolute bottom of "thread_view"
Code: 
<xen:hook name="thread_view_share_after" params="{xen:array 'thread={$thread}'}" />

At the absolute bottom of "forum_view"
Code: 
<xen:hook name="forum_view_pagenav_after" params="{xen:array 'forum={$forum}'}" />
 
Blocks​
​

What are blocks?

Blocks (or “modules”) are the basic components of XenPorta which can be easily arranged to customise your portal homepage (and through the use of additional “layouts” can be integrated into the rest of your XenForo site). These provide functionality such as displaying the recent threads from designated news forums, providing information on who’s online and integrating with the other 8WR addons such as XenCarta (wiki) and XenHabla (chatroom).

Block Configuration

As a minimum all blocks are configurable to set usergroup permissions and cache time but some blocks also have additional configuration options. The configuration page can be accessed by clicking the block name in the ACP here: admin.php?ewrporta/blocks

Block positions

Blocks can be placed in a variety of positions as shown below but it should be noted that some blocks are specifically designed for either central or sidebar positions and may not display correctly if placed elsewhere.

View attachment 22089

How do I add extra blocks?

There are various additional official blocks available for XenPorta that aren’t installed by default as well as community-created blocks that can be installed (e.g. a simple HTML block). These can be installed by clicking “Install Block” on admin.php?ewrporta/blocks. Note that it is the XML file you install, not the PHP file.

Where are the XML files for the additional official blocks?

Some modules (e.g. donations) are not installed by default but are contained within the XML Addons directory and must be installed by the user. To install any additional modules, simply navigate to XenPorta -> Blocks in the ACP (admin.php?ewrporta/blocks), click “Install Block” and either specify the location locally or on your server.

Which block is this?
e.g. Which block shows the thread “slideshow”?

Below is a list of the most common XenPorta Blocks with a brief description of what they do.

RecentNews

The recentnews block allows you to pull threads from specified forums and display them on your portal homepage as news articles. An example of this can be seen below from 8WR:

View attachment 22088

Threads not in your specified news forums can also be “promoted” to display as news items using the “Promote thread” button. News items are sorted by date so the promotion option allow you to specify the date as well as the icon used on the portal homepage (either an attachment or the users avatar).

RecentSlider

The recentslider block will pull any post from your specified recentnews forums that contains an attachment named slide.jpg (note the file just needs to be attached, not actually embedded in the post) and displays the attachment and post summary within a slidershow-type box.

View attachment 22087

RecentThreads

Sometimes confused with RecentNews, RecentThreads simply displays the latest thread titles from the specified forums. Typically this block is more suited to the sidebar in contrast to RecentNews which acts best in the central position.

Donations

The donation block allows you to set individual “drives” with their own specified goals and associated paypal email addresses. You can also set the default donation amounts and currency from the block configuration page.

Additional Blocks

The following blocks are large self-explanatory with only minor configuration changes (e.g. adding in social network ids) needed.

StatusUpdates - shows recent status updates and allows users to update their status directly from the block
SharePage - Allows the page to be shared on social media sites
Twitter - A twitter block
Facebook - A facebook block
BoardTotals - shows statistics such as total number of threads, users, etc
OnlineUsers - shows number of users online
ChatUsers - integrates into XenHabla (IRC Chatroom) and displays the number of users in the room

Guide to creating add-on blocks/modules for XenPorta

Instructions for creating your own blocks / modules are located here but please note that since 1.5, the block system has been moved completely to the ACP and hence these instructions are now out of date.

Please note that as of XenPorta 1.5, modules are now called blocks.

A guide, along with a list of available community-created modules which have been tested and are compatible with XenPorta 1.5, may be found below.

Community-Created Blocks

With the release of XenPorta 1.5, the majority of older community-created blocks no longer work due to the change in the block-creation system. If you have released a block and would like it mentioned here please let us know.

The blocks listed below have been tested and work in XenPorta 1.5:

HTMLBlock - by boban - Basic HTML block where content is created by editing the EWRblock_HtmlBlock template (see here for more details)

IncludePHP - by boban
 
Layouts​

What are Layouts?

Layout are simply the positions assigned to your blocks and specify which blocks are displayed. It’s possible to customise XenPorta to add different layouts for different parts of your site (for example, showing Who’s Online at the bottom of your forum index but showing it in the sidebar on your homepage).

Jaxel covers Layouts in more detail here

How do I create a new layout?

If you want to create a new layout so that the position of your blocks is different on different parts of your site compared to your homepage this can be achieved with the following.
  • Admin Control Panel - XenPorta options
  • Tick "Forum (forum-# > forum)" (or thread if you want it for a specific thread)
  • Go to layout, set type as “Forum”
  • By default this will apply to all forums, if you want the layout for a specific forum, simply enter the forumid
  • Click customise new layout.
  • Change the new layout block positions to what you want and save it.
The same procedure allows you to create a customised layout for the generic threadview and even for specific threads (using the threadid).

As detailed by Jaxel here, you will need to add these template edits manually if you plan on Globalizing Thread and Forum Layouts respectively:

At the absolute bottom of "thread_view"
<xen:hook name="thread_view_share_after" params="{xen:array 'thread={$thread}'}" />

At the absolute bottom of "forum_view"
<xen:hook name="forum_view_pagenav_after" params="{xen:array 'forum={$forum}'}" />

Can I use layouts to create multiple portal pages?

Yes, this is done simply by defining a new layout as above but not specifying a type and setting the id to whatever you want the new portal page to be named (e.g. news). This additional portal layout can then be accessed from /portal/{layout}/index (e.g. (/portal/news/index).
 
Frequently Asked Questions (applies to both XenPorta 1.5 and 1.4 unless indicated)​

This section covers most of the questions that have been repeatedly asked throughout the add-on thread.

After installing XenPorta, how can I access the portal page?

The default portal page can be accessed at http://domain.com/portal


My portal page is at http://domain.com/portal. I would like it to be located at http://domain.com. How would I do this?

In your XenForo APC, go to Home > Options > [8wayRun.Com] XenPorta (Portal) and enable by checking the option “Set as Index Controller”. Save this change.


After installing XenPorta, I have two “Home” tabs in the navigation bar, one pointing to my home page and the other pointing to the portal. How can I fix this to have only one “Home” tab that points to my portal page?

To fix this, in your XenForo ACP go to Home > Options > Basic Board Information and clear the “Home Page URL” field. Doing so will remove the “Home” tab pointing to your home page and the remaining “Home” tab shall point to your portal page.


What does the “Set as Index Controller” feature do?

As the description below it says, it moves the forums to /forum (e.g. http://domain.com to http://domain.com/forum/) and sets the /portal/ page to be the index (e.g. http://domain.com/portal/ to http://domain.com/)


What does the “Break out of Content Container” feature do?

When disabled, you start out with this...

1.webp​
​
You enable the switch.​
​
2.webp​
​
And you get this.​
​
3.webp​

What do the (O) and (Export) links in the layout administration do? (XenPorta 1.4 only)

The (O) clears the cache whereas (Export) exports the XML of that particular module. (Source)


How can I create a module for custom HTML?

Some examples of this code can be found (1) here, (2) here and (3) here.


How can I remove the site name beneath the breadcrumb navigation on the portal and forum list?

In order to remove the site name on the portal, use this solution.

In order to remove it from the forum home, use this solution.


How do I get the Slider working?
  • In RecentNews Module Settings, add a forum you want to be displayed on the portal (if you have not already done so).
    Create a thread in this forum and attach an image called slide.jpg to the first post. Every thread in this particular forum with an attachment named "slide.jpg" will be displayed in the portal slider.
  • The picture does not need to be aligned, just attached.
  • Now import one of the sliders module you want. There are two sliders:
    • RecentSlider
    • AccordionSlider
Both can be located at /library/EWRporta/XML_Addons/​
  • Place the choosen Slider Module to the top of your Portal Site.
  • And thats it. (Source 1 and Source 2)
How do I add a notice to JUST the portal pages?

Follow Brogan’s advice here to find the template and then simply set this template as one of the notice criteria as demonstrated here.


Can I have two or more RecentNews Blocks, each pulling threads from different forums?

Yes, this is possible.

1. Export the RecentNews.xml file. Open it and add 1 after every instance of recentnews, such as:
  • RecentNews1
  • recentnews1_forum
  • recentnews1_limit
  • recentnews1_truncate
  • recentnews1_social
  • recentnews1_pagenav
  • recentnews1_leftdate
  • EWRblock_RecentNews1
  • EWRblock_RecentNews1.css
  • $RecentNews1
  • EWRblock_RecentNews1.css
2. After making these changes to the .xml file, save it as RecentNews1.xml but do NOTupload it yet.

3. In case you want more than one extra RecentNews block, change the 1 to 2 and so forth for each block.

4. Open /library/EWRPorta/Block/RecentNews.php. Make a copy of RecentNews.php and rename it to RecentNews1.php.

5. Open RecentNews1.php and change:
class EWRporta_Block_RecentNews extends XenForo_Model
to
class EWRporta_Block_RecentNews1 extends XenForo_Model

Save and close.

6. Make sure you have the RecentNews1.php uploaded to /library/EWRporta/Block/. Now upload your edited RecentNews1.xml via your admin control panel into the blocks section.


Is there a way to include the thread prefix in the news title on the RecentNews block?

Yes, there is.

Search in block EWRblock_RecentNews template for:
Rich (BB code): 
                             <a href="{xen:link threads, $news}" class="newsTitle">{$news.title}</a>

Replace it with:
Rich (BB code): 
                             <xen:if is="{$news.prefix_id}">
                                <xen:if is="{$linkPrefix}">
                                    <a href="{xen:link forums, $forum, 'prefix_id={$news.prefix_id}'}" class="prefixLink">{xen:helper threadPrefix, $news, html, ''}</a>
                                <xen:else />
                                    {xen:helper threadPrefix, $news}
                                </xen:if>
                            </xen:if>
                            <a href="{xen:link threads, $news}" class="newsTitle">{$news.title}</a>

Continued below...
 
Commonly Encountered Issues/Problems

General Advice

Styling changes should be made to extra.css where possible to maintain compatibility with future releases. Edit the templates at your own risk.

The contents from first page of my RecentNews block has disappeared

This can be resolved by clearing the cache of your RecentNews block.

Changes made to the layout in the ACP are not taking effect

The most common cause of this is that you have previously selected to “customise” the portal via the frontend. The customise link allows the layout to be altered on an individual user basis and only applies to yourself, hence you fail to see the changes to the default layout. This is in contrast to the layout options in the ACP which set the defaults. To solve this, on the customise page, click revert.

My attachment isn't showing in the RecentSlider

For guests to view the image, the original thread/attachment must be viewable to guests. In addition, the attachment image name is case-sensitive (i.e. by default it must be named slide.jpg not slide.JPG)
 
Frequently Asked Questions (continued)​


How do the [prebreak] tags work?

This has been very nicely explained by Yorick.

On the portal, everything in the article up to the [prbreak] tag will be visible in plain text, whereas the text between the [prbreak] and [/prbreak] tags will appear as a link to the forum thread. All text after the closing [/prbreak] tag will not appear on the portal.

So, in the thread, if you have something like...

This is line 1 of my article.
[prbreak]Continue reading[/prbreak]
This is line 2 of my article and so on.

On the portal, this will be visible as:

This is line 1 of my article.
Continue reading {This will be a link to the forum thread}

In the thread, it will be visible as:
This is line 1 of my article.
This is line 2 of my article.

If you would like to simply break the article at a particular point, just insert the [prbreak][/prbreak] tags and leave the space between them empty. This will just break the article at that point without hiding anything.
 
Status
Not open for further replies.

Similar threads

Saeed
  • Locked
XenPorta User Guide and FAQ
Replies
5
Views
46K
RobParker
R
Back
Top Bottom