Invision Community Blog: Community Management

Theme Tip: Using custom template bits

Thu, 01 Jan 1970 00:00:00 +0000

We frequently encourage people to use custom CSS files when designing their themes. The reason for this is simple: it makes upgrading your site much easier because IPS4 can apply any changes to its own CSS files, and will leave your custom CSS files untouched. If instead you made edits to IPS4's CSS directly, it wouldn't be able to upgrade them automatically, which means more work for you, and a potentially broken UI on each upgrade.

Something that's not quite as common, but that we still strongly suggest, is using custom template bits as much as possible. The most common template you'd edit is globalTemplate, perhaps to include some extra resources in the , a custom header, and maybe some footer pieces. The usual approach would be to simply add all of that custom HTML directly into globalTemplate, but my recommendation is that you instead create each piece as a custom template bit, and then include it.

With templates, it's not quite as much of a clear-cut benefit as with CSS; you'll still need to modify the original template in order to include your custom pieces of course. But there's still good reasons for doing so; it keeps your template as clean as possible, meaning if in a later upgrade you have to revert it to get the latest changes, reapplying your custom pieces is easy - you just add the template includes back in.

We've been taking this approach with all custom themes we've created since IPS4's release (dozens by my last count). We try and keep the naming convention consistent too. All custom templates are named _customABC.phtml and exist in the /front/global/ group in the core application. This puts them in an easy-to-find location, and because of the underscore prefix, they're shown at the top of the directory.

Example custom template bits in a custom theme

Using them is simple:

{template="_customHeader" group="global" app="core"}

I hope this approach helps you keep your templates clean and more manageable! If you have any tips for working with your templates, please share them in the comments!

Theme Tip: Advanced uses for Pages database fields

Mon, 18 Apr 2016 13:06:17 +0000

Our Pages app includes a powerful feature that allows you to create your own databases within the community. Within each database, you create custom fields (we support a number of custom types, from plain text fields, to YouTube embeds and more). And while we provide some generic, simple templates to display your data, custom templates allow you to more precisely control how your database looks in a manner best suited to your site.

Anyone who has created a Pages database will be familiar with using custom fields. You may have created a field for the title of your item, or an upload field so that the item contains a file for users to download. But beyond these straightforward uses, I wanted to explore some more advanced uses of custom fields. Fields don't necessarily have to be displayed to the user - or at least not in the usual way. We can use them as configuration options for our record display, or manipulate the data in order to show it in a different way. Let's take a look at some examples.

1. Adding an optional badge to records

We'll start with a fairly simple example. In our Guides section, we highlight guides that have a video tutorial by showing an 'Includes Video Guide' label on the listing:

We achieve this simply by having a Yes/No field that we turn on as needed. In the field format, we turn the Yes/No value into the label by setting the format to Custom and using this code:

{{if $formValue == 1}}
	 class='ipsType_medium'> class='fa fa-video-camera'> Includes Video Guide
{{endif}}

2. Using fields as a way to configure the record display

Fields don't necessarily need to be shown to users. Instead, we can use them as a means to configure the record display, giving us some really powerful flexibility in how we show records. In this contrived example, I'm going to create a field that changes the background color of the content.

Create a Select Box field. Each option key will be a hex color, while the value will be the name the record creator will choose.
Set the field key to record_background
Set the field formatting to Custom, and the format to simply: {$formValue}. This means it will output our hex value instead of the color name.

In the display template assigned to this database for records, we can use the field like so:

 style='background-color: #{$record->customFieldDisplayByKey('record_background', 'listing')|raw}' class='ipsPad'>
  ...rest of the template...

Now, when you create a record, you can choose a color and that color will be used when the record is shown:

You can use this approach in others ways - toggles to control the layout of the record, or options for grid sizes, or even take an upload field for images and set the background of an element as that image.

3. Pass data to 3rd-party integrations

Pages has built-in support for several 3rd party integrations, such as Spotify, Soundcloud, YouTube and Google Maps. But using custom fields, you can pass data to other services too. Let's say we wanted to embed an iTunes album widget into each of our records - perhaps the album is relevant to the Pages record in some way and we hope to encourage some click-throughs. In this example, we'll use the embed.ly service.

Create a URL custom field.
Set the field key to itunes_album

