• IP.Board 3.4.6
• IP.Nexus 1.5.9
  

• The editor, both within IP.Board (topics/posts) and in other areas (such as IP.Content articles, IP.Blog entries, etc.). Pay attention both to the editor itself (i.e. when typing out and formatting your post, and toggling the editor back and forth) and the final post that is submitted.
• URLs that are submitted with a post being automatically turned into a link correctly.
• Any IP.Nexus functionality that has to do with grouped renewals.
  

{{if theme.rounded_photos}}
.ipsUserPhoto {
border-radius: 100px
}
{{endif}}

Or, if you want to use it without an IF clause, then you can simple use this:

<div>
{theme="rounded_photos"}
</div>

You can manage the custom settings from the theme edit form. In this screen shot, the tabs "Custom" and "Colors" are theme setting tabs.



Version Check
We've added the ability for theme creators to include a URL that is checked multiple times a day. All you as the theme creator needs to do is return a simple JSON object like this example:

{
    "version": "4.0.1",
    "longversion": 40001,
    "released": 1377688587,
    "updateurl": "http://www.exampleurl.com/announcement.php?theme=xeonblue"
}

This is a great way to notify your customers about updates to your themes.



More information is displayed when you mouse over the "Update available" badge.

Designer's Mode
There are times when you want to change many template bits and CSS files using your own development tools. The new ACP template and CSS editor is great for making edits now that it supports full syntax highlighting but for more advanced work you'll want to work with your favourite IDE and make use of its tools such as file compare and searching.
In IP.Board 3 we have the WebDav interface which allows you to work with plain .html and .css files but because it's sent over HTTP and each item needs recompiling to show changes, it's often a little sluggish and can be frustrating to work with if connection speeds start to suffer.

In IPS Social Suite 4 you can work with plain .html and .css files locally; there's no need to fire up a WebDav client. You enable designer's mode by adding a constant into constants.php. This will automatically write out the HTML and CSS files into a directory called "themes" right in your suite's root folder. You can edit these files and the changes are instantly applied to the suite making working very fast indeed.



Once you're done working in designer's mode, simply sync back the changes using the menu item on the theme's row and remove the constant.



This will copy the changes back to the database and remove any stale compiled templates and CSS files.

Diff
It's often very useful after upgrading to see which template bits have changed. The new "diff" tool instantly provides a list of changed, deleted or added template bits and CSS files. You can even download a copy as a stand-alone HTML file to distribute with your theme sets.



These advanced tools will make creating themes for IPS Social Suite 4 easier than ever before. We look forward to seeing what you create with them!

• Files uploaded by users get put in the /uploads directory. If you have a complicated setup, it's difficult to handle these. If you have a load-balanced cluster you need to set up an environment whereby all files are stored on a single server, or all uploaded files are synched between servers, but serving these files over a high-performance CDN can be difficult.
• CSS, JavaScript files, images and emoticons get put in /style_* directories. If you want to serve these over a CDN, you can do so, but you need to copy the files over yourself.
• Other pieces of data are written to disk as a caching mechanism. This has the same issue with load-balanced environments as file uploads.
• Some applications had other methods - for example, IP.Downloads allows you to store files on a remote server using FTP.
  

• On a local server
• On a remote server using FTP (which you can use to upload files to many CDN services)
• As binary data in the database
• On Amazon S3
  

• APC
• eAccelerator
• Memcached
• Wincache
• XCache
  

{{if member.isAdmin()}}
{template="admin_bar"}
{{endif}}

You can now put the conditional inside the template tag like so:

{template="admin_bar" if="member.isAdmin()"}

This is much easier to read and reduces a lot of visual clutter. The combination of the better template syntax and HTML 5 mark-up results in a dramatic reduction in size and complexity of often edited templates such as the globalTemplate which is commonly used to add your own site chrome.

The screenshot below shows all of the IPS Social Suite 4 globalTemplate and for comparison, part of the IP.Board 3.4 globalTemplate which is over 340 lines long!


The CSS framework much like the javascript framework has been completely rewritten and is now modular. This means that most CSS files are very small which makes looking for specific selectors much easier. In addition, upgrades are less destructive to your themes. If you made edits to the button styles, then only that one style sheet is altered leaving the rest as default. Of course, IPS Social Suite combines and minifies these separate CSS into fewer files when saved.

