XenPorta User Guide and FAQ

XenPorta User Guide and FAQs

Introduction

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

Throughout the original add-on thread, which has already gone beyond 175+ pages, users have been seen asking questions pertaining to the same problems repeatedly. Although this can easily be avoided by using the “Search within thread” feature, newer members installing the add-on infrequently do so and the thread has been growing longer unnecessarily with posts about issues already discussed, rather than posts about issues with the latest versions only.

Keeping this in view, 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 post on this thread and we shall have a look at it.

To make this guide easy to read and navigate through, it has been divided into the following sections:

• Installation and Upgrading instructions for XenPorta (1.5 and 1.4)
• Changelog for XenPorta 1.5+
• Blocks
• Layouts
• Frequently Asked Questions (applies to both XenPorta 1.5 and 1.4 unless indicated)
• Commonly Encountered Issues/Problems

======================================================================

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, deleteall 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

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.



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:



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.



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

You enable the switch.

And you get this.

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?

Two examples of this code can be found here and 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:

Code:

                             <a href="{xen:link threads, $news}" class="newsTitle">{$news.title}</a> 

Replace it with:

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>

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)