Set the field formatting to Custom, and the format to:

 class="embedly-card" href="{$formValue}">iTunes Album
 async src="//cdn.embedly.com/widgets/platform.js" charset="UTF-8">

In your database display template, position the field as desired by adding:
```
{$record->customFieldDisplayByKey('itunes_album', 'listing')|raw}
```

Now when you add an iTunes album link to your record, you'll get an embed automatically!

This approach is great for a range of uses. Perhaps you have an Amazon Associates account and want to add a relevant product link to each of your records so that you earn a commission when users click through. Using database fields and templates in this way, it's easy to set up.

I hope that's given you some ideas of other ways you might use database fields in Pages. Share any interesting uses you've come up with in the comments!

Theme Tip: Using Pages blocks anywhere

Mon, 11 Apr 2016 13:02:41 +0000

Blocks are an extremely popular feature in IPS4, used by a huge number of customers to great effect. They range from feeds of topics, to statistics, to custom blocks that can contain anything you wish. They're a great way to add dynamic content to your community theme.

What many people don't know is that blocks you create with Pages can be used anywhere in your theme, not just in the designated block containers (in the header, footer & sidebar).

The {block} tag

It's really easy to do so. Here's the tag you'd use:

{block="block_key"}

That's it! The block_key is the one you specify when you're creating the block in Pages (if you don't specify one manually, Pages will auto-generate one for you).

Where can you use them?

Block tags can be used anywhere that template logic is supported. That includes:

Theme templates
Pages page content
Other kinds of templates (e.g. database templates)
Even within other blocks!

What can you do with them?

The obvious benefit of blocks is that they are reusable, so in any situation where you need the same content duplicated, it makes sense to put the content in a custom block instead, and simply insert it wherever needed. Then if you need to update the content later, you have one place to do so. Custom menus are a great example of reusing blocks; since blocks have full use of template logic, you can build your menu HTML in a block, use HTML Logic to highlight the correct item, and insert the menu block on each of your pages. We use this approach on our feature tour section menu. Here's a snippet of the menu block HTML for that page:

 id='elTourNav'>
	 class='container'>
		 class='ipsList_inline'>
			 href='/features/apps' {{if \IPS\Request::i()->path == 'features/apps'}}class='sSelected'{{endif}}>Our Apps
			 href='/features/engagement' {{if \IPS\Request::i()->path == 'features/engagement'}}class='sSelected'{{endif}}>Engagement

Blocks are useful beyond that, though. A couple of weeks ago, we showed you how to use HTML Logic to only show content to certain groups. Using blocks is actually an easier way to do this - simply add the content to a custom block, then check the groups who should see it. We use this technique to show a 'welcome to our community' message to guests on our own community. We created our welcome message as a custom Pages block, set it so that only guests have permission to view it, and then added it to our template header. Simple, effective and easy to manage.

That's just two ways you can use blocks - there's many other creative users too! If you've used blocks in an interesting way, share your example in the comments!

7 ways to secure your community

Tue, 05 Apr 2016 16:00:00 +0000

Security should never be an afterthought for your community. All too often, site owners consider beefing up their security only when it's too late and their community has already been compromised. Taking some time now to check and improve the security of your community and server could pay dividends by eliminating the cost and hassle of falling victim to hacking in the first place.

Let's run down 7 ways that you can protect your community with the IPS Community Suite, from security features you may not know about to best practices all communities should be following.

1. Be selective when adding administrators

Administrator permissions can be extremely damaging in the wrong hands, and granting administrator powers should only be done with great consideration. Granting access to the AdminCP is like handing someone the keys to your house, so before doing so, be sure you really trust the person and that their role requires access to the AdminCP (for example, would moderator permissions be sufficient for the new staff member?).

Don't forget to remove administrator access promptly when necessary too, such as the member of staff leaving your organization. Always be aware of exactly who has administrator access at any given time, and review regularly. You can list all accounts that have AdminCP access by clicking the List Administrators button on the System -> Security page.

2. Utilize Admin Restrictions

In many organizations, staff roles within the community reflect real-world roles - designers need access to templates, accounting needs access to billing, and so forth. IPS4 allows you to limit administrator access to very specific areas of the AdminCP with the Admin Restrictions feature, and even limit what can be done within those areas. This is a great approach for limiting risk to your data; by giving staff members access to only the areas they need to perform their duties, you reduce the potential impact should their account become compromised in future.

3. Choose good passwords

This seems like an obvious suggestion, but surveys regularly show that people choose passwords that are simply too easy to guess or brute force. Your password is naturally the most basic protection of your AdminCP there is, so making sure you're using a good password is essential.

We recommend using a password manager application such as 1password or LastPass. These applications generate strong, random passwords for each site you use, and store them so that you don't have to remember them.

Even if you don't use a password manager, make sure the passwords you use for your community are unique and never used for others sites too.

4. Stay up to date

It's a fact of software development that from time to time new security issues are reported and promptly fixed. But if you're running several versions behind, once security issues are made public through responsible disclosure, malicious users can exploit those weaknesses in your community.

When we release new updates - especially if they're marked as a security release in our release notes - be sure to update as promptly as you can so you receive the latest fixes. Your AdminCP will also let you know when a new version is ready for download.

5. Use .htaccess protection for your AdminCP

In addition to IPS4's own AdminCP login page, you can set up browser-level authentication, giving you a double layer of protection. This is done via a special .htaccess file which instructs the server to prompt for authentication before access to the page is granted. IPS4 can automatically generate this file for you - simply go to System -> Security in your AdminCP, and enable the "Add a secondary admin password" rule.

And it should go without saying, but to be clear: don't use the same username or password for both your .htaccess login and your admin account, or the measure is redundant!

6. Restrict your AdminCP to an IP range where possible

If your organization has a static IP or requires staff members to use a VPN, you can add an additional layer of security to your community by prohibiting access to the AdminCP unless the user's IP matches your whitelist. This is a server-level feature, so consult your IT team or host to find out how to set it up in your particular environment. If you're a Community in the Cloud customer, contact our support team if you'd like to set up this protection for your account.

7. Properly secure your PHP installation

Many of PHP's built-in functions can leave a server vulnerable to high-impact exploits, and yet many of these functions aren't needed by the vast majority of PHP applications you might run. We therefore recommend that you explicitly disable these functions using PHP's disable_functions configuration setting. Here's our recommended configuration, although you or your host may need to tweak the list depending on your exact needs:

disable_functions = escapeshellarg,escapeshellcmd,exec,ini_alter,parse_ini_file,passthru,pcntl_exec,popen,proc_close,proc_get_status,proc_nice,proc_open,proc_terminate,show_source,shell_exec,symlink,system

Another critical PHP configuration setting you need to check is that open_basedir is enabled, especially if you're hosted on a server that also hosts other websites (known as shared hosting). If another account on the server is comprised and open_basedir is disabled, the attacker can potentially gain access to your files too.

Naturally, Community in the Cloud customers needn't worry about either of these steps - we've already handled it for you!

So there we go - a brief overview of 7 common-sense ways you can better protect your community and its users. As software developers, we're constantly working to improve the behind-the-scenes security of our software, but as an administrator, there's also a number of steps you should take to keep your community safe on the web.

If you have any tips related to security, be sure to share them in the comments!

Theme Tip: Create custom error pages with the Pages app

Mon, 04 Apr 2016 12:24:53 +0000

When IPS4 encounters an error (be it a simple 404 Not Found or a more complex configuration issue), the user sees a standard built-in error page. That's fine in many cases, but did you know you can create your own error page using our Pages app?

This is a particularly good approach for communities that use Pages for their website too. If you have built a website theme, the standard error page may not fit with your visual style, so building your own error page allows you to improve it. You might want to show some helpful links to other parts of your website, for example.

Creating your error page

The first step is creating your error page in Pages. Note that for this page, you must create a manual page - the Page Builder tool can't be used in this case.

In order to show the error on your page, there's two special tags you should insert in the page content. When your page is shown in response to an error, Pages will swap out these tags for the relevant text. They are:

{error_code}
Replaced with the technical error code for this error. This code identifies the exact piece of code that triggered the error, and can be given to IPS support technicians to help diagnose problems.
{error_message}
Replaced with a human-friendly description of the error that occurred.

Configuring Pages to use the error page

Next, set Pages to display the error page. You do this in the Pages section; click the Advanced Settings button, and select your page from the list. Note that this will replace all error pages across the suite - not just errors triggered by Pages itself!

Have a request for a theme tip? Let us know in the comments and we'll try and help out in a future tip!

Theme Tip: Use HTML logic to display content to specific groups

Mon, 28 Mar 2016 12:29:32 +0000

HTML Logic is our name for the additional tags available in IPS4's templates that allow runtime logic to be executed. It comprises if/then/else statements as well as loops and more.

Since HTML Logic has access to all of the underlying PHP framework in IPS4, it's very powerful and a lot can be achieved with it. One common use is to limit certain content within a template to particular member groups. Let's see how that might be done.

Showing or hiding content only to guests

We'll first look at a simpler idea: showing or hiding content specifically to guests (i.e. anyone who isn't logged in). Within IPS4, the \IPS\Member::loggedIn() object contains information about the current user. Guests always have a member_id of NULL (i.e. no value), so we can simply check that value in our logic tag:

{{if \IPS\Member::loggedIn()->member_id === NULL}}
	This content *only* shows to guests, since they have a NULL member_id.
{{endif}}

{{if \IPS\Member::loggedIn()->member_id}}
	This content *only* shows to logged-in users since their member_id is a number, which will equal true.
{{endif}}

Showing content only to specific groups

Let's go a bit further and this time show content to specific (primary) member groups. First, you need to get the IDs for the group(s) you want to deal with. You can find this by editing the group in the AdminCP, and making a note of the id parameter in the URL. On my installation, the Administrator group is ID 4 so we'll use that in our example.

Once again, we're using the \IPS\Member::loggedIn() object, but this time we're using the member_group_id property.

{{if \IPS\Member::loggedIn()->member_group_id === 4}}
	This content only shows to members in the "Administrators" group (ID 4 in our example)
{{endif}}

Working with multiple groups at once

Following the code above, you could simply repeat the check against \IPS\Member::loggedIn()->member_group_id several times, for each ID you want to allow. However, since our templates allow arbitrary PHP expressions to be used, there's a neater way: use an array of member group IDs you want to allow, and check against that using PHP's in_array function. Here's an example where we only show content to group IDs 2, 4 and 6:

{{if in_array( \IPS\Member::loggedIn()->member_group_id, array( 2, 4, 6 ) )}}
	This content only shows to members in groups with the ID 2, 4 or 6.
{{endif}}