This blog entry is just an overview of the theme section in the Admin CP. We'll go into more detail in a later entry on the new tools available designed to make theme creation and management a breeze for theme authors. We know you will have a ton of questions but please be patient with us if we keep saying "wait for next blog entry" :smile:

<?php

namespace IPSContentShareServices;


class _Servicename
{
    /**
     * @brief    URL to the content item
     */
    protected $url        = NULL;
    
    /**
     * @brief    Title of the content item
     */
    protected $title    = NULL;

    /**
     * Constructor
     *
     * @param    IPSHttpUrl    $url    URL to the content [optional - if omitted, some services will figure out on their own]
     * @param    string            $title    Default text for the content, usually the title [optional - if omitted, some services will figure out on their own]
     * @return    void
     */
    public function __construct( IPSHttpUrl $url=NULL, $title=NULL )
    {
        $this->url        = $url;
        $this->title    = $title;
    }

    /**
     * Add any additional form elements to the configuration form. These must be setting keys that the service configuration form can save as a setting.
     *
     * @param    IPSHelpersForm    $form    Configuration form for this service
     * @return    void
     */
    public function modifyForm( IPSHelpersForm &$form )
    {
    }

    /**
     * Return the HTML code to show the share link
     *
     * @return    string
     */
    public function __toString()
    {
        return "<b>Some HTML</b>";
    }
}

The class name "_Servicename" should be the same as the filename, minus the _ (the underscore is part of hooks and plugins system in 4.0, which you can read about in a later blog entry). So this filename would be "Servicename.php" and would be located in /system/Content/ShareServices/. The modifyForm() accepts a reference to the form object that is displayed when configuring the service. Here, you can add new configuration options that will be saved automatically (the configuration options should be settings). If you need to specify any HTML or CSS that needs to be manually loaded for the service, you can add assets to both the <head> of the document, or insert content right before the closing </body> tag, depending upon the service's needs in the constructor. The __toString() magic method should return the HTML necessary to generate the share service link.

It is really that simple - there are no hidden "gotchas" to watch out for.

As an aside, the built in ability to email a link has been greatly simplified for third party developers as well. If you implement third party applications by extending the appropriate classes (which we will blog more about later), the ability to email a link to your page with permission checking built in will all be handled automatically for you. You don't need any plugin files specifically to facilitate emailing links to your content items in 4.0.


Implementing Sharelinks in Applications

To implement the sharelinks in your third party applications is equally simple. As mentioned above, assuming you extend the appropriate classes to generate content items (which will be blogged about in detail at a later date), you need only do two things to implement share service integration in your application.

First, your class that extends IPSContentItem must implement the interface IPSContentShareable. This automatically enables the share links in your application and adds support for any functionality the share services utilize.

Second, your template should include the appropriate sharelinks template where-ever you wish to display the share links

{template="sharelinks" group="global" location="front" params="$contentItem"}

If you wish to render the share links in some manner beyond our default generic rendering, you can simply use whatever HTML you need to, however we feel that most content items can utilize our generic template just fine.


A Few Notes in Closing

We feel that these changes will make implementing share links as easy as possible while still providing you all the flexibility you may need to customize the interaction and display of the links at every level.

We have also decided to remove the "print" and "download" share links at this time. In researching their usage and their functionality, we feel that it is no longer worth maintaining these unnecessary links which simply add clutter to the page. All browsers allow you to save a page (i.e. download it) already, and all browsers allow you to print a page already. We will include a print stylesheet with 4.0, just as we did with 3.x, so when you choose to print a page the output will be better tailored for printed media. We feel, however, that retaining the links adds no real value for the vast majority of users, and is more inline with what most users encounter on other similar websites.

We hope that the improvements and decluttered interface, both on the front end and the ACP, make configuring and using these services (and adding support for others) much simpler than in previous versions.