Have a request for a theme tip? Let us know in the comments and we'll try and help out in a future tip!

Theme Tip: Apply CSS to specific Pages databases

Thu, 01 Jan 1970 00:00:00 +0000

When you use custom templates for a Pages database, you'll often need custom CSS to go along with it to provide the styling. There's two main ways of doing this:

CSS files within Pages

Pages allows you to create CSS files, and then associate them with particular custom pages of your community (you create these in the AdminCP, under Pages > Templates > CSS). So simply create your CSS file, and associate it to the page that your database is displayed on.

The benefit of this method is it applies to all themes, so it's great if you want your database to look the same on all themes. Of course, this is also the drawback - you can't easily use it for per-theme customization.

Targeting the database classname in theme CSS

Alternatively, you can target the database classname in your normal theme CSS files. When a database is inserted into a page, IPS4 helpfully adds a classname to the body element, which makes it really simple to style that page in particular. If your database key is myDatabase, then the classname added to the body element would be cCmsDatabase_myDatabase. Use this in your selectors and you can style everything exactly how you need:

.cCmsDatabase_myDatabase .ipsButton_important {
  /* Style important buttons differently in this database, for example */
}

Combine both methods!

Of course, you can use both approaches when it makes sense. Create a CSS file within Pages for the basic structural styling that will apply regardless of which theme the user uses, and then in each theme target the database classname to customize it for that particular theme - perfect for the colors, font family and so on.

Theme Tip: Twitter Embed Block

Mon, 14 Mar 2016 13:06:00 +0000

Several clients have asked how we placed the Twitter feed block on the sidebar of our News page. It's really quite easy and a great demo of how you can place custom HTML in our system. Here is how it was done:

Get the embed code from Twitter
Create a custom HTML block in our Pages app
Drag and drop that block into the sidebar

That really is it! Here is a video walkthrough:

This is a basic example of a custom HTML block that you can use in so many different ways. You could create a "call to action" the only shows to Guests to get them to register. You might also create text that only displays to your staff with quick links to areas they need.

Here we demo dragging the block into the sidebar. You can also put blocks right in theme templates and use them in many more ways. That will be covered in future theme tips.