• Better user of space. Our current ACP uses vertical space for the main menu, and horizontal space for the application menu. In an era of widescreen desktops being standard, this could be improved.
• Get rid of dropdown menus. The main menu currently uses dropdowns for navigation, but this can be difficult to use - especially if you want access something in a 3rd party app, meaning you have to traverse the Other Apps menu.
• More consistency across pages. Our current ACP has some interactive tables (e.g. the member list) - but not every table makes use of the functionality. We should be enhancing every page with similar functionality, if it makes sense.
• Better styling. People aren't a fan of pink, it turns out. I guess it'll have to go. The blue gradients are showing their age too.
• And the big one: Better mobile support. You can't effectively use the AdminCP on a mobile device. It's time you were able to manage your entire community from your phone with all of the same functionality, right?
  

• Action overloaders - which allowed overloading the PHP class for any controller.
• Library hooks - which allowed overloading the PHP class for some (though not all) other classes.
• Data hooks - which allowed the modification of variables at specific, defined places in the code.
• Skin overloaders - which allowed overloading the compiled PHP class representing a group of templates.
• Template hooks - which allowed content to be inserted at specific points in templates.
  

• As you search for a language string, results appear as you type.
• Editing a language string saves immediately without needing to click a save button.
• Filter tabs can show you words/phrases which have not yet been translated or the translation is out of date (meaning we've changed the default English value for the word/phrase since it was translated).
  

{# [1:record][?:records]}

The # indicates where the number will go, then each set of square brackets represents a possible value - the number before the : indicating the number which will cause that to show, and ? meaning "all other numbers".

So for our Slovak example, we'd set the value to:

{# [1:článok][5:článkov][?:články]}

On display, it will automatically show the appropriate version.


Lists

Along a similar thread to pluralisation, we've also made the way lists are formatted to be customised through a special language string. For example, a list in English looks like "one, two and three". However, in Japanese, it's "一、二、三。" (the comma symbol is different and there's no "and") - similarly Arabic, Thai and others have similar differences. In 4.0, simply by changing an example language string, this can be changed.

In the default language, this language string is:

a, b and c

For our Japanese example, we'd just change it to:

a、b、c

UTF-8

Without wanting to get into too much technical detail - UTF-8 is the most common of many ways text can be encoded for storage and display on webpages. UTF-8 has been the default encoding in our software since IP.Board 3.0.

Some sites which have been around for a long while though may not be using UTF-8. This can cause issues with some features where UTF-8 encoding is expected (for example, many features which rely on JavaScript require UTF-8 due to JSON only supporting it and nothing else). In addition, some sites may try to use UTF-8, but content is actually stored differently as the database is set to a different encoding, which can also cause issues.

In 4.0, we're going all UTF-8. If you're not already on it, the upgrader will convert data. This means a much more reliable and compatible way of handling text.

IPSOutput::i()->output = new IPSHelpersMultipleRedirect(
	/* Query string which will take us back to this controller */
	'app=foo&module=bar&controller=baz&do=process',
	/* Code to run for each HTTP request */
	function( $data )
	{
		// If we're not done yet...
		return array(
			$data,				// Data to get passed back to this function,
			"Processing...",	// Message to show (via AJAX) to the user
			50,					// [Optional] Number between 1 and 100 to indicate progess for progress bar
		);
		
		// If we're done
		return NULL;
	},
	/* Code to run when we're done */
	function()
	{
		// Code that runs when we're done
	}
);

• Scheduled installation time
• Initial training & consultation by phone or live chat
• Post-deployment best practices training
• Custom migration from other platforms*
• Custom skin design*
• Custom single sign on (SSO)*
  

• Same business day ticket response
• Scheduled upgrade times
• Custom skin upgrades between versions*
• Security updates applied before public release
  

• Logs checked for signs of problems
• Advise and schedule if upgrades are available
• Database maintenance
• Settings reviewed for optimal performance
• Best practices reviews
  

		/* Init Chart */
		$chart = new IPSHelpersChart;
		
		/* Specify headers */
		$chart->addHeader( "Date", 'date' );
		$chart->addHeader( "Members", 'number' );
		
		/* Add Rows */
		$stmt = IPSDb::i()->build( array(
			'select'	=> "COUNT(*) AS count, DATE_FORMAT( FROM_UNIXTIME( joined ), '%Y-%m-%d' ) as joined_date",
			'from'		=> 'core_members',
			'group'		=> 'joined_date',
			'order'		=> 'joined DESC',
		) );
		$stmt->execute();
		while ( $row = $stmt->fetch() )
		{
			$chart->addRow( array( new IPSDateTime( $row['joined_date'] ), $row['count'] ) );
		}
		
		/* Output */
		IPSOutput::i()->output = $chart->render( 'LineChart', array(
			'title'	=> "Registrations",
		) );

As you can see, the code is extremely simple to understand and use. This is what the output looks like:

By hovering over any point I'll see a tooltip with the value at that point.

All of the chart types and options available in Google Charts are available to us. Let's make some changes to make the lines curved, get rid of the legend and show titles on each axis - I just change the last line of the code to:

		IPSOutput::i()->output = $chart->render( 'LineChart', array(
			'curveType' => 'function',
			'hAxis' => array(
				'title' => 'Date',
			),
			'legend' => array(
				'position' => 'none',
			),
			'title'	=> "Registrations",
			'vAxis' => array(
				'title' => 'Number of registrations',
			)
		) );

And now my chart looks like this:

• Lack of file organization (a single JS directory that contains dozens of unrelated script files)
• Different script types are bundled together (interface widgets, routes and full applications all in one place)
• Lack of modularity (each JS file is pretty much a floating island in how it might implement functionality, with no formalized structure)
• Simple things requiring code (how many times have you had to write half a dozen lines of JS just to launch a popup?)
• New dom nodes aren't initialized automatically (load some new HTML via ajax, and your popups won't work without manually hooking them up)
  

• Widgets - interface widgets like popups, tooltips and menus
• Utility modules - things like cookie handling or URL manipulation
• Controllers - modules which work on a particular dom node. More on these later.
• Models - modules which handle data. In the vast majority of cases this is simply fetching data from the server.
  

;( function($, _, undefined){
	"use strict";
	
	ips.createModule('ips.myModule', function () {

		// Private methods
		var _privateMethod = function () {

		};

		// Functions that become public methods
		var init = function () {

		},

		publicMethod = function () {

		};

		// Expose public methods
		return {
			init: init,
			publicMethod: publicMethod
		}
	});

}(jQuery, _));

This pattern works well for our purpose, because it enables a module to contain private methods for doing internal work, while exposing only those methods which should be public to the outside world.

This example module could then be used like so:

ips.myModule.publicMethod();

So this keeps everything neatly organized, and ensures variables don't leak into the global scope (which we want to avoid at all costs). When the document is ready, the module is automatically initialized (though you can also have functions that execute before DOMReady if necessary).


Interface widgets

It's fair to say that interface widgets make up a large proportion of the JS used in our software - a web app such as ours has an intrinsic need for popups, menus, tooltips and so on. As mentioned above though, the big hinderance in 3.x is that these widgets have to be created manually (or, in a few simple cases, a special classname is added to an element to initialize it). This feels unnecessary when all the developer wants to do is show a simple widget that is otherwise standard.

To alleviate this hassle, interface widgets in 4.0 all support a data API. What this means is that any widget can be created simply by adding some parameters to an HTML element, and specifying some options. Need a dialog box that loads a remote page? Simply do:

<a href='...' data-ipsDialog data-ipsDialog-title='My dialog' data-ipsDialog-url='http://...'>Click me to open a dialog</a> 

Or if you need a hovercard, just do:

<a href='...' data-ipsHover>This will launch a hovercard</a> 

We already have around two dozen widgets built, covering everything from dialogs, menus and tooltips, to keyboard navigation, tab bars and autocomplete - all supporting initialization with data attributes.

Building your own widgets is easy - they are built as a module, and then simply define some settings to be accepted. The widget module does the rest. They can either be initialized when they're first seen in the dom (which you'd want for something like an image slider widget), or when an event occurs (such as hovering on a link, in the case of hovercards). Whenever new content is loaded into the page, widgets will be found and initialized automatically, too.

Most widgets emit events when certain things occur - when we get to Controllers, you'll see why that is useful.


Utilities

Utilities are simple modules that don't need much discussion. They simply provide methods which do something useful - for example, fetch/set a cookie, write to the user's local browser database, or handle timestamps.


Controllers

Controllers are the meat of the application. Whereas interface widgets are used (and reused) as dumb tools on a page, controllers provide the logic for particular elements, sections and pages. They would, for example, handle the interactions in the topic listing, or the interactions with a post. Notice the word interaction - controllers are specifically designed to deal with events on the page. In fact, that's almost all they do!

Controllers are initialized by specifying the controller name on an element, like so:

<div id='topic_list' data-controller='forums.topicList'> </div>

This div becomes the controller's scope. The controller can manipulate content inside the div, watch for events, and so on.

Controllers, in general, should be as specific and succinct - so simply specifying a page-wide controller then handling everything inside it is discouraged. If we take the topic list in forum view as an example:

<div id='topic_list' data-controller='forums.topicList'> 
	<ul>
		<li data-controller='forums.topicRow'>
			...
		</li>
		<li data-controller='forums.topicRow'>
			...
		</li>
		<li data-controller='forums.topicRow'>
			...
		</li>
	</ul>
</div>

Each topic row might specify the forums.topicRow controller which handles locking, pinning, or marking that topic. The topic list itself might specify the forums.topicList controller, which handles sorting and loading more topics. By doing it this way, controllers become responsible only for a specific portion of the functionality, which keeps them lean and simple.


Controllers are entirely decoupled and cannot reference each other - which is by design, given that a controller is only interested and responsible for its own scope. To communicate, events are used. A controller can trigger events on the page, which other controllers, widgets and models might respond to (and in turn emit their own events).

Continuing the example above, let's assume one of our topic rows is being deleted. The forums.topicRow controller handles removing the HTML from the DOM, but it doesn't care what happens after that - it's not its responsibility. However, it emits a deletedTopic event to let the page know. The forums.topicList controller sees this event, and because it does care, it loads a new topic entry into the list. By using events like this, we can build interfaces that respond fluidly to user interactions while still maintaining separation of concerns.

So, how does a controller deal with events? Because we're using jQuery, event handling in controllers piggy-backs with the on and trigger methods. In the controller's initialize method (which is specifically for setting up event handlers), you simply do:

this.on( 'menuItemSelected', '#menuid', this.handleMenuClick );

Usually when setting up events in an object using jQuery, you need to use $.proxy to properly control the scope of this, but in controllers, this is handled for you automatically - you just specify the method name.

Notice the event we're observing here - menuItemSelected. This is an event that the ui.menu widget emits, and it illustrates how widgets and controllers can interact. Controllers can watch for events from widgets, then do something with the information given, all without ever directly referring to each other.

Triggering an event is similar:

this.trigger( 'doSomething', {
    color: 'yellow',
    size: 'big'
});

This is the same syntax as jQuery's own trigger, except that the controller will ensure the parameters object is passed between different event handlers in the same chain. This will hopefully be clearer when you get your hands on it.


Models

Models are quite similar to controllers (they also use the special on and trigger methods), but their only purpose is to handle data. By decoupling data handling from controllers, we can centralize data getting/setting so that any controller can use it.

Let's say we have a user model, which handles data for the current user. It might have event handlers for adding a friend, for example, so when it sees the event addFriend, it handles it appropriately. Let's also assume we have a controller on each post in a topic, there's three posts, and that the controllers are observing the click event on the 'add friend' button. Here's the sequence of events:

(controller1) click 'add friend button'
(controller1) emit 'addFriend' event
(user model) adds a friend via ajax
(user model) emits 'addedFriend' event
(controller1) updates friend icon
(controller2) updates friend icon
(controller3) updates friend icon

Even though it was controller1 that requested that the model adds a friend, all controllers respond to the event the model emits and updates the friend icon in its own post. This again shows the power of using events as the primary communication system - anyone can respond, and the caller doesn't have to deal with maintaining associations.



Conclusion

So that's about it - the new JS framework in IPS4. Hopefully this in-depth post has covered everything you need to know at this stage. You'll be pleased to know that most of the framework and widgets are already documented, and that will be available when IPS4 hits beta.

Do note that everything covered here is subject to change or removal, as usual in our development blogs.

If you have any questions, feel free to ask!

IPSEmail::buildFromTemplate( 'core', 'admin_spammer', array( $this ) )->send( IPSSettings::i()->email_in );

Here, we are building an email from a template ("admin_spammer" in the "core" application, more on that in a moment), passing the current object in for purposes of replacing out variables in the template, and then calling the send method to actually send the email, passing the recipient to it. The buildFromTemplate() method is a factory method that will create a new object of type IPSEmail. When calling the send() method, you can optionally pass a single email address to send the email too, an array of email addresses to send the email to, or a single instance of IPSMember or an array of IPSMember instances to send the email to. The library takes care of the rest.


The other type of email you may need to send is a completely custom email where you define the entire body without using a template. Bulk mails are a good example of this type of email. You can easily send these types of emails as well.

$email		= IPSEmail::buildFromContent( $subject, $htmlBody, $plaintextBody );
$email->from	= "john@doe.com";
$email->send( "jane@doe.com" );

Here we call the factory method buildFromContent(), passing in the email subject, the HTML email body, and the plain text email body. You can optionally omit the plain text email body and it will be generated for you automatically.

We then specify the from address (which defaults to the suite's outgoing email address), and finally we call the send() method, passing in an email address.

While it is not recommended, you can create an email object without specifying either email body parameter, and specify these later if you have a need.


Further control and options

Beyond what is outlined above, you have fine-grain control over the details of the email being sent. The following example outlines more of the possible values you can specify when necessary

$email			= IPSEmail::buildFromContent( "Hello world" );
$email->from		= "john@doe.com";
$email->fromName	= "John Doe";
$email->subject		= "Changed my mind to hello planet";
$email->useWrapper	= FALSE;

$email->headers['X-Mailer']	= "My cool app";
$email->headers['Priority']	= 3;

$email->setBody( array( 'html' => "<html><body><b>My email</b></body></html>", 'plain' => "My email" ) );

$email->send( array( "jane@doe.com", "janet@doe.com" ), array( "abc@abc.com" ), array( "test@test.com" ) );

Most of the above should be self-explanatory. Just a few quick notes:

• You can set the $useWrapper property to FALSE if you do not wish for the email to be wrapped in the standard default HTML and plaintext email wrappers. The wrappers primarily define the HTML structure (doctype, html tag, etc.) and also allow for automatic definition of the unsubscribe link.
• You can call the $unsubscribe property to manually define an unsubscribe link and the text to display. Alternatively, you can call the "buildUnsubscribe()" method (see below) to do this automatically and consistently. There is no point in doing this if you do not use the wrapper, however, which is why it is omitted in the example above (in this case you should manually include an unsubscribe link if appropriate).
• The first parameter passed to the send() method is the to addresses. The second is the CC addresses, and the third is the BCC addresses, if necessary.
  

$email->buildUnsubscribe( 'bulk', IPSMember::loggedIn() );

The first parameter is the 'type', which is 'bulk' in this case. The second parameter when specifying an unsubscribe link for a bulk email should be the member who is being emailed, as their personal details are used to generate a unique key allowing one-click unsubscribing.

When sending notification emails, you still call buildUnsubscribe() with the following parameters

$email->buildUnsubscribe( 'notification', 'my_notification_key' );

Instead of a one-click unsubscribe link being included, a link pointing to the user's notification preferences area will be included instead, highlighting the notification preference that caused the email to be sent.

Unsubscribe links are only automatically included in the outgoing email if you (1) call this method, and (2) use the default wrappers.


Email templates

While we will touch on this further in a future blog entry, email templates are now defined in a similar manner to HTML templates, and there is one template for the HTML version of the email and one template for the plaintext version of the email. This allows us to better tailor the email being sent dependent upon the content-type in order to provide the nicest experience for the user. The email subject is a language string based upon the email template name and is determined automatically by the email library when buildFromTemplate() is called.


Wrapping Up

While the email library still provides plenty of control to accomodate almost any scenario encountered within the Social Suite, for day to day needs the interface to send emails has been vastly simplified in order to provide a more consistent experience for both the user and the developers integrating applications within the Suite. We hope you find these small changes will make your jobs easier, without losing the control you have presently.