Jump to content

Leaderboard

Popular Content

Showing content with the highest reputation since 02/24/2009 in Guides

  1. Mark

    Google Map Integration

    Enabling integration with Google Maps provides autocomplete functionality when a user enters an address (which is particularly useful if you are using the Commerce application) and can display maps when looking at IP addresses and elsewhere. Warning You need to enable three different API services. Make sure you follow all of the following instructions carefully. To enable Google Maps integration: Go to the Google Developers Console and sign in if you are not signed in already. In the top-left corner is the project selector. You may already have a project if you have previously integrated Google login on your community. If you do not have project, click the dropdown and create one. Select "Enable API's and Services" in the top left of the screen Click the "Google Maps JavaScript API" link and then click the "Enable" button. Click "Credentials" from the left menu, and select "Create Credentials". Choose the API Key option. You will be presented with an API key. Please keep hold of this key for the next step. On your community, to AdminCP > System > Community Enhancements > Google Maps. Here you need to select which items you wish to use. Here we have selected "Show Google Maps?" Important: You will see it then shows at the bottom which APIs you need to enable within 'Enable API's and Services' in your Google Developer Console. We just enabled one already in the previous steps, however you will need to enable any others showing. These will be different, depending on your selections Click on Continue, and in the API key given above here, then follow the instructions given on this page to restrict your API key, and create another secret key.
    9 points
  2. There are several methods of adding advertisements on your Community both in HTML and as image-based ads. They are placed automatically in areas of your choosing. Create Ads Advertisements can be placed on you site in either image or plain HTML in Advertisements in the AdminCP. You can add a new advertisement by clicking on the "Create new" button shown in the image above. Once you have done this you will be presented with the various options for creating an image. You can either enter HTML code or you can click "Upload Images" in order to upload an ad image. In the example below, you will see you can chose to enter separate HTML code to appear on secure pages. Once you have added your image or advertisement code, you can then choose the location and permissions for your advert to be shown. You can select more than one location for an ad to show and criteria for when and how long to show the ad. When using Google Adsense adverts you may notice that page navigation no longer works as expected. This is caused by Google requiring that adverts are not loaded using AJAX. To resolve this issue you can disable AJAX pagination using the built in theme settings. Ajax Pagination Should you wish to disable an advert at any time, you can do this by clicking the "Enabled" text in the list, which will then change to "Disabled" Disable/Enable Manual Ad Placement You can put advertisements in several pre-defined locations but it is also possible to create additional locations which you can insert by modifying the HTML code for your community or use in the Pages application. First, create your advertisement as normal. For the "Show the advertisement" setting, select "Define your own location" and enter a key into the box (it can be whatever you like). You can then later use the same key for other advertisements that you want to show in this location. Now you will need to insert a special tag in the HTML code where you want the advertisement to show. The code to insert is: {advertisement="KEY"} Replace "KEY" with whatever key you used. In your theme Go to Themes and click the "Edit HTML and CSS" button for your default theme. The specific template you need to edit and where to make the change depends on where you want the advertisement to show. For this example, if you wanted the advertisement to show in the profile under the header, go to the core -> front -> profile -> profileHeader template and insert the code at the very bottom. Since each theme has its own HTML templates, you will now need to repeat this for each theme. In pages or blocks The tag can be inserted in a page, block or template within the Pages application. Simply insert the tag wherever you want the advertisement to show. Control when Ads Show Using the responsive CSS classes available in IPS4, it is possible to set your ads up so that different content displays depending on the device size. This only applies to ads you create yourself. If you use an ad service (such as Google Adsense), you should find out how that service supports responsive ads. For example: <div class='ipsResponsive_showDesktop ipsResponsive_showTablet ipsResponsive_block'> This ad shows on desktop and tablets, but *not* phones </div> <div class='ipsResponsive_showPhone ipsResponsive_block'> This ad shows on phones, but *not* desktop and tablets </div> Ads in email Introducts in version 4.4 of the Invision Community platform, is the ability to show your ads within your community emails, as well as on your site. Within the same email section, you will see an Email Advertisements tab, where you can ad advertisements which will only show within emails. Ads within Emails can be restricted to only show within specific email types. As you can see in the image below, I have changed this ad only to be sent when the email is from a Topic, such as a topic reply notification. Email Ads
    9 points
  3. By default, we use the 'comments' icon from FontAwesome to represent forums on the read/unread badges. IPS4 also includes an option to upload an image that will be used instead of the icon. But what if you want to use a different FontAwesome icon for each forum? The good news is this is possible using some custom CSS. Each forum row in the index template includes a data attribute with the forum ID, meaning we can write a style to specifically target each individual forum and overwrite the icon it uses. Note: Although this method isn't terribly complex, it does require editing custom CSS and working with unicode characters. Determining the icon unicode value The method we're going to use involves replacing the icon using a CSS rule, rather than changing the icon classname in the HTML. The reason we take this approach is it won't make upgrading your templates difficult later - our custom CSS persist through IPS4 versions easily. What this means however is that we need to identify the unicode value that FontAwesome assigns to the icons we want to use. To do so, head over to the FontAwesome icon list on this page. Locate the icon you'd like to use, and click it. On the information page, you'll see the unicode value for the icon. Make a note of this code. For example: Do this for each icon you'll want to use. Adding the CSS We're going to add our CSS to our custom.css file so that it persists through upgrades. In the AdminCP, go to Customizations -> Themes, and click the code edit icon next to the theme you want to change. On the CSS tab, open the custom.css file: The rule we need to use looks like this: [data-forumid="..."] .fa-comments:before { content: "\f123"; } You'll need to adjust this code to include the forum ID for the forum you want to change. You can find the forum ID by hovering on the link to the forum, and noting the number you see in the URL: You'll also need to replace the f123 unicode value with the one for the icon you want to use that you noted earlier. Example Let's say we have forum ID's 1 and 2, and we want to use FontAwesome's bicycle and car icons, respectively. We note the unicode values for those icons, which are f206 and f1b9. The CSS we'd add looks like this: [data-forumid="1"] .fa-comments:before { content: "\f206"; } [data-forumid="2"] .fa-comments:before { content: "\f1b9"; } Once we save it, we can see the result:
    7 points
  4. Rikki

    Pages

    The foundation of Pages (the application) is the page (the thing). Tip To alleviate confusion in these tutorials, the application "Pages" will always be referred to with a capital letter; pages within the application or community will be lowercase. What is a page? A page is a container for content. Depending on your needs, a page can simply contain simple content (whether that's plain text, or rich content with images, embeds, and the other things you're used from our other applications), or more complex content like blocks and databases (see later steps to find out more about those). If you are comfortable with code, you can also use all of our standard template logic in a page, allowing for some highly custom results. For those who aren't comfortable with coding, there's an easy page builder, allowing you to drag and drop components into your page. A page has a URL, and can be automatically added to your menu navigation when you create it, if you wish. A page can also have custom permissions, allowing you to restrict who can or cannot access the page. This is great if you want to build special sections of your site, perhaps for staff or premium members only. Prior to Invision Community 4.3, Pages were not searchable (although external search engines such as Google will index them). However, if you have a database on a page, the content of the database will be searchable. Creating Pages Pages are created via the AdminCP, by navigating to Pages -> Pages. A directory listing of your current pages will be shown. Folders are supported here as you'd expect; the URL of the page will reflect this structure. For example, a page called index in a folder called guides will have the URL <your community URL>/guides/index. When you click the Add Page button, you are asked whether you want to use the Page Builder or Manual HTML. Page Type Page Builder After creating the page in the AdminCP, you'll be able to go to the front-end to add content to your page, using drag and drop from the sidebar manager. This option is best for those not familiar with HTML. Manual HTML When you choose this option, you'll be provided with a code editor to create your page. Within this code editor you're free to use HTML, as well as the full range of template logic supported by IPS4. With this method, you insert other items (blocks, databases etc.) into the page by using special tags. A sidebar on the editor show you the available tags. Managing content in pages with the drag and drop editor If you've created a page using the Page Builder options, after saving the configuration in the AdminCP, you can head over to the page on the front-end to manage its content (click the View Page option from the menu on the page listing screen to easily navigate to it). By default, the page will be empty. Click the sidebar toggle to open the sidebar and see the available widgets. All of the usual widgets are available to you from across the suite, but under the Pages category are a handful of special reusable widgets: Block Manager Of these, WYSIWYG Editor is the one you'd be most likely to use when setting up your pages. It gives you a standard IPS4 rich text editor to add content to the page. Simply drag it into a location on your page, then click the Edit button to access the editor. We won't cover the other blocks here since they are specific to other kinds of functionality within Pages. Managing content in pages using Manual HTML When you create a page using manual HTML, you can choose how much of the standard IPS4 wrapper you start with. By default, the suite wrapper is included in the output. This encompasses the header, menu navigation etc., meaning the content of your page is inserted inside this wrapper. With this option disabled, the suite wrapper isn't used - you'll be responsible for providing this (you can however choose a custom page wrapper you've created). If you use the suite wrapper, you can also choose whether the standard sidebar is included in the output. The content you enter into the code editor forms the main page content, and the sidebar will be managed as usual with drag and drop on the front-end. Adding to Navigation When you create a page, you can easily add it to your site's main navigation menu under the Menu tab on the page edit screen. Alternatively, you can add it to the menu manually via the normal menu management process. Setting as Default Often you will wish to set the pages application as your default application, so that you can show a page you created as your default homepage. For this, along with how to create a basic homepage, please refer to the following guide. Blocks
    6 points
  5. We can now tie everything together with some Javascript. It's with the Javascript that everything will feel snappy and interactive. Begin by heading over to the template editor, and editing the Javascript file we created earlier. The Javascript controller we write will do two things: Load the first record when the page is loaded Handle click events on the other records to load the ones the user clicks Here's the final Javascript code you need to insert into the file. We'll explain it shortly: This is a standard IPS4 javascript controller; refer to the controller documentation for more information. In our initialize method (called automatically when the controller is initialized), we set up an event handler for clicking on elements with the data-releaseID attribute (if you remember, we gave items in our record listing this attribute). We bind this handler to the showRelease method. We then call the setup method. The logic in this method selects a record to load automatically, so that the page has content in it when the user first loads it. It tries to find a record with the data-currentRelease attribute, but if one doesn't exist, it will load the first item in the list instead. Finally, there's the showRelease method which has the job of loading and displaying the record view, pulled dynamically via AJAX. To do this, we find the relevant URL from the record row and then fire an AJAX request. In the done handler, we update the div that holds our record content. When a Pages URL is called via AJAX (whether it's a normal page, or a database), it will only return the page content - it won't include the complete site wrapper. This makes it a little easier to implement dynamic page loading. However, in our case, the HTML we need is actually even narrower - we want just the record content, not any of the surrounding page from Pages. For this reason, in the done handler we select just the contents of the #elCmsPageWrap element, and use that as our record content.
    5 points
  6. Rhett

    Using SSL (HTTPS)

    Community in the Cloud customers can submit a support ticket to request SSL/HTTPS be enabled for your community. Applies to self-hosted customers only You will need to obtain an SSL certificate and install it on your server before following these instructions To enable SSL/HTTPS for your community, please edit your conf_global.php file, changing 'http' to 'https' in your URL, then save. From: $INFO['base_url'] = 'http://www.yourdomain.com'; To: $INFO['base_url'] = 'https://www.yourdomain.com'; (it's possible that this parameter may be called board_url in your configuration) Then log into the AdminCP > Support > 'Something isn't working correctly'. Proceed with the first step, this clears out your cache, and will allow all items to then be linked from HTTPS. Running the support tool Please also keep in mind that all advertisements or any code you may have added to the site or theme must be served from https or the cert will show an error for your users.
    4 points
  7. HTML Logic is a very powerful way of conditionally showing different elements in your theme, depending on the values of certain properties. Since the entire IPS4 framework is available within a logic expression, there's a lot of scope for using different kinds of data to determine what should show. In this guide we'll provide a range of examples of common logic checks you might want to do. Even if the exact expression you need isn't listed here, it should provide a good starting point to help you write your own expressions. Logic Recap Let's quickly recap how HTML Logic works. For a more complete tutorial, be sure to read through the Template Syntax guide. In IPS4, logic checks are done using the special {{if}}, {{else}} and {{elseif}} tags. As with standard programming logic, if the expression results in true, the block of code within is executed. If it is false, it isn't (and if there's an else or elseif block, that is tested for a true result instead). So, a block of logic in a template might look like this: {{if member.member_id == 3}} <!-- If the member has ID 3, this will be shown --> {{elseif member.member_id == 9}} <!-- But if the member has ID 9, this will be shown instead --> {{else}} <!-- If the member isn't ID 3 or 9, then this will show --> {{endif}} If you need help constructing a logic check, feel free to check out the Customization Resources forum. Examples. I want to... Check if the user is logged in {{if member.member_id}} <!-- this will show if the member is logged in --> {{endif}} Check if the user isn't logged in {{if !member.member_id}} <!-- this will show if the user is a guest --> {{endif}} Check if the user's ID is one of x, y or z You can check as many values as you like; just add more numbers to the array. {{if in_array( member.member_id, array( 5, 28, 472 ) )}} <!-- Shows if the member's ID is 5, 28 or 472 --> {{endif}} Check if the user is in group x Where x is the group ID number. Note that this also checks secondary member groups. {{if member.inGroup('x')}} <!-- Shows if member is in group 'x' --> {{endif}} Check if the user has more than x posts In IPS4, all content in all apps counts as a 'post'. {{if member.member_posts > 3}} <!-- Shows if the member has more than 3 posts --> {{endif}} Check if the user has fewer than x posts In IPS4, all content in all apps counts as a 'post'. {{if member.member_posts < 3}} <!-- Shows if the member has fewer than 3 posts --> {{endif}} Check if the user is an administrator Note that this also checks if any of the user's secondary member groups has admin permissions. {{if member.isAdmin()}} <!-- Shows if the user is an administrator --> {{endif}} Check if the user is banned {{if member.isBanned()}} <!-- Shows if the user is banned --> {{endif}} Check if the current page is part of app x You need to check the application key. Most are obvious (e.g. forums is the forums app), but there are some others to be aware of. For custom/third-party apps, ask the author which app key they use. core = Any system page that isn't part of another app, e.g. search, login/registration, profiles etc. cms = Pages nexus = Commerce {{if request.app == 'forums'}} <!-- Shows if the user is viewing any page in the 'forums' app --> {{endif}} Check if a system setting has value x You can check whether system settings have a given value, although you will need to know the setting key used by the backend. Values may not be simple to check, depending on their type - consult our Customization Resources forum if you aren't sure how to check a particular setting. {{if settings.auto_polling_enabled}} <!-- Shows if the 'auto_polling_enabled' setting is true (i.e. enabled) --> {{endif}} Check a variable in a template has value x Template bits in IPS4 may receive one or more variables from the backend code. You can check the values of these within the template to do something based on the value. This only works within the template into which the variable you are checking is passed - they are not inherited. {{if $myVariable == 'some_value'}} <!-- Shows if $myVariable is equal to 'some_value' --> {{endif}} Check if the current forum is forum ID x Within the forums app, you can check whether the current page is showing the forum with ID x {{if request.app == 'forums' && request.module == 'forums' && request.id == 3}} <!-- Shows if the user is in the forums app, viewing a forum with the ID 3 --> {{endif}} .
    4 points
  8. Occasionally, you'll want to be able to change the style of a particular element on a particular page, without affecting similar elements on other pages. For example, lets say you wanted to change how the .ipsPageHeader element looks in topic view, to make the title bigger, but without changing it for all other pages that also use .ipsPageHeader. Adding a classname - the wrong way One method would be to edit the template for topic view, add a classname to the element, and then create a style using that new classname as the selector. This works, but it has a drawback - because you've edited the template, IPS4 won't be able to automatically update it for you when you upgrade to newer versions of the IPS Community Suite. We always suggest you try and avoid editing templates directly, for this reason. Using page-specific selectors - the right way There's a better way - every page in IPS4 includes some special attributes on the body tag that identify the app, module and controller being viewed. You can use these to write a CSS selector to only target pages that match the ones you want. Going back to our example, we could target .ipsPageHeader in topic view like so: body[data-pageapp="forums"][data-pagemodule="forums"][data-pagecontroller="topic"] .ipsPageHeader { ...your styles } This works because topic view is generated by the topic controller, in the forums module, in the forums app. All pages in the IPS Community Suite follow this controller/module/application structure. You can mix and match these. If you want to style all page headers in the forums app only, you could simplify the above to: body[data-pageapp="forums"] .ipsPageHeader { ...your styles } You can find out the right values to use by going to the page you want to target, viewing the source in a tool like Web Inspector, and finding the body tag - look for the special data-page* attributes that are used for that page. By including these styles in your custom.css file in your theme, you can target specific elements on specific pages, without making it difficult to upgrade your community later.
    4 points
  9. For more advanced sites built with Pages, you may want to change the output of a custom HTML or PHP block depending on which page the user is viewing. For example, if you have a custom menu, you may want to highlight the active item. We can implement this in Pages by checking the underlying page URL parameters. Although you access a page with a friendly URL (FURL) like http://<yourcommunity>/section/page, behind the scenes this is mapped to a raw URL, such as http://<yourcommunity>/index.php?app=cms&module=pages&controller=page&path=/section/page. Notice the path parameter allows us to identify which page we're accessing. When we access the \IPS\Request::i() object, we can compare against this parameter, like so: {{if strpos( \IPS\Request::i()->path, 'section/page' ) !== FALSE}} <!-- We know the user is on /section/page --> {{elseif strpos( \IPS\Request::i()->path, 'othersection/otherpage' ) !== FALSE}} <!-- We know the user is on /othersection/otherpage --> {{endif}} Note that for reliability, we're using PHP's strpos function to check for the presence of the page URL in the path parameter, rather than a simple comparison. Example Let's assume we've created a Manual HTML block, we're adding HTML to show a menu, and we want to highlight the correct item based on the page. Here's what our block contents might look like: <ul class='ipsList_inline cMyMenu'> <li {{if strpos( \IPS\Request::i()->path, 'help/home' ) !== FALSE}}class='active'{{endif}}> <a href='/help/home'>Home</a> </li> <li {{if strpos( \IPS\Request::i()->path, 'help/faq' ) !== FALSE}}class='active'{{endif}}> <a href='/help/faq'>FAQ</a> </li> <li {{if strpos( \IPS\Request::i()->path, 'help/tutorials' ) !== FALSE}}class='active'{{endif}}> <a href='/help/tutorials'>Tutorials</a> </li> </ul> If we had many items to show, it would get tedious to list them all like this. We could instead do it as a loop: // Using a PHP variable to store an array of pages => page names that we'll loop over {{$myPages = array('help/home' => "Home", 'help/faq' => "FAQ", 'help/tutorials' => "Tutorials", 'help/qna/listing' => "Questions", 'help/qna/recent' => "Recent Questions", 'help/contact' => "Contact Us");}} <ul class='ipsList_inline cMyMenu'> {{foreach $myPages as $url => $title}} <li {{if strpos( \IPS\Request::i()->path, $url ) !== FALSE}}class='active'{{endif}}> <a href='{$url}'>{$title}</a> </li> {{endforeach}} </ul> Now to add new items to our custom menu, we just have to add them to the array.
    4 points
  10. If an existing CKEditor plugin isn't available that meets your needs, another alternative that may be suitable is to create a custom button. What can custom buttons do? Custom buttons allow you to create blocks of HTML that are inserted by clicking a button on the editor toolbar. The blocks you create can accept content that users can enter. Custom buttons don't have the capabilities of a full CKEditor plugin - they can't be dynamic or use Javascript, for example. But for formatting text the user enters, a custom button may be the best choice. Note: although custom buttons tend to be simple, we recommend you have knowledge of HTML, or seek assistance from our peer-to-peer forums. Creating a custom button To create a custom button, navigate to Customization -> Editor -> Toolbars. Click the Add Button button in the header, and then the Custom tab. The form you see has the following fields: Button title The title seen by users when they hover over the button in the editor Icon A small image file that will act at the button icon on the editor. For retina support, upload an icon twice as big as you'd like it to display; it will be resized down by the browser and therefore show high-res. Type Three types of content are supported, and they roughly mimic the three types of element display in HTML: Inline - used when the inserted HTML exists somewhere in a line of text. Does not create a new line for the content. Single line block - designed for single lines (e.g. headers), and puts the block on a new line Block - used for multiple lines, and puts the block on a new line Use option A custom button can optionally accept a value from the user (aside from what they can type as normal inside the block itself). This option will appear as a popup dialog when the user clicks the button in the editor, and the value they enter is passed into the block when it is rendered. With this field enabled, you'll see an additional setting: Option label The text shown to the user requesting a value for the option. HTML The actual HTML the button will render in the editor when used. Generally, any HTML is supported but it must be valid. Within this HTML, a couple of special tags can be used: {option} If the option is used, this tag is replaced with the value the user entered, as-is. {content} If your button will allow the user to type within the generated HTML, insert this tag where the user should be able to type. Click the Save button to create the button. Your icon will be shown on the Buttons Not On Editor toolbar, and from here you can drag it to your live toolbars and configure it as normal. Using custom styles We don't recommend using inline styles in your HTML, because it will be almost impossible for you to update later (posts are built at save-time, not display-time, so if you update a custom button, old posts won't reflect those changes). Instead, we suggest using classnames, and adding styles for those classnames in your custom.css theme file. This way, you can update the styles later, and old posts will also reflect the changes. An example Within this documentation we have tip boxes like this: Tip This is a tip This is a custom editor button we've created that is available to staff. Here's the configuration we used to create this button: Button title Tip Icon Type Block Use option No HTML <div class='docsBox docsBox_tip'> <div class='docsBox_header'>Tip</div> <div class='docsBox_body'> <div class='ipsType_richText ipsType_break ipsContained'> {content} </div> </div> </div> We then add these styles to our custom.css CSS file: .docsBox_header { padding: 5px 10px; color: #fff; font-weight: 500; font-size: 15px; } .docsBox_body { padding: 10px; font-size: 13px; line-height: 1.4; } .docsBox_tip .docsBox_header { background: #2E7D32; } .docsBox_tip .docsBox_body { background: #E8F5E9; } .docsBox_tip .docsBox_body .ipsType_richText { color: #1B5E20; }
    4 points
  11. Rikki

    Buttons

    Basics The button classes described here can be applied to any element, although typically would be applied to an element like a, input[type="submit"] or button so that the user can interact with it. As a minimum, a button should receive the basic ipsButton class, plus a size class and a style class (explained below). Button styles ipsButton_normal Normal button ipsButton_primary Primary button ipsButton_alternate Alternate button ipsButton_important Important button ipsButton_light Light button ipsButton_veryLight Very light button ipsButton_overlaid Overlaid button ipsButton_link Link button Button sizes ipsButton_medium Medium button ipsButton_verySmall Very small button ipsButton_small Small button ipsButton_large Large button ipsButton_veryLarge Very large button ipsButton_fullWidth Can be combined with another size, above. Full width button Disabled buttons Buttons can be visually disabled either by adding the class ipsButton_disabled, or, on relevant input elements, adding the disabled property. For example: <a href='#' class='ipsButton ipsButton_normal ipsButton_medium ipsButton_disabled'>Disabled button (link)</a> <input type='submit' class='ipsButton ipsButton_normal ipsButton_medium' disabled value='Disabled button (input)'> These would render like so: Disabled button (link) Split buttons Split buttons allow you to create toolbars easily by specifying a list of buttons that display joined to each other. They are created by specifying the class ipsButton_split on a wrapper element containing two or more buttons. The wrapper element can be a <ul> tag, or any other that makes sense for your use. All of the buttons in a split button group should be the same size, otherwise results are unpredictable. Different styles can be used on each button, though. <ul class='ipsButton_split'> <li><a href='#' class='ipsButton ipsButton_small ipsButton_primary'>Button 1</a></li> <li><a href='#' class='ipsButton ipsButton_small ipsButton_light'>Button 2</a></li> <li><a href='#' class='ipsButton ipsButton_small ipsButton_light'>Button 3</a></li> </ul> Button 1 Button 2 Button 3
    4 points
  12. Rikki

    Icons

    Description We make use of an icon font called FontAwesome. This enables us to display icons that are accessible, that don't require an additional HTTP request, that can be styled with CSS (and inherit styling automatically), and which scale without loss of quality. Usage An icon can be included within the markup by using the following code: <i class='fa fa-iconname'></i> The list of possible icons and their classnames is available at http://fontawesome.io/icons/. Note that these classnames are not prefixed with ips as with other framework classes; they are left with their default names as they appear on the FontAwesome website. Icons can be used anywhere that HTML can be used. For example, within text, on buttons, in menus and more. Icon on a button A caret icon indicates a dropdown Yes, I think so No, I disagree This is another caret Icon consistency It is important that icon use remains relatively consistent throughout the suite. This applies to core developers as well as addon developers. If different icons are used for the same purpose (or worse, an icon is used for a purpose different to it's usual purpose), users will become confused by the software. To help alleviate this, we have a list of icons that we generally refer to when choosing an icon to represent an action. Check this list to see if your action already has an associated icon, and lean towards using that instead of choosing another. The list below organizes actions, with the title being a general concept. The icon names are FontAwesome icons, without the preceding fa- Adding plus-circle plus Deleting times-circle trash-o Editing pencil Reverting undo Go Somewhere arrow-right Open External Link external-link Confirming Yes/No check times Permissions lock unlock Log In/Sign In key Copy copy Settings cog Flagging On/Off flag flag-o Star On/Off star star-o Developer/Application cogs Help question-circle Merge level-up Code/PHP/HTML code Mail/Send Mail envelope-o Search search View search Refresh/Reload refresh Execute/Run Now play-circle Easy Mode/Visual Editor magic
    4 points
  13. Rikki

    Adding custom fields

    Custom fields are what you use to make a database that is specific to your needs. IPS4 supports a wide range of field types so that you can collect data in the appropriate formats, from text and numbers, to upload fields and YouTube embeds. We're going to create a few different fields to gather information about each recipe that we can then display in our database. They are: List of ingredients Prep time Cook time Cuisine A link to a YouTube video recipe We don't need fields for the recipe title, or the instructions. Databases already provide a title field, and we'll also use the built-in content field for the recipe instructions. We'll see how to set up the custom fields, as well as how to customize their appearance. Ingredients field 1. To create a new field, hover on the Pages tab in the AdminCP, and then click the Fields link under the Recipes database in the menu. The screen will show you the default built-in fields for your database, including Title and Content. 2. Click the Create New button; you'll see a form where you configure your field. 3. For Title, enter "Ingredients". This is the field title users will see when adding/viewing recipes on your site. 4. For Description, enter "One per line". The description is only shown on the add/edit record form, so it's a good place to enter special instructions for filling it in. 5. For the type, we'll choose Editor in this case, because it will allow the user to format the list if they wish. The other fields on the form will change depending on which field type you choose, since each has specific options. 6. We don't require a maximum length, but we do want to require this field to be completed, so leave these settings at their default values. 7. On the Display tab, we'll configure how the field content is shown to users. First, enter ingredients as the field key. This key is how IPS4 identifies this field in templates. We won't actually be using it in this tutorial, but it's good practice to set it anyway so you can use it later if needed. 8. We don't want our list of ingredients to show on the listing screen, so disable that option. 9. We do, however, want it to show on the record display screen, since this is the main screen for viewing a recipe. A badge isn't ideal for showing content from an Editor, so change the Display View Format to the simple Label: Value option as shown: Display View Format 10. We'll show the list of ingredients above the main record content, so make sure Above the item content is selected for the Display option. 11. Finally, there's no need to allow this field to be updated when viewing a record; instead, users will go to the full edit form. You can leave the Editable when viewing a record option disabled. 12. Save the form to create the field. Other fields Other fields are created in the same way, so instead of going through the whole process again, here's the configuration options you need for each field. Where a configuration option isn't listed, leave it at its default value. Note: Some field types, including the Select Box type that Cuisine uses (see below), support a fixed set of options from which the user can choose. You'll set these up as key/value pairs in the AdminCP, but the user will only see the values when they select them. The key is just used internally by IPS4 and in custom templates to identify the value, and is best kept as a single lowercase word. Prep time Name: Prep Time Type: Text Required: No Template key: prep-time Listing view format: Label: Value Display view format: Label: Value Cook time Name: Cook Time Type: Text Required: No Template key: cook-time Listing view format: Label: Value Display view format: Label: Value Cuisine Name: Cuisine Type: Select Box Content: (key/value) indian / Indian italian / Italian american / American mexican / Mexican Allow filtering: Yes Required: Yes Template key: cuisine Listing view format: Label: Value Show to right of listing area: Yes Display view format: Label: Value Display: Above the item content Video recipe Name: Video tutorial Type: YouTube Embed Required: No Template key: video-tutorial Show in listing template: No Show in display template: Yes In a record, display as: Embedded Player That's it! If you now head over to the front-end page for your database, click into a category, and click the Add New Recipe button, you'll see your fields on the form, ready to collect information! Feel free to add some sample records to try it out. You'll also see the Record Image field that the database provides automatically (discussed earlier). When you upload an image here, you'll see it is automatically included in the record view for you. Here's an example recipe in our database: Listing View Record View
    3 points
  14. Rikki

    Using designer's mode

    While the standard template editor is useful for light template editing, for larger, more complex changes, editing with a real IDE is desirable. The IPS Community Suite facilitates this through something called Designer's Mode. What is Designer's Mode? Designer's Mode allows you to use a real IDE by exporting all of the templates and CSS files to disk as files, and then reimporting them to the suite when you have finished editing them. With Designer's Mode enabled, the software will load its theme from this folder, meaning you can edit the files and see the changes as you make them. Warning Designer's Mode should not be used on a live community because it will have resource usage implications. We always recommend developing themes with Designer's Mode on a test/development installation. Enabling Designer's Mode The first step is to create a folder called themes in your root community directory (that is, the same place your conf_global.php exists). CHMOD this folder to 777 to enable the suite to write the files. Next, navigate to Customization -> Themes in the AdminCP. In the toolbar at the top of the page, click the Designer's Mode button. Toggle the setting on after reading the information box, and then save the form. IPS4 will begin writing the theme files to disk. Once complete, you will see a directory structure similar to this in the /themes folder on your server: All themes currently installed are exported when Designer's Mode is enabled; the parent folders in this structure are named based on the theme ID. You can cross-reference the theme ID you wish to edit on the theme listing page in the AdminCP while Designer's Mode is enabled: Each theme folder contains four key parts: /css The CSS for the theme, grouped first by app, then by location (front/admin/global). /html The *.phtml HTML templates this theme uses, grouped first by app, then by location (front/admin/global) then by section. lang.php A language file into which you can insert any custom language strings your theme requires. They should be in this format: 'my_language_key' => "The English phrase" /resources Resources for the theme (primarily images), grouped first by app, then by location (front/admin/global) then by type. Resources aren't allowed to be larger than 1.5 MB . Editing templates When you edit the *.phtml template files exporting by Designer's Mode, you will notice a special tag on the first line of each file that looks like this: <ips:template parameters="$title,$html,$location=array()" /> This tag is how the software knows which variables belong to this template. It is very important that you do not modify this line in template files, or your theme may break. Completing Designer's Mode When you are happy with your changes, you can disable Designer's Mode to import them back into the suite (note that you can enable Designer's Mode again later to continue). To do this, go back to the theme listing screen at Customization -> Themes, and click the red Designer's Mode Enabled button. When you toggle the setting off, you will see additional settings asking you to confirm that you want to synchronize the changes. Warning Be sure the Synchronize option is enabled when you save this form, otherwise your changes will be lost. You can select individual themes to sync, or all of them. You can also choose whether to keep the files on disk or automatically delete them once the sync is done.
    3 points
  15. It may be handy at times, to be able to add some of the blocks you see in pages, or even your own custom blocks, into external webpages. Within IPS4 we give you the ability to choose any block to embed externally directly from the admin CP. Getting the code In order to embed one of your blocks on an external page. First log into your admin CP and visit Pages>Page Management>Blocks. Once you are in here, select the dropdown box next to the block you wish to embed externally, and select "External embed" Once you have selected this, you will be presented with a screen similar to the below. Copy the code into the relevant areas of your own website code to embed the block. Note that there is a checkbox to "Inherit key styles from parent page". If this is selected, then the styling of the block will also be brought across. If not, then you would need to style the block from your own websites code.
    3 points
  16. Rikki

    Responsiveness

    Introduction to responsive classes IPS4's CSS framework is responsive, meaning elements adapt according to the size of the display the users chooses to use. In most cases, the existing classes already outlined in this guide take care of it for you; for example, menus automatically adjust, and tab bars collapse into a dropdown menu on mobile phones. There may be times when you need to control on which devices sizes elements show or hide themselves. For example, if you add a custom footer element, you may want to only show it on desktop, and hide it from tablets or phones. The responsive classes that IPS4 provides allow you to control this kind of behavior. Responsive sizes used by IPS4 For the purposes of the media queries we use to control responsiveness, the following sizes represent each device: Phones - up to 767 pixels wide Tablets - between 768 pixels and 979 pixels wide Desktops - 980 pixels and wider Basic show/hide functionality The CSS framework includes two groups of three classes that show or hide elements on desktop, tablet and phone-sized devices, respectively. The classes act in an exclusive way; that is, if you use the show classes, any devices that don't match will not show the element. The opposite is also true; if you use the hide classes, then the element will not show on those devices but will show on the others not specified. The classes are: ipsResponsive_hidePhone ipsResponsive_hideTablet ipsResponsive_hideDesktop ipsResponsive_showPhone ipsResponsive_showTablet ipsResponsive_showDesktop You can combine these as needed. For example: <div class='ipsResponsive_hidePhone ipsResponsive_hideTablet'> This element *will not* display on phones or tablets, but *will* display on desktops </div> Additional classes to control element display When using the show classes outlined above, you typically need to include an additional class that controls how the element is rendered. This can be one of the following: ipsResponsive_block ipsResponsive_inlineBlock ipsResponsive_inline <div class='ipsResponsive_showDesktop ipsResponsive_block'> This element will *only* show on desktop sizes, and will render as a block-level element. </div> These additional classes aren't usually necessary when using the hide classes.
    3 points
  17. For most admins, creating a theme with the Easy Editor is the best option. It allows you to customize the default theme in a point-and-click environment and see your changes in real-time, and requires no coding skills whatsoever. Creating the theme To create the theme we'll edit, navigate to Customization -> Themes in the AdminCP. Click the Add Theme button. In the popup window, ensure the Easy Mode option is selected (it's the default), and then click Next. On the next screen, you can configure some choices about your new theme: Name (required) As it will appear to users of your site Parent You can make this theme a child of another, meaning it will automatically inherit any style/template changes from the parent theme Default theme Makes this theme the default for guests and members who have not specifically chosen another theme Available for Sets permissions for which groups can use this theme. Example use: a theme that only 'premium' users can access as an added benefit of paying Click Save once you have filled in the information. Your theme will be created and you'll be returned to the theme listing. Launching the Easy Mode editor From the theme listing in the AdminCP, you can click the magic wand icon on any Easy Mode theme to launch the visual editor (you will need to be logged into the front-end of your community to use the visual editor): Note: You can launch the visual editor at any time, even long after you've created the theme. However, if you convert an Easy Mode theme to a normal theme, you can't go back and use the visual editor. Launching the visual editor will take you to your community in editing mode (that only you can see). Your community will be shown on the left, with editing tools available in a panel on the right: The visual editor has a few key functions to help you design your theme. We'll cover each in turn. 1. Colorize This tool lets you instantly change all of the theme colors to different shades of another color. Click the Colorize button, and you'll see four swatches: Clicking a swatch and choosing a new color will immediately update the live preview to show you the result. The colorize tool is great as a first step - if you know you want a red theme (for example), you can use it to get the basics done, and then fine-tune the resulting colors later using the other tools. If you don't like the result, you can click the Revert Colorizer button to undo your changes. 2. Select tool The Select tool allows you to point-and-click at sections of pages on your community, and the visual editor will automatically show you the color editor for the closest available parts. 3. Custom CSS If you are familiar with CSS, the Easy Mode editor gives you the ability to add custom CSS to your theme without needing to convert it to a full manual theme. Simply click the CSS button, and a code editor will be shown for you to use. And yes, you still get the live preview! 4. Style editor The available styles you can edit are listed in the main panel. Click one to see the color swatches and to edit the colors. Some styles allow you to edit just the background, others will also allow you to edit the font color. Background colors can also be turned into gradients by clicking the button. To use it, you choose a direction in which the gradient should go, and then add colors to form the gradient. 5. Build The Build tab is where you'll go once you're happy with your changes and want to save them. Click the Save Theme button to do so. This will save your changes and make them live to any users who have chosen this theme.
    3 points
  18. Rikki

    Dropdown Menus

    Description Dropdown menus allow users to select from a number of options. The markup is designed to work in tandem with the ips.ui.menu javascript module. Usage A menu consists of a trigger element, and the menu element itself: <!-- The trigger --> <a href='#elMyMenu_menu' id='elMyMenu'>Open Menu</a> <!-- The menu --> <ul id='elMyMenu_menu' class='ipsMenu'> ... </ul> The ID of the menu should be the ID of the trigger element, suffixed by _menu. If the trigger element is a link, its href should be an anchor to the ID of the menu element. This makes the menu accessible even when Javascript is disabled in the browser. Basic menu A basic menu might have the following markup: <ul class='ipsMenu ipsHide'> <li class='ipsMenu_item'><a href='#'>Item 1</a></li> <li class='ipsMenu_item'><a href='#'>Item 2</a></li> <li class='ipsMenu_item'><a href='#'>Item 3</a></li> <li class='ipsMenu_sep'><hr></li> <li class='ipsMenu_item'><a href='#'>Item 4</a></li> <li class='ipsMenu_item'><a href='#'>Item 5</a></li> </ul> This would display as follows: see example. Item 1 Item 2 Item 3 Item 4 Item 5 ipsMenu is the base class for the menu element. Items within the menu should have the class ipsMenu_item, with the link element inside of that. A separator item can be added by giving the item the class ipsMenu_sep, containing an <hr> element. Note that the positioning and stem is added automatically by the menu javascript module; it does not need to be manually specified. The stem can be removed, if necessary, by including the class ipsMenu_noStem on the menu element. Disabling menu items Individual menu items can be disabled by adding the class ipsMenu_itemDisabled to the list item: see example. Item 1 Disabled Item 2 Item 3 Note: Disabled items are not foolproof; in browsers that do not support the CSS pointer-events style, a click on a disabled item will still register. Ensure your javascript properly deals with disabled item clicks if necessary. Menu sizing By default, a menu will have no defined width. An additional classname can be specified on the menu element to determine how wide it should display. ipsMenu_auto - menu will appear as wide as necessary, though with a minimum width of 200px and a maximum width of 500px ipsMenu_narrow - 200 pixels wide ipsMenu_normal - 300 pixels wide ipsMenu_wide - 450 pixels wide Selectable menus A selectable menu allows the user to toggle one or more of the menu items, useful for turning options on and off. For this functionality to work, the javascript module needs to be used. A menu can be made selectable by adding the classname ipsMenu_selectable. A menu item can be shown as selected by adding the classname ipsMenu_itemChecked to the list item. The markup for a selectable menu might look this: <ul id='elMenu2_menu' class='ipsMenu ipsMenu_normal ipsMenu_selectable ipsHide'> <li class='ipsMenu_item'><a href='#'>Item 1</a></li> <li class='ipsMenu_item ipsMenu_itemChecked'><a href='#'>Item 2</a></li> <li class='ipsMenu_item'><a href='#'>Item 3</a></li> </ul> This would display as follows: see example. Item 1 Item 2 Item 3 Sub-menus Submenus can be created by embedding menus within one another. To do so, simply include the ipsMenu_subItems class on the item that contains the submenu, and the submenu itself within the item. For example: <ul id='elMenu3_menu' class='ipsMenu ipsMenu_normal ipsHide'> <li class='ipsMenu_item'> <a href='#'>Item 1 (no children)</a> </li> <li class='ipsMenu_item ipsMenu_subItems'> <a href='#'>Item 2 (with children)</a> <ul class='ipsMenu ipsMenu_wide ipsHide'> <li class='ipsMenu_item'><a href='#'>Sub Item 1</a></li> <li class='ipsMenu_item'><a href='#'>Sub Item 2</a></li> <li class='ipsMenu_item'><a href='#'>Sub Item 3</a></li> </ul> </li> </ul> This would display as follows: see example. Item 1 (no children) Item 2 (with children) Sub Item 1 Sub Item 2 Sub Item 3
    3 points
  19. Rikki

    ips.ui.dialog

    Description The dialog widget displays popup windows within the page, typically loading content from a remote source. Usage A dialog is defined simply by including the widget key as an attribute on a trigger element. It is recommended that the trigger element be a link or button, so that if the user has javascript disabled their browser can take them to a full-page version of the dialog contents. <a href='...' data-ipsDialog data-ipsDialog-url='...'>Launch dialog</a> Dialogs offer special functionality for forms contained with the dialog, enabling them to be automatically validated and submitted via AJAX when used with the form helper from the IPS4 PHP framework. See the remoteVerify and remoteSubmit options below. Obtaining a dialog reference If you need to control a dialog programmatically, you can do so by first obtaining the reference to the dialog. To do so, call the getObj method, passing in the element on which the dialog was created as the parameter: // HTML <div id='elementWithDialog' data-ipsDialog> ... </div> // Javascript var dialog = ips.ui.dialog.getObj( $('#elementWithDialog') ); The returned reference to the dialog instance can be used to call the methods shown below. Creating a dialog programmatically Dialogs can be created programmatically by controllers instead of being created on particular elements. To achieve this, call the create method: var dialog = ips.ui.dialog.create( object options ); The options parameter should be an object containing keys for the options below. This method returns a reference to the dialog instance on which you can call methods to control the dialog, for example: dialog.show(); dialog.hide(); Instance methods show( boolean initOnly ) Initializes and shows the dialog. If initOnly is true, the dialog is initialized but not immediately shown. hide() Hides the dialog. remove( boolean hideFirst ) Removes the dialog from the DOM. If hideFirst is true, the dialog will call hide() and remove itself after the animation is completed. setLoading( boolean loading ) If loading is true, indicates to the user that something is being loaded (i.e. shows a spinner in the dialog). If loading is false, removes the loading state. Note: this method doesn't empty the dialog content first. Call instance.updateContent('') manually if desired. updateContent( string newContent ) Updates the contents of the dialog with the provided newContent. New controllers/widgets are automatically initialized after updating. Options url (String; optional) If provided, the dialog contents will be loaded by calling this URL when the dialog is launched. content (Selector; optional) If the dialog content already exists in the DOM, this option should be a selector that will locate the wrapper element for the content. modal (Boolean; optional; default true) If true, the page background will fade, preventing the user from interacting with it until the dialog is dismissed. title (String; optional) Sets the title shown in the dialog window. If not set, no title bar will display. size (String; optional) If provided, will set a special class on the dialog designed to change its size. Currently, narrow, medium, wide and fullscreen are supported as values for this option. If not provided, the default dialog width will be used (defined in CSS). close (Boolean; optional; default true) Determines whether the dialog should be built with a close button. fixed (Boolean; optional; default false) Determines whether the dialog is fixed. A fixed dialog is anchored to the viewport, not the page. Its height will also be fixed, with the content scrolling inside if necessary. If this is false, the dialog will scroll with the page, and it will expand to fit all the content being shown, regardless of length. remoteVerify (Boolean; optional; default true) When the dialog contains a form built using the IPS4 PHP framework form helper, this option instructs the dialog to automatically validate the form values and present any errors to the user. remoteSubmit (Boolean; optional; default false) When the dialog contains a form built using the IPS4 PHP framework form helper, this option instructs the dialog to submit the form values via AJAX. If remoteVerify is also true, two separate AJAX requests are fired; first, the form is validated, and if successful the form is submitted with a second request. If remoteSubmit is true, after a successful submit the dialog is closed automatically. If the flashMessage option is provided, it will be shown at this point. By default, remoteSubmit is false, which means forms submit via a traditional page reload. callback (Function; optional) Specifies a callback function that will be executed after the dialog has loaded remote content. Note: this option cannot be provided via the data API, and is therefore only available when interacting with ips.ui.dialog directly. forceReload (Boolean; optional; default false) By default, once a dialog has loaded its content, it will not do so again even if the dialog is relaunched. By setting this option to true, the dialog will call the url every time it is opened. This option only takes effect when the url option is used. Events emitted by ips.ui.dialog openDialog Triggered when the dialog is shown. Event data: elemID ID of the element that triggered the dialog dialogID ID of the dialog element dialog Reference to the dialog element contentLoaded Boolean indicating whether the dialog content has been loaded (may be false if remote content is used) hideDialog Triggered when the dialog is hidden. Event data: elemID ID of the element that triggered the dialog dialogID ID of the dialog element dialog Reference to the dialog element dialogContentLoaded Triggered after remote content has been loaded and inserted into the dialog. Event data: elemID ID of the element that triggered the dialog dialogID ID of the dialog element dialog Reference to the dialog element contentLoaded Boolean indicating whether the dialog content has been loaded (always true here) Events to which ips.ui.dialog responds closeDialog Instructs the dialog to close. Event data: dialogID (required) The ID of the dialog to close (the event is ignored if the ID does not match the current dialog)
    3 points
  20. Rikki

    Databases part II

    Database URL Structure Databases exist inside a page you've created with Pages. Individual categories and records in the database are accessed via the URL of the page. For example, if you had a page with the URL <yourcommunity>/mypage and this page contained your database, you might have a record that's accessed via the URL <yourcommunity>/mypage/category/record, where category is the category name and record is the record name. Your URLs would dynamically update themselves if you renamed your page or moved the database to a different page. To facilitate this approach, databases can only exist in one page at a time. They can't be duplicated on other pages (although you can create blocks showing data from the database and use them on other pages). Fields More advanced uses of databases require custom data to achieve their goals, and fields can be set up to gather this data. Fields are created in the AdminCP, and when a user adds a new record, the fields are shown on the form. IPS4 supports a wide range of field types, allowing you to capture data of a specific type easily. Here's the supported types: Address Provides a special auto-completing address field, powered by Google Checkbox A single on/off checkbox Checkbox set A group of several on/off checkboxes Code Provides a way to syntax-highlight code Date A date field, with a date picker Editor Provides a rich text editor for WYSIWYG editing Database relationship An advanced field type that allows records from different databases to be associated Member Provides an auto-complete member search box Number A number input box (on older browsers, reverts to a simple text box but with number validation) Password A password input field Radio A group of radio boxes (meaning only one of the options can be selected) Select box A drop-down menu containing the provided options (can allow multiple selections if desired) Soundcloud A Soundcloud embed field Spotify A Spotify embed field Telephone A telephone number input field (on older browsers, reverts to a simple text box) Text (default) A one-line text input field Text Area A multiple-line text input field Upload An IPS4 upload field URL A URL input field (on older browsers, reverts to a simple text box with URL format validation) Yes/No A toggle field that can accept yes or no values YouTube A YouTube embed field Many of these field types have additional options specific to them. For example, select boxes have an option to allow multiple values to be selected, whereas the upload has options to allow multiple files, and a way to restrict file types. Field Formatting Fields can have automatic formatting applied to them. For non-coders, a range of badge colors is available to choose from, and you have some control over the location that the field shows in the listing or record display. For coders, however, you have full control over the HTML output for each field, including having use of IPS4's template logic. This means you have the ability to use the data stored by IPS4 for each field in some very interesting ways - for example, you might take the value of an address field and use it to output an embedded Google Maps map, or even create some fields that you don't output, but instead use to control the layout of your record templates. There are a huge number of possibilities. Permissions There's multiple levels of permissions at play with databases: Page-level Since pages have their own permission settings, if the user doesn't have permission to see the page, they won't be able to see the database either. Database-level Permissions can be set at a database-level, which forms the default permissions for categories in the database too. Category-level A category can optionally override the database-level permissions and provide its own. This is useful for hidden categories - perhaps staff only, or a category only for premium members. Managing Databases Databases are managed by going to Pages -> Databases in the AdminCP. You'll also find that databases are listed in the Pages menu in the AdminCP for quicker access. From this screen, you'll see some simple information about each of your databases, as well as menu items to manage each part: Managing Database Records can be added either via the AdminCP (click the icon) or via the front-end page that displays the database. This means users don't need AdminCP access to add/edit records. Creating Databases To create a database, click the Create New button on the screen above. There's a number of configuration options available to you. Details The basic settings for this database. At the bottom of this tab, you can choose the templates you want to use for this database. If you haven't created them yet, you always do this later. Language On the Language tab, you set up the words that will be used to refer to records in this database (rather than the generic 'records' terminology). For example, if you are creating a database for guides, these language choices will mean IPS4 will refer to your database in context, such as "Search Guides", "There are 5 guides in this database" and "Create a new guide". Options This tab more finely controls how your database will work, including comments, reviews, tagging, and the 'wiki-style' editing we covered earlier. Sorting options are also available here, allowing you to choose the order of records, and more importantly, the field on which they are sorted. For example, if you had a database containing records about dinosaurs, you may want to sort the records by Era (a custom field you will have created). You can return to this tag after creating your fields later to configure it. Forum This tab configures the aforementioned Forums integration for the database (individual categories can override these settings too). Page Since a database requires a page in which it displays, you can easily create one here as part of the database creation process. Alternatively, you can add it to one of your existing pages later. Adding to a Page If you don't create a page as part of the database creation process (above), you can do so manually by using a special database tag in your page content. On the Details tab of the database form, you specified a database key. This is how this database is included in pages. If the key is my-database, you'd insert it into a page by placing this: {database="my-database"} As mentioned above, a database can only exist on one page at a time; trying to use this tag on multiple pages won't work correctly.
    2 points
  21. Rikki

    Mixins

    Mixins are a special type of controller that allow you to augment or change the functionality of an existing controller. This is particularly useful when you need to change something about how a built-in controller works. Basic structure This is the boilerplate for a mixin: ;( function($, _, undefined){ "use strict"; ips.controller.mixin('mixinName', 'core.global.core.table', true, function () { // Your code goes here }); }(jQuery, _)); The method signature is: ips.controller.mixin( string mixinName, string extendsController, boolean autoLoad, function mixinBody ) mixinName A name that will refer to this mixin extendsController The full name of the controller that this mixin will extend (e.g. core.global.core.table) autoLoad Boolean indicating whether this mixin should always extend the extendsController controller, or only when specified mixinBody A function that returns the behaviors that the mixin defines How a mixin works A mixin works by allowing you to provide custom code that will execute at key points when the parent controller's method is called. To do that, there are three important methods available to a mixin: before() Run the specified code before the parent controller's method after() Run the specified code after the parent controller's method around() The specified code is passed a reference to the parent controller's method, allowing it to be called when desired (and the return value modified In addition to hooking into existing controller methods, your mixin can also provide new methods for its own use and, notably, simply redefine a method present in the parent controller in order to completely replace its functionality. A note about this Within the mixin body, you'll be adding methods to this. The mixin executes in the same context as the parent controller; that is, this in a mixin refers to both the mixin and the controller it extends, allowing you to call methods from the controller, and any create yourself in the mixin. During execution, they are one and the same. The same is also true within methods in your mixin since, like in controllers, methods are automatically bound to the controller for you. You may be familiar with this.scope in controller methods (which refers to the DOM element onto which the controller is applied). Since mixin methods are bound in exactly the same way, using this.scope in a mixin method will still give you the element onto which the controller is applied. before() and after() The behavior of these two methods are very similar. They simply allow you to execute your custom code either immediately before, or immediately after the parent controller's code. Your custom code receives the parameters that are passed into the parent method, but not the return value (if any). A common usage of either method is to add additional event handlers to a controller. A controller sets up its event handlers in the initialize method, and so a mixin can add more handlers like so: this.before('initialize', function () { this.on('click', '#button', this._doSomething); this.on('click', '#button2', this._doSomethingElse); }); In this case, our function will be executed, and then the parent's own initialize method will be executed. In this example we don't deal with any parameters but, if the parent method is called with any, they will also be available to your mixin function as normal parameters, in the same order. around() This behaves differently to the previous example, because rather than simply being executed before or after the parent, it actually provides the parent method as a reference to your own function. This allows you to call the parent method at a time of your choosing - perhaps determined based on some logic in your code. Since you have control over calling the parent method, you also have access to its return value, meaning that around can also be used as a way to modify the value that is returned from a controller method. As an example, let's assume that the parent controller method returns a JSON object, but we want to augment this with some additional key/values. We can do this using the around call, like so: this.around('parentMethod', function (origFn) { var returned = origFn(); return _.extend( returned, { key1: true, key2: false }); }); Notice that the parent method is passed in as a parameter (if the method has any other parameters, these will appear first, and the parent method will be the last parameter). We call this method in order to get its return value for our own use. When we look at the parent method we know that it returns a JSON object, so we extend it with our own values. It's worth noting that since you receive both the original parameters, and a reference to the parent method, you have the ability to modify the parameter values before passing them into the parent method. This approach can offer a lot of flexibility. Custom methods and replacing existing methods Finally, you can create new methods in your mixin, or completely replace methods from the parent controller by redefining them. In both cases, this is done like so: this.myMethod = function () { //... }; Of course, if you replace an existing method, be sure it plays nicely with any calls to it! Calling a mixin Mixins can be applied to controllers manually when needed (you don't need to do this if you configured your mixing to automatically apply to the controller, though). To do so, specify the mixin name in parenthesis after the controller. For example: <div data-controller='core.front.core.someController( mixinName )'> </div> Multiple mixins can be provided if they are comma-delimited. Note that mixin files are not loaded on demand in the same way that controller files may be (but they will be compiled into bundles in the same way at build-time). In order for a mixin to be applied, it must be included in the page output. This means that if you're creating a plugin that (for example) has a mixin that applies to a core controller, you are responsible for ensuring the mixin file is included in the page as needed. This may mean creating a theme hook that modifies the output of the includeJS template.
    2 points
  22. Reputation & Reactions are an important part of communities across the internet. IPS Community Suite gives you the flexibility to set these up in a way which is suites your own community needs. Basic Settings Reputation settings can be managed in the following location in your ACP Members -> Member Settings -> Reputation & Reactions From the basic settings screen, you can set up various overall settings, related to how reputation and reactions work on your site. You can switch the system on and off, as well as assign which groups are allowed to use this, and how to display the reputation items. Example Reputation Settings One important item to note here, is the "Highlight content with positive reputation. When this is set, topics will be highlighted when they reach the set reputation level, along with being given a reputation symbol in the top right to highlight the post has high reputation. Denotes High Reputation Post Reactions Reactions settings can be managed in the following location in your ACP Members -> Member Settings -> Reputation & Reactions -> Reactions On the reactions tab you will see a list of all the reactions that a user can give on your site. Each of these is given either a positive, a negative, or a neutral value. These are the reputation points in which a user will receive for a particular reaction. You can reorder these using the anchors on the left of each item. You can create new reaction items using the button in the top right of the screen. Default Reaction Set You will note that the 'like' item has no ability to delete. This is the default reaction, and is what is shown at in the reaction placement area on posts. Your users point at this icon in order to show other reactions, or click to give this reaction. Of course you can use the pencil icon to edit this to be anything you wish. Pointing at the like icon shows other reactions Leaderboard The new Leaderboard is designed to better highlight your most active members and content based on reputation and other metrics. The Leaderboard will greatly enhance both member and content discovery on your community. Winners being highlighted within the profile when 'winning the day', and being added to the past members list. In turn, this can improve member participation on your site. IPS Community Leaderboard Leaderboard settings can be managed in the following location in your ACP Members -> Member Settings -> Reputation & Reactions -> Leaderboard From here, you can change various settings to determine what and how the leaderboard will display, or indeed if it will display at all. This can be helpful if, for example, you wish to exclude staff, or specific items, from being counted. Leaderboard Settings Reputation Levels Reputation levels can be managed in the following location in your ACP Members -> Member Settings -> Reputation & Reactions -> Reactions Here you will see levels that can be gained upon reaching a set number of reputation/reaction points on your site. These can be given a reputation name and optionally an image. Reputation Levels Clicking on "Create new" will give you the opportunity to add a new reputation level. The one I have created below as an example will give people the superstar reputation level with a star image upon hitting 1000 reputation points. Example Reputation Level Note: Within each member group, you can also set whether that group can see who has given reputation and the amount of reputation they can give in any one day.
    2 points
  23. In any community there will always be information you want to capture about your members which is not provided within the core product. These may be information needed for administration purposes, or items which you wish to have displayed within profile, or content items. In the IPS Community Suite, we provide the ability to set up many of these, grouping in a way in which is appropriate to your site. Setting Up Profile fields can be set up within the following location within your ACP Members -> Member Settings -> Profiles -> Profile Fields Profile field list Clicking on the Create New button in the top right will allow you to set up a new grouping for profile fields, similar to what you see above with the Personal Information section. To add a new field to a group, select the + at the side of the relevant group. Clicking to add a new field will show you the following screen. You will see I have selected text as the field type on this occasion which will let a user enter information into a text box. New profile field entry You can see settings here you can use to set up a maximum length and even using Regular Expressions to validate the data that is entered. You will note that there is no "Required" element shown here. This is because we have profile completion set up. If you do not have quick registration set up to use profile completion, you will also see a "Required" checkbox which can be selected. In addition you can set up where the information is shown, how it is shown, and its behavior with regards to being filled in. Do you want this to be edited once it is filled in? No? Not a problem, just de-select the "Member can edit value" and it will only allow this to be entered once. New profile entry What is important to note on the screenshot above, is the "Display Format for..." sections. These will appear only if you have the corresponding settings to make these viewable, and were introduced in version 4.4 of the Invision Community platform. So for example, above we have "Show to staff" set for the "Show with members content submissions". If we switched this not to show, then you would not see the "Display format for topics" option. Display Formatting The display formatting sections by default will display just the field contents. However you can display the item stored in the field in any way you wish, by selecting "Use Custom Formatting". You will then be shown the following field for adding your own formatting code Display Formatting This is where you can enter HTML along with the placeholders provided to display the information in any manor that you choose. This is how they will then be displayed in that area (Profile or topic). Note: Prior to the 4.4 version, this is a single field named "Display Format" and applies to both areas. {title} and {content} should be used instead of the ones below. If you add the following code to the example field we set up, the placeholders {$title} and {$content} will be replaced with the title of the custom field, and the content that is entered by the user <strong>{$title}:</strong> {$content} User Side You will see once you have set up your profile fields the members can then add the information from within their profiles. Profile Field Completion Depending on if you have setup of your profile fields to be searchable, these can also be searched using the member search form on your site Profile Field Search And of course, they will show up in various areas of the site, using the formatting in which you have set to your own liking. Formatting on Posts
    2 points
  24. Rikki

    Miscellaneous

    Padding ipsPad 15px padding on desktop ipsPad_half 7px padding on desktop ipsPad_double 30px padding on desktop The padding classes are scaled appropriately on mobile devices. Spacing ipsSpacer_top 15px top margin ipsSpacer_bottom 15px bottom margin ipsSpacer_both 15px top and bottom margin ipsSpacer_half When combined with one of the above, halves the spacing ipsSpacer_double When combined with one of the above, doubles the spacing Clearing ipsClear Clears floats preceding the element this class is applied to ipsClearfix The popular 'clearfix' technique, which causes a wrapper element with this class applied to fully wrap elements contained within it, even if they are floated. This class should be applied to all elements where descendents may be floated. Positioning For text positioning, see typography. ipsPos_left Floats the element left ipsPos_right Floats the element right ipsPos_center Sets automatic margins on the element in order to center it. Block elements will require a width to be set for this to be noticeable, otherwise they will naturally display at 100% width. Horizontal rules Horizontal rules can be styled simply by adding the class ipsHr to a standard <hr> element. Notification counts ipsNotificationCount is a class for a floating bubble which can denote a notification count of some kind. The parent element should have a non-static position for this class to work correctly. By default, the notification bubble will be offset to the top and right, but this could be overwritten with additional specific styles if desired. Usage: <!-- The element the notification belongs to --> <!-- position: relative; is set inline here, but avoid that in practice --> <a href='#' class='ipsButton ipsButton_primary ipsButton_medium' style='position:relative'> A button with notification <span class='ipsNotificationCount'>12</span> </a> This would render: A button with notification12 Online/Offline status Provides simple styling to denote whether something (a user, for example) is online or offline. ipsOnlineStatus is the base class; add ipsOnlineStatus_online or ipsOnlineStatus_offline to denote the actual status. <strong class='ipsOnlineStatus ipsOnlineStatus_online'><i class='fa fa-circle'></i> Online</strong><br> <strong class='ipsOnlineStatus ipsOnlineStatus_offline'><i class='fa fa-circle'></i> Offline</strong> Online Offline Cursors Several classes are provided as shortcuts for changing the mouse cursor on elements. ipsCursor_locked "No permission" cursor (example) ipsCursor_drag Shows an element can be moved (example) ipsCursor_pointer Shows an element can be clicked (example) ipsCursor_help Shows an element provides help (example) ipsCursor_default Sets the cursor to the default state (example)
    2 points
  25. Rikki

    Template plugins

    It's often useful to transform raw values in some way, and this is achieved in IPS4 with template plugins. Template plugins take a value, and optionally some arguments, and output some transformed value. The syntax for template tags is: {pluginkey="<value>" argument="..."} The value can be a normal string, or it could be a variable coming from elsewhere. Template plugins can always be used in templates, but some can also be used in CSS files. Those that can are identified below. Available plugins {advertisement="$location"} The HTML for the specified ad location Parameters $location - A valid advertisement location {datetime="$timestamp" dateonly="[boolean]" norelative="[boolean]" lowercase="[boolean]" short="[boolean]"} Shows a time formatted according to the user's locale Parameters $timestamp - A timestamp to transform into a date dateonly - Show only the date (with no time) norelative - By default, relative times will be used (e.g. 8 hours ago). To always show an absolute date/time, set this to true. lowercase - By default, date strings will be capitalized where necessary (e.g. Yesterday, 8:32pm). Setting this to true ensures it is lowercase, for use in a sentence. short - Uses a very short date format (ideal for mobile devices) {expression="$expression" raw="[boolean]"} Allows the result of arbitrary PHP expressions to be inserted into templates. The result of the expression is output. Can be used in CSS files. Parameters $expression - A valid PHP expression that produces output of some kind raw - By default, the result of the expression is HTML-escaped. Setting this parameter to true outputs the raw result. Be careful! This can be a security risk. {file="$file" extension="[string]"} Outputs the URL to a file stored by IPS4's file handling classes. Can be used in CSS files. Parameters $file - Either an instance of the \IPS\File class, or a string representing the stored URL to the file extension - The file storage extension used to originally store the file, e.g. calendar_Events. If none is specified, core_Attachment is assumed. {filesize="$sizeInBytes" decimal="[boolean]"} Formats the specified filesize and outputs an appropriate human-readable form. Parameters $sizeInBytes - An integer representing a file size, in bytes, to be formatted decimal - Whether the filesize should be treated as a KB (i.e. 1kb = 1024 bytes) or 1 = 1000. All values are always rounded to one decimal place. {insert="$filename"} Includes a PHP script file Parameters $filename - The filename of the PHP file to include. The output of the file is buffered and output. {lang="$languageKey" sprintf="[string]" htmlsprintf="[string]" pluralize="[string]" wordbreak="[boolean]" ucfirst="[boolean]"} Inserts a phrase from the language system in the user's chosen language. Paramaters $languageKey - The key of the language phrase to insert sprintf - Comma-separated list of values to replace in the language string. These values are HTML-escaped. htmlsprintf - Comma-separated list of values to replace in the language string. These values are not escaped. Be careful! pluralize - Comma-separated list of values to pass into any pluralize statements in the language string. wordbreak - If true, adds <wbr> tags to the returned string to help prevent strings that break the page width. ucfirst - Determines whether the first character of the string should be made uppercase. {member="$propertyToDisplay" id="[integer]" group="[boolean]" raw="[boolean]"} Outputs the property or result of a method called on the member object. Parameters $propertyToDisplay - One of the properties or methods available on the member object. For example: link() or name. id - Member ID to load and display. If not specified, the current member is used. group - If true, this tag works on the member's group instead (and so the $propertyToDisplay should be one of the group properties or methods instead) raw - By default, the returned output is HTML escaped. Setting this to true means the output won't be escaped. Be careful! {number="$number"} Formats a number according to the user's locale (e.g. with commas or periods) Parameters $number - Number to format {prefix="$CSSPropertyName" value="[string]"} Shortcut tag which automatically prefixes the provided CSS property with vendor prefixes. Can be used in CSS files. Parameters $CSSPropertyName - The property name to prefix. The supported properties are: transition, transform, animation, animation-name, animation-duration, animation-fill-mode, animation-timing-function, user-select, box-sizing, background-size. value - the value of the CSS property. {request="$requestParameter" raw="[boolean]"} Inserts the value of a request parameter. Paramaters $requestParameter - The parameter from the request object to be inserted. raw - By default, the returned value is HTML-escaped. If this parameter is true, the output won't be HTML-escaped. Be careful! {resource="$path" app="[string]" location="[string]" noprotocol="[boolean]"} Returns the absolute URL to the specified resource. Can be used in CSS files. Parameters $path - Relative path to the required resource (path is relative to the current theme's /resource directory) app - The app to which the resource belongs. location - The location (front/admin/global) noprotocol - Whether to make the resulting URL protocol-less (i.e. do not include http:// or https:// at the beginning, which can be useful for resources which are not allowed to be loaded over http on an https connection) {setting="$settingKey" escape="[boolean]"} Inserts the value of a system setting. Can be used in CSS files. Parameters $settingKey - Key of the system setting to insert. escape - By default, the raw value is output. If you need the value to be HTML-escaped, pass true for this parameter. {url="$url" csrf="[bool]" base="[string]" seoTemplate="[string]" seoTitle="[string]" seoTitles="[array]" protocol="[\IPS\Http\Url::PROTOCOL_AUTOMATIC|\IPS\Http\Url::PROTOCOL_HTTPS|\IPS\Http\Url::PROTOCOL_HTTP|\IPS\Http\Url::PROTOCOL_RELATIVE]" fragment="[string]" ref="[string]" plain="[bool]" ips="[string]" noprotocol="[bool]"} Generates an \IPS\Http\Url instance of a URL. Can be used in CSS files. Parameters csrf - Adds the CSRF Key to the query string base - The base to use, if this is an internal URL. seoTemplate - The SEO template for this URL to construct a friendly URL. seoTitle - The title to use for the friendly URL. seoTitles - An array of friendly URL titles. Not used if seoTitle is used. protocol - One of the \IPS\Http\Url::PROTOCOL_* constants to define the protocol to use. fragment - Adds a fragment to the end of the URL. ref - Sets a base64 encoded referring URL as a query string to the URL (used in conjunction with \IPS\Request::i()->referrer()). plain - To output the string value of the URL raw. If omitted, the string value is run through htmlspecialchars(). ips - If this is an internal IPS URL to the documentation. Ignores all other parameters. noprotocol - Makes the URL protocol relative regardless of the defined protocol. This is deprecated, and \IPS\Http\Url::PROTOCOL_RELATIVE should be used instead.
    2 points
  26. Selling advertisement space to your customers can easily achieved within commerce by adding a new product within Commerce>Store>Products. Before reading this step, it is suggested that you read the previous step. This step will cover the items specifically relating to selecting advertisements as the product type. When selecting the Advertisement product type, you will be presented with a screen similar to the following. In addition to the many items discussed in the previous step of this guide, you can choose an advertisement location when selecting this type. This will allow you to sell ad space in one or many locations directly to your customers. You will also be able to set an expiry period for the product, as well as the maximum dimensions for any banners which are uploaded. This allows you control over the size and period that a banner is show for. Any which are purchased will show up within System>Site Promotion>Advertisements as a pending advertisement. This enables you to ensure that the ads are suitable for your site before showing them.
    2 points
  27. Marc Stridgen

    Upgrading themes

    When a new version of the software is released, there will inevitably be changes to the default templates in which would need to be replicated in your own custom themes. On an upgrade, only unedited templates would be upgraded automatically, and therefore this would be for yourself to upgrade any templates which cannot be upgraded. There are a couple of tools available for you in order to achieve this. Each of which is explained below. Theme differences The theme differences tool is an external tool which can be found in the following location on our site https://invisionpower.com/index.php?app=core&module=system&controller=plugins&do=diff This tool will allow you to see the differences between any 2 versions of the 4.x software, from 4.0.0 right up to the current version. Once you have selected the versions to compare, you will then be shown all changes between templates on the 2 versions in which you selected in a similar format to the below. Red showing what has been removed, and the green showing what was added Comparing within the admin CP Whilst within a template in your custom theme, you can compare that to the default, unedited version of the same template directly from the admin CP. First of all, you would take a look to see which items within your custom theme have been modified. You can do this using the selection menu at the top of the template list, to select only modified templates. This will enable you to quickly find all templates that you may need to look at after an upgrade. Once you have found and opened a template that you are working on, you will see a tools button in the top right of the screen. Clicking on this will show an option for you show the default. Tip If you simply need to change the template to be that of the default template, you can use the Revert button, also shown in the image below, to achieve this. Once you have selected this, you will see the default template is placed alongside, with any changes to the default indicated, as shown below. Note that you can edit directly on the right hand side to make any changes needed.
    2 points
  28. The IPS Community Suite has built-in support for languages that use right-to-left text (including Arabic, Persian and others), and if you are creating a theme to share with others, you should ensure it is compatible with right-to-left display. Doing so is easy. RTL-specific CSS When RTL display is used, certain CSS properties need to be reversed; for example, if you position something left in LTR languages, when shown in RTL it would need to be positioned right instead. The global template in IPS4 always has the dir attribute specifying the text direction (the value is either ltr or rtl), and it is this attribute we can use to add direction-specific styles. Let's imagine you have some CSS in your theme like this: .yourClass { font-weight: bold; position: absolute; left: 15px; top: 15px; padding-left: 30px; } Some of these styles need to be separated out for RTL or the theme won't look right. So, by using the dir attribute on the html tag, what we instead need to write is: /* These styles are the same regardless of text-direction */ .yourClass { font-weight: bold; position: absolute; top: 15px; } /* LTR styles */ html[dir="ltr"] .yourClass { left: 15px; padding-left: 30px; } /* RTL styles */ html[dir="rtl"] .yourClass { right: 15px; padding-right: 30px; } That's it! RTL languages will now correctly position the element on the right-hand side of the screen, while LTR languages will show it on the left as expected. Whenever you use styles impacted by text direction, you should split them out in this way. RTL-specific icons The IPS Community Suite makes extensive use of FontAwesome icons. Some of the icons need to be flipped for RTL languages (such as arrows) and if you use the standard classnames (e.g. fa-caret-left), we automatically flip these so that they are correct for RTL languages. If you manually specify icons in your CSS classes using the unicode code, you will need to adjust them for RTL so that their opposite icon is used. For example, if you do this in your CSS: /* This uses the unicode for FA's 'angle-right' icon */ .nextLink:after { font-family: 'FontAwesome'; content: '\f105'; } You will need to change it to be: .nextLink:after { font-family: 'FontAwesome'; } html[dir="ltr"] .nextLink:after { content: '\f105'; } html[dir="rtl"] .nextLink:after { content: '\f104'; } Consider your Javascript This usually will not require any action. However, if you have any custom JavaScript which adds user interaction, consider if any changes need to be made. For example, if you have a menu which opens from the left, it may need to open from the right. If you are only using the UI widgets already in the IPS Community Suite, these already make all such considerations so no action will be necessary.
    2 points
  29. You can set up gift cards on the system, which will allow your customers to purchase gift cards for people to use on your site. To set these up, you would visit the following area within your admin cp. Commerce>Store>Settings>Gift Cards Setting up gift card settings When first visiting this area, you will see the following screen. You can then set up various set amounts that your members can purchase along with optionally allow their own amounts if you wish to do so, as you can see I have set up below. Purchases gift cards Your members can then buy gift card from the store on the section on the right When selecting to buy a gift card, you can then select a colour, a message for the person who is to receive this. You can then either print or email these to the person they are for. Using Gift Cards Your members can use gift cards using the redeem button shown in the image above (next to the buy button). They will then be asked for the gift card code which can be seen on the gift card itself. Upon entering this, the credit will be added to the account for purchasing items in your store with.
    2 points
  30. While the theme system allows almost limitless customization possibilities, there are a few best practices that we recommend you follow. They will make things easier for both you and site admins who choose to use your theme. Don't edit default CSS files Whenever a default theme file is edited, it makes upgrading a site a little more difficult because the customizations have to be handled. This is an easy problem to solve for CSS because by its nature it cascades - that means you can create your own CSS files that overwrite styles defined in our default CSS files, without impacting the ability for the suite to update the default CSS file later upon upgrade. By way of encouragement, we ship an empty CSS file called custom.css which you can use as a starting point for your changes. For simpler themes, keeping your changes in this one file might be sufficient. However, you can create more custom CSS files in the custom group if you wish, and they'll be automatically included (no need to use @import statements). The IPS Community Suite always includes your custom CSS files last in the loading order, so you can use the same selectors you see in the default CSS files and your new styles should overwrite the default. Keep template changes to a minimum Similar to the above, editing templates can lead to difficulty with upgrades, because customized templates may be missing new HTML necessary for a new feature, or worse, break the templates by calling a variable that has since been removed. However, unlike CSS files, templates can't cascade, and sometimes editing a template is the only choice. Therefore, we recommend you try to keep these edits to a minimum. There's a few strategies for doing so: Use CSS where possible It may be tempting to adjust the HTML in templates to help achieve some particular visual style. We recommend exploring using CSS to do this instead wherever possible because it will make maintaining your theme much easier in the long run. Use template includes and custom templates where appropriate If you're adding a larger block of HTML to a template (more than a couple of lines), consider putting that code in a custom template bit instead, and then calling that template from the default template. That way, the customization to the default template is a simple include tag that can easily be reverted and added back later without much effort. To call a custom template, you can do: {template="myCustomTemplate" group="<group>" app="<app>"} where <group> and <app> are the keys for the location you chose when you created your custom template bit. Consider creating a hook instead Application hooks have the ability to adjust templates by 'hooking' into the code inside them. In some situations, using a hook to adjust the template may be more appropriate that editing the template contents directly. Remember mobile support The IPS Community Suite has been designed from the ground up to be responsive; that is, the same theme works on devices regardless of screen size, whether it's a desktop monitor or a phone. When you make changes to your theme, remember to consider mobile support and ensure you include responsive styles too. You can use a tool like Google Chrome's web inspector to mimic different screen sizes, or use a tool like BrowserStack to test your theme on real devices Remember right-to-left support The IPS Community Suite is designed to work fully with both left-to-right (LTR) and right-to-left (RTL) languages. If you are creating a theme that you plan to share with others (rather than one just for your own use), keep RTL support in mind. The next step of this guide covers some steps you can follow to support it.
    2 points
  31. Rikki

    Messages

    Description The messages module provides a way to style informational messages to bring something to the user's attention. Usage To create a message, simply add the ipsMessage class to a container element (e.g. div), along with one of the message styles below. The message style class will automatically add the appropriate icon to your message box. Message styles Error - ipsMessage_error This is an error message. Success - ipsMessage_success This message indicates something happened successfully. Warning - ipsMessage_warning This message warns the user of something terrible (or not so terrible). Information - ipsMessage_info This message provides general information. Message codes If you need to add a code to your message, such as an error number, you can do so using the ipsMessage_code class: <div class='ipsMessage ipsMessage_error'> <span class='ipsMessage_code'>12345</span> This is an error message. </div> 12345 This is an error message.
    2 points
  32. Rikki

    Databases part I

    What is a database? Databases are one of the most powerful and flexible features available in the Pages application. With some configuration and customization, they enable you to add complex, data-driven areas to your community, using some of the basic underlying functionality that full IPS4 applications have. Databases, as the name implies, are designed to hold data and display that to the user. This might be as simple as a table of records each containing a title and a body, from which you could make a very simple blog-like section, or it might be as complex as a completely custom interface backed by a large number of custom data fields specific to your needs - and the possibilities for this are endless. Features Searching Databases are searchable by default (although you can turn this off if desired). Each database is treated as a distinct area of your community, so on the search form, each database is listed as a first-class area to search, much like the Forums app for example. Core suite features Pages provides a range of core application features to databases that make even the simplest database feature-rich and well-integrated with your community from the outset. Commenting and writing reviews for records is available (although this can be disabled per-database). Users can also follow categories and records to be notified of new content wherever they are in the community. Social features such as reputation and sharing to other social networks is also built-in and available for records. Tagging and full moderation of records is also supported by default, and integrated across the suite as you'd expect. Wiki-style editing In terms of adding/editing records, databases in Pages behave much like you'd expect from our other applications; that is, when a user with permission creates a record, they 'own' it. However, databases have an option for wiki-style editing, whereby any user can edit records after they are created. This approach is great for community-curated content. Revisions Databases also support revisions for records. This means each time a record changes, the previous version is saved as a revision that can be accessed again later - you can also revert to an earlier revision if desired. Forum Integration Finally, databases has special integration with our Forums app. When posting a new record to a Pages database, IPS4 can optionally cross-post the record as a forum topic, to a category of your choosing. But it goes further - you can even use the forum topic as the comments for the record, rather than the standard commenting interface that records have. What does a database consist of? There's a few key components in a database to be aware of when creating one: The database itself Naturally, you need to create the database itself. This is where you configure options that affect that database as a whole, such as sorting, permissions, and so on. Categories If your databases uses categories (you can optionally choose not to), they add another level of structure and permissions. Fields We'll cover fields in more depth shortly, but you can create custom fields for all kinds of data that you might need for your database. IPS4 supports a wide range of field types, from simple text boxes up to YouTube embeds, upload fields and intra-database relationships. Templates Templates allow you to customize the output of the database. Default templates are supplied with IPS4, and if you aren't a coder, using these defaults allow you to get a database up and running quickly. For coders, however, customizing templates is the best way to build complex data-driven applications. Templates, CSS & JS
    1 point
  33. Charles

    Storage Configurations

    There are four standard file storage options you can choose to configure. Most will use the default File System option which stores files on your local server. Any option can be used for a Content Distribution Network (CDN) if you choose to use such a service. You can create multiple storage configurations to mix and match storage for various areas of the Suite to suit your needs. File System Default option which is sufficient for most environments. This stores files on your local server with no special configuration needed. Amazon Web Services (AWS) S3 Remote storage system recommended for very busy sites. Service fees apply. AWS S3 Setup Database Use if you do not have much file storage space available or file writes are undesirable for your server environment. Will require more server resources to display a file. For database storage no configuration is needed. Your files will be stored in MySQL in a BLOB column type. This takes more resources but is sometimes the only option available based on your environment. Using a CDN All storage options, excluding Database, can be used with a CDN. You will see a "Use Custom URL?" option under those options where you can override the default URL to use a CDN. You will need to contact your CDN provider for instructions on the proper URL to use. As an example here, I have visited System>Overview>Files>Storage Settings>Configuration and selected to edit one of my Storage methods (in this case my uploads) Editing your storage settings We can then switch on the "Use a custom URL" settings and add in our CDN URL as shown below. Enable a custom URL
    1 point
  34. Share Icons You can place links to share content to other social media such as Facebook and twitter. You will see these links below any content on the site. Here is an example from a topic. Share icons Share Permissions If you visit Sharing you will see all of the sharing sites that you can currently use. You can disable any of these completely at any time. Simply click the "Enabled" button and this will change to "Disabled" Shares Available If you click on the pencil icon at the side of any of these, you will be presented with options for which user groups can use any individual share link, along with any other options which may be relevant to that share link. Below is an example of the options for Twitter. Edit Share Option Social Sign In You can enable social networks like Facebook, Twitter, and more as an option for your visitors to register or login on your Community. Existing members can choose to link their accounts to one or more social media platforms to enable a more integrated experience. Setting up social media integration varies by network. Facebook Twitter Microsoft LinkedIn Another Community Instance Wordpress External Database
    1 point
  35. On the front end of your community, moderators can moderate your site depending on the permissions that you have given them to do so. Moderation can be done at an item level, or the level of its container. For example you may moderate individual posts from the topic screen, or moderate topics from the forum screen. Content Moderation Whilst within a post or topic, if you hover over the topic or post you wish to moderate you will see a checkbox appear in the top right of that item. Selecting this will add this to the items that you are currently moderating. Once you have selected at least one item, you will see the moderation menu appear at the bottom where you can select the action you wish to perform. You can see this in action in the animation below. Moderator Bar In some of the other areas of the community, you may find moderator actions under a button, such as you can see here in a gallery image. Moderation Menu Items Tip Within each item of content you will see a moderator actions menu. You can perform similar actions from here, and also see the moderation history for that particular item. Depending on where you are within the system, the moderation menu will show different actions. Below is another example where posts in a topic are being hidden from the end user. Inline Selection Post Approval There may be times when you need to switch on approval for replies within an individual topic. You can select this option from the 'Moderation Actions' menu, which will then mean each reply will need to be approved before being seen Post Approval Automatic Moderation There comes a time when your community is so successful that it can be a little tough to keep up with all the content and reports. To help with this, you can make use of our automatic moderation feature, which performs actions when an item of content is reported by a user of your community. This feature leverages your member reports to automatically remove objectionable content from public view. You as the admin will define thresholds for the content. For example, you may say that to hide content, a post needs 5 reports. This reduces the workload for your moderators and enables you to crowd source moderation. Community Moderation When a member reports a piece of content, they now have the option to set a type, such as "Spam" or "Offensive". These options can count towards the threshold. Once the threshold has been passed the item is hidden. Options when a user reports This threshold can be set up by creating rules in the Admin CP as shown below Report Types Before you can create your own rules for automatic moderation, you must create 1 or more report types from the following location. Once you have done this, you can then continue to setting up rules for auto moderation. Members -> Content Moderation -> Automatic Moderation -> Manage Report Types Any report type can be added here Creating Rules At its heart of the system are the rules. You can create custom rules within the ACP from the following location Members -> Content Moderation -> Automatic Moderation Rules set within the ACP For example, you may decide that: A member with less than 10 posts only needs 5 reports to hide the content. But you may want to give more experienced members a higher threshold as there is more trust. You simply add a new rule: A member who joined over a year ago with over 500 posts needs 10 reports to hide content. You can do that easily with the rules system as it will scan them all and pick the one most suitable for this member. Notifications Once an item has received enough reports to match the threshold, it is automatically hidden from view. Meaning it can then be dealt with by a moderator at an appropriate time, without the reported post being an issue to your members. Post is hidden on auto moderation A notification is sent to all moderators who opt in for notifications. This notification shows inline in the notifications center. Inline notification It can also optionally be sent via email for those who want to know without checking the site. Notification sent via email Of course, a moderator may decide that the content is fine and un-hide it. Once a piece of content has been un-hidden, automatic moderation will not hide it again. Preventing Abuse The system will only count a unique member as one point towards the threshold. This is to prevent a single member can reporting an item 5 times, as they are only counted once towards the threshold. You can also set a time limit between reporting the same item. This will prevent a member reporting a single item multiple times in succession. These settings can be found within the following area Members -> Content Moderation -> Automatic Moderation -> Settings Set limits to prevent abuse of this feature Of course, the member can delete their report if it was in error. Clicking report again gives the option to delete
    1 point
  36. S3 is a reliable, scalable cloud storage service provided by googles AWS platform. Using AWS, for some, may be a cost effective and faster way to store data outside of your usual hosting environment. The following guide shows how to set up S3, alongside your Invision Community setup. Note that this guide is correct at the time of writing, and screens may vary from time to time on the AWS console. If you have not set one up already, please first of all ensure you have created an amazon AWS account. You can do this at the following location. https://portal.aws.amazon.com/gp/aws/developer/registration/index.html Creating an S3 bucket When you first log into AWS, you will need to add an S3 storage service to your account. Using the search box provided, type in S3, and select the S3 service Finding S3 in AWS Once you have selected the S3 service, you will be able to create a new S3 'Bucket'. A bucket is simply an area where you will store your data, within the S3 service. Click on create bucket to get started with its creation. Create a New Bucket On the first screen you will be asked for a bucket name, and a region. Choose the region which is closest to the majority of your users, and give your bucket a name. The name can be anything you wish. In this example I have used 'myinvisionbucket' Choosing Name and Region Once you have added the name and chosen your name, click on next. You will see the following configure options page. If you are unsure on what these are, please leave them on their default setting before clicking next again Configuration Options Now we are at the permissions page. As we are storing items which must be accessible to public (they are viewable to people on the web in general) you need to deselect the "Block all public access" item. Ensuring Public Access Select to state you acknowledge the items will become public, and click on next Agreement to Public Access Finally, select "Create bucket" to create the new S3 bucket you will be using on your site Create Bucket Your new bucket is new created and available for use on your site. You can proceed to set this up within the Admin CP of your site Creating Credentials Before we can go ahead an set up the storage method in our admin CP, we need to create a set of credentials to use with the S3 bucket. In order to do this, you need to visit the Identity and Access Management (IAM) settings page of your AWS account. You can find a direct link to this here https://console.aws.amazon.com/iam/ Once here, we need to first create a group which has full access to your S3 location. Select Access Management -> Groups from the menu on the left. Then Click on "Create New Group" Creating a Group Give it a group name, and then click next step. You will then be given a list of items to select from. Search for S3, click the checkbox at the side of "AmazonS3FullAccess" and click next. Policy Selection You can now click on create group, which will take you back to the first page. On the left, under groups, you now need to click on users, and click "Add User" Create User Give the user a name, select "Programmatic Access" then click "Next: Permissions" User Setup Screen On the next screen you will see the name of the group you previously created. Select Group Click the checkbox for this and Click "Next: Tags", then "Next: Review" and finally "Create User" Here you can see your Access ID, and Secret Access Key (click show). Copy these out somewhere so that you have these in the next steps. Setting the storage method In order to set up the new storage method, visit the following location within your Admin CP System -> Overview -> Files -> Storage Settings -> Configurations Once in this location, select to create a new storage method Creating New Storage Method Once you have done this, select "Amazon S3" from the storage method options at the top of the page. We then need to set up an access key and add the information into your Admin CP as we go. The items in the image below are numbered corresponding to the descriptions below Storage Method Options The first item you need to add is a bucket name. This is the Bucket Name you used in the first step of this guide. In our example case, we used myinvisionbucket. The endpoint will be different depending on what you have set up as your region in previous steps. The link below this item will take you to the AWS help guides where you can find the end point name. First of all find this in the list. I have used Europe (Ireland), and therefore I need eu-west-1 for part of my endpoint URL The 'Endpoint' you will enter is the following, where {yourRegion} is replaced with the region name you got above. s3.{yourRegion}.amazonaws.com So in our scenario, we will be using s3.eu-west-1.amazonaws.com The 3rd and final part of setting up the storage method, is to enter the access key and secret. These are the values you copied from creating your user in the previous stage of this guide. Choosing what to store Now that you have created a new storage method connected to your S3 bucket, you can choose what you wish to store in amazon S3. Go to the following location to do this System -> Overview -> Files -> Storage Settings From here, use the dropdown on any of the items to change the storage method to your amazon S3 bucket. If there are items which exist already, a background task will be created to move these to the new location. Changing Storage Method
    1 point
  37. Marc Stridgen

    Customer Referrals

    Customer Referrals can be a good way in which to drive sales on your site, as you can get your customers doing the work for you, giving a small benefit to the customer who is referring people to your site. Within the admin CP, you can get to the referal setup section by going to Commerce>Customers>Referrals. Switching On Once you enable referrals and save them as being on, you will see 3 tabs. The first section you will see will look similar to the screen below, and allow you to switch the system on and off, and to set whether your customers can see the commision rules. In most cases you would leave this on, however if you set up complicated rules, you may wish to switch this off. Switching this off will give you an editor where you can add information to show about the commission received instead. Referrals Main Settings Setting Rules The next tab will show you a list of the commission rules currently set up, and give you the ability to add new ones. Clicking on "Create New" will give you a screen similar to the below. From this screen you can set up a commission rule set, along with the percentage of that sale you would pay the referrer. Commission Rules Referral Banners You may want your customers to use referral banners if they are advertising your site or products. You can add in as many banner as you wish within the Referral Banners tab, which will then be shown to your customers for use when referring people to your site, along with the links for these in html and bbcode. Banner Setup On the customer side Warning It is important to note, that referrals will only apply to new registrations made via the referral links discussed below. If the purchaser is already a registered member of your site, then no referral commission would apply, regardless of the link followed. By default the referrals section on the front end of your site is under Store>My Details>Referrals (of course you can change this using the menu manager). Here they will see their unique links to give to people when referring others to your site. Anyone using these links will be shown as referred by the person who's link they used. Customer Side
    1 point
  38. Rikki

    Styling CKEditor

    The IPS Community Suite uses CKEditor to power its rich text editing capabilities. Often, when developing a theme for you own community or for distribution, you'll also want to style the editor to match. CKEditor itself is a very large and complex project. It has many hundreds of CSS classes, and explaining how to style each part of the editor is beyond the scope of this guide. We recommend you check out CKEditor's website if you need more information. That said, here's some tips to guide you. Using custom.css to style the editor Prior to IPS 4.1, we used CKEditor's older iframe mode. What this meant is that the entire text editor existed inside of an iframe on the page (although this was seamless and transparent to users). Since styles of a parent page do not apply to the contents of iframes, the only way to style the editor was to edit the CKEditor skin that we shipped with the product. This meant working outside of the IPS4 theme system, but more importantly it made distributing your changes more difficult because you'd also have to distribute your CKEditor skin. In IPS 4.1 onwards, we use the newer div mode. Instead of using an iframe, the editor is built inside a div element right on the page. This is great news for themers, because it means the CSS styles you create within IPS4 will be inherited by CKEditor automatically. So, to start styling the editor, you can simply open your custom.css file in your theme, and using a tool such as Google Chrome's Web Inspector (or the equivalent in your browser of choice), inspect the HTML that CKEditor generates and use that to develop your styling. When you save your custom.css file, you'll see it applies to the editor too. Above: inspecting CKEditor's generated HTML with Web Inspector allows you to see which CSS styles (right) are being applied to each part of the editor, helping you identify which class names you should be using in your own CSS. Or build a standalone CKEditor skin If you intend to make more substantial changes to the editor, you may still want to consider developing it as an actual CKEditor skin instead. CKEditor has a very mature skin framework that can be used for advanced changes. Consult the CKEditor for more information on creating a skin. If you go this route, you would export the CKEditor skin, and ship it with your IPS Community Suite theme. When an administrator installs your theme, they can install the CKEditor skin in the AdminCP too. So, that seems quite straightforward - in almost all cases, simply edit the custom.css file you use in your theme, and you can customize CKEditor to match your theme! But, there's gotchas... There are exceptions, of course. Even in div-mode, CKEditor still generates some iframes. For example, when you click a dropdown menu in the editor (e.g. Font), CKEditor actually builds an iframe for the menu. This introduces the same problems we discussed above, again! Unfortunately, there is no simple answer here. As before, styles you build into your custom.css file won't apply to these special areas where CKEditor uses an iframe. For many theme designers, this won't be a huge problem - being able to edit the 95% of CKEditor available to custom.css will be sufficient. But if you really do need to style the contents of those iframes, the only option is to do it within CKEditor's own skin system (since it loads those CSS files within its iframe). This isn't too problematic if you're only concerned with styling your own community. The CSS files CKEditor uses can be found in /applications/core/interface/ckeditor/ckeditor/skins/ips (if your theme uses the default CKEditor theme we provide). Edit the editor.css file in this directory to adjust the styles (this is a compressed CSS file, so add your own CSS at the end - don't edit existing CSS in the file!). If you plan to distribute your IPS4 theme, however, and you need to style these areas of CKEditor that still exist in an iframe, you'll need to go back to using CKEditor's skin system, and distributing a CKEditor skin with your theme.
    1 point
  39. By default, IPS4 has a maximum body width of 1340 pixels, and is fluid at sizes smaller than this. However, we ship the software with a customizable theme setting allowing this to be easily overridden, should you want to change the behavior. Using the Easy Mode theme editor If your theme was made using the Easy Mode editor, you can adjust the body width on the Settings tab when designing your theme. First, click the magic wand icon to launch the Easy Mode editor: And then the Settings tab. There's two settings you need to adjust; turn on Enable Fluid Width, and then change the percentage value in the Fluid Width Size setting. To have it take up all available space, set this to 100%. Using the standard theme editor If your theme was created using the standard theme editor in the AdminCP, you adjust the theme settings also in the AdminCP. Click the edit icon next to the theme you want to adjust: And on the Custom tab on the edit screen, you will see the Enable Fluid Width and Fluid Width Size settings.
    1 point
  40. Rikki

    Variables

    Each template bit can have variables passed into it by the backed PHP code, and these variables can be used by the template bit to control the display. Consult either the template editor or designer's mode guides (depending on your preference) to find out how to determine which variables are available to a template. As well as these local variables, you can access the various objects created by the IPS4 PHP framework. Variables are escaped It's important to note that by default, all variable values are HTML-escaped when you output them in templates. This is for security, and ensures you don't inadvertently output some malicious HTML that is then processed by the browser and displayed. If a variable $value contained: <strong>Example</strong> Then outputting it in a template like so: Here's the variable value: {$value} Would actually send: Here's the variable value: &lt;strong&gt;Example&lt;/strong&gt; This is safe for the browser to display. Bypassing this protection Of course, in some situations, you want the raw HTML to be output, and not escaped. To do so, you can use the raw modifier on the variable: Here's the variable value: {$value|raw} Warning Using this modifier on untrusted content is a security risk. You should not output raw user-supplied HTML unless it has been properly sanitized and you are certain it is safe. Content that comes from IPS4's rich text editor is safe to output with this modifier.
    1 point
  41. Rikki

    Plural phrases

    Why plurals are treated differently Many of the phrases used in the IPS Community Suite are plurals. Some examples are: 21 replies 3 comments You have 10 new notifications In English, a plural typically has an 's' for multiple, and no 's' for singular. In other languages, the rules may be more complex and require a specific format depending on the exact number. To facilitate these nuances, the IPS Community Suite uses a special syntax for phrases that refer to a plural items. The language system passes the value being used into the phrase, and the special syntax can use this value to determine which words to show. Syntax The syntax for plural phrases looks like this: {# [1:reply][?:replies]} There's a lot that this syntax allows, but this is the basic usage. It's made up of definitions that are applied depending on the number passed into the phrase for replacement. Let's step through each part of this. {...} The plural replacement always needs to be enclosed in curly braces so that the suite core can recognize it. Note that the plural replacement can appear inside another phrase if the rest of the phrase isn't plural-dependent. For example: "You have {# [1:new notification][?:new notifications]}" # The next character is typically the pound/hash symbol. When it appears at the start of the replacement, this symbol is replaced with the actual number passed into the plural. Alternatively, if you use !# then the number is not included. {# [1:reply][?:replies]} {!# [1:reply][?:replies]} becomes: 10 replies replies [x:reply] The next block is the replacement option, of which there can be several. These are enclosed in square braces, and you can have as many as needed for your language. The block begins x:, where x is a number, indicating that this replacement is used when the number passed into the phrase is exactly x. If your language requires a different plural form for certain numbers, you can repeat the block for each. There's three special symbols you can use for 'x' here: *1: Matches all numbers that end in 1, e.g. 1, 11, 21, 251 %1: Matches all numbers that start with 1, e.g. 1, 10, 12, 163 ?: Matches all other values that aren't matched by another block After the colon : is the string value used if this block matches. Note that the values in these blocks can use the special character #, which like above is replaced with the actual value passed into the phrase. This is particularly useful where the phrase does not need to show the number except in certain circumstances. For example: "Every {!#[1:year][?:# years]}" In English, saying "Every 1 year" would be odd, but for other values you would say "Every 3 years". So in this case, we use !# at the start of the replacement so that the number isn't automatically added, and then use # in the second block so that our string contains the number only if that block is used.
    1 point
  42. On occasion you may wish to override the theme choice members have made (for example, when you install a new default theme). The IPS Community Suite allows you to do this easily on a per-group basis. Navigate to Customization -> Themes in the AdminCP, and click the dropdown arrow next to the theme you want to force as the selected theme. Select Set as Members' Theme from the menu: In the popup window that will appear, you can choose which groups (or all of them) to reset. For example, if a member in the Members group had chosen the Green Theme to use, by using the Set As Members' Theme and selecting the Members group on the Red Theme, that member's choice will be reset and they'll see the Red Theme in future.
    1 point
  43. Rikki

    Introduction to themes

    What is a theme? A theme is a package that changes how the IPS Community Suite looks. By default, the software has a blue theme (it's the one you see here on our own community), but with themes you can completely change that, including colors, fonts, images and much more. With a little skill, your imagination is the limit! Above all, themes are a great way to keep consistent branding between your main website and your community. Where do you get themes? Themes can come from a few different sources, including: Our Marketplace, for free or paid Created yourself using the Easy Mode editor Created yourself using the full theme editor (for advanced users) Some designers run their own sites that offer ready-made themes for purchase/download You can hire a designer to create a theme especially for your community Multiple themes Although many communities have one theme that matches their brand, it's also possible to install multiple themes and let users choose between them. You can select a default as your 'main' theme, and users can choose their own preference from the theme selector at the bottom of the page. You can even restrict themes to certain member groups, allowing you to have 'premium' themes for paid members (for example). We'll cover how to do all this and more in a later step.
    1 point
  44. Rikki

    Layout: Grids

    Description The grid module provides classes for building layouts based on a flexible 12-column grid, with automatic margins, and with additional classes to enable the layout to collapse properly on smaller devices. Usage A grid should be made up of a wrapper element with the class ipsGrid, and direct descendants with appropriate size classes applied (see below). For example: <div class='ipsGrid'> <div class='ipsGrid_span3'>Span 3</div> <div class='ipsGrid_span3'>Span 3</div> <div class='ipsGrid_span4'>Span 4</div> <div class='ipsGrid_span2'>Span 2</div> </div> This would render as: Span 3 Span 3 Span 4 Span 2 Grid classes ipsGrid_span1 through ipsGrid_span12 are available for the various column sizes. Wrapping Grid Items Elements in a grid will automatically neatly wrap to new rows, providing every item in the grid uses the same span width and height, without you needing to manually create new row structures. For example: <div class='ipsGrid'> <div class='ipsGrid_span6'>Span 6</div> <div class='ipsGrid_span6'>Span 6</div> <div class='ipsGrid_span6'>Span 6</div> <div class='ipsGrid_span6'>Span 6</div> </div> Span 6 Span 6 Span 6 Span 6 For grids where your items may differ in height or width, consider the ips.ui.grid widget instead. Responsiveness To cause the grid layout to collapse on smaller devices, add either ipsGrid_collapseTablet or ipsGrid_collapsePhone to the class list on the wrapper element, like so: <div class='ipsGrid ipsGrid_collapsePhone'> ... </div>
    1 point
  45. Rikki

    Layout: Columns

    Description The column module, unlike the grids module, provides classes that enable layouts comprising both fixed and fluid columns to be easily created. This is a layout often used for fixed sidebars with fluid content areas, for example. Additional classes are available to collapse the layout on smaller devices. Usage A column layout consists of a wrapper element, with the column elements as direct descendants of the wrapper. No other layout classes should be applied directly to the column elements. An example of a column layout: <div class='ipsColumns'> <div class='ipsColumn ipsColumn_medium'>Fixed column</div> <div class='ipsColumn ipsColumn_fluid'>Fluid column</div> </div> This would render as follows (background colors and padding added for clarity): Fixed column Fluid column The wrapper receives the classname ipsColumns (note: plural), while individual columns receive the classname ipsColumn (note: singular). Column Sizing A number of different classnames are available to change the column sizing. One of these classes should be applied to each column in addition to the base ipsColumn classname. ipsColumn_veryNarrow - 50 pixels wide ipsColumn_narrow - 120 pixels wide ipsColumn_medium - 200 pixels wide ipsColumn_wide - 280 pixels wide ipsColumn_veryWide - 360 pixels wide ipsColumn_fluid - Takes up remaining space; should be used on all fluid columns Border Spacing By default, no spacing is provided between columns (see example above). Spacing can be included around columns by using one of the three following classnames on the root ipsColumns element: ipsColumns_verticalSpacing - 15 pixels vertical spacing ipsColumns_horizontalSpacing - 15 pixels horizontal spacing ipsColumns_bothSpacing - 15 pixels spacing on all sides The spacing can be halved by also including the ipsColumns_halfSpacing classname. <div class='ipsColumns ipsColumns_bothSpacing ipsColumns_halfSpacing'> <div class='ipsColumn ipsColumn_medium'>Fixed column</div> <div class='ipsColumn ipsColumn_fluid'>Fluid column</div> </div> Fixed column Fluid column Responsiveness To cause the layout to collapse on smaller devices, add the classnames ipsColumns_collapseTablet or ipsColumns_collapsePhone to the wrapper element. Columns will collapse into source-order, one after the other.
    1 point
  46. Introduction In order to properly differentiate between CSS classes and HTML elements that form part of the IPS4 framework and those that do not, and in order to create a logical structure that can be understood at a glance, naming conventions are applied as follows. Framework classes & elements The IPS4 CSS framework is split into loosely-defined 'modules'. A module groups together related styles in a single file, with the aim of making it clearer which styles will be applied to a given element, and also to make it easier to find those styles to edit in the CSS files. All framework classes and elements take the name format ipsModule, where Module is the type of style being defined. Within a module, additional classes can be defined in the format ipsModule_option. Note that the module name and module options both use lowerCamelCase notation, with the module name and option separated by an underscore. Normally, an element will receive the base module class, plus some options. There are some cases where only the option class is needed; see individual module documentation for details. In general, the framework shouldn't be used with element IDs, since this restricts their use to one per page. The exception to this is aspects of the layout module, where page structure will naturally only exist once. Example of framework names: .ipsMenu .ipsTabs_item #ipsLayout_mainArea .ipsComment_hasChildren Writing CSS for custom themes As a rule, you shouldn't edit the framework CSS files directly. Doing so is prone to breaking future updates, or at least making it harder to upgrade your site between versions. Instead, all of your changes should live in the custom.css file at /core/front/custom/. You can create other CSS files within the custom directory if you wish and these will also be included. CSS files in the custom directory are not modified by the IPS4 upgrader, meaning your changes will safely persist across versions. Determining which elements use which CSS classes When editing your theme, we recommend you make use of the developer tools available in your browser to inspect the page and find out which CSS classes are applied to elements. Consult the documentation for your choice of browser to find out how to do this. This is an example of Chrome's Web Inspector: Writing CSS for custom applications CSS for your custom applications belongs in the <app>/dev/css/front/ directory. Consult the PHP framework documentation for information on using CSS files you create here.
    1 point
  47. Rikki

    Controllers

    Overview Controllers are special modules that handle specific functionality on specific pages. They are not necessarily reusable in different contexts, although some may be. A controller is initialized on an individual element, and that element becomes the controller's scope. A controller responds to user events (such as click) and events triggered by UI widgets or sub-controllers, and manipulates its scope element accordingly. The scope of a controllers functionality is entirely flexible. A controller might be initialized on a very small fragment of the page and perform just one task, or it might be initialized on a main wrapper and handle functionality that applies to the whole page. A controller can be initialized on an element even if it's a descendent of another element with a controller; this is a common pattern whereby the child controller can emit events that the parent controller can respond to. Generally, keep a controller narrowly focused on one aspect of the page. If a controller ends up handing distinct and unrelated functionality, split it into smaller controllers. Creating a controller A controller is registered in a slightly different way to standard modules; instead, an object literal is passed to the method ips.controller.register: ;( function($, _, undefined){ "use strict"; ips.controller.register('type.controllerID', { initialize: function () { // Controller events are initialized here } }); }(jQuery, _)); A controller, at the very least, must define an initialize method, which is called when the controller is initialized on an element. The initialize method should set up events that are handled by this controller only; if other initialization tasks are necessary, it is recommended that you define a setup method within the controller, and call that at the start or end of the initialize method as appropriate. Within the controller definition, this refers to the controller instance. That means controller methods can be called internally with this.someMethod(). A reference to the element that the controller is initialized on (its scope) is available with the scope property: // An example which hides the element this.scope.hide(); Method and property names For clarity, it is recommended that event handler method names (i.e. the handlers to events you set up in initialize) are not prefixed with an underscore, while other methods and properties of the controller are. This helps create a clear distinction between core functionality of the controller (the event handlers) and supporting methods. Handling events Event handling is the core purpose of a controller. There are three special methods available for watching and triggering events. Two are named after their jQuery counterparts, but add controller-specific behavior. this.on Used for watching and responding to events. this.on( [element elem,] string eventType [, selector delegate], function callback ); elem A reference to the element on which the event will be watched for. If not specified, this.scope is used by default. eventType The event being watched for. This can be a default browser event, like click, or events from widgets and models, like menuItemSelected. delegate A delegate selector can optionally be specified. See the jQuery documentation for more information. callback A callback function, called when this event is observed. The function specified here is automatically bound to this, so internal methods can be passed simply by referencing them like so: this.on( 'click', this.internalMethod ); this.trigger Used to emit events that originate from this controller (specifically, the scope element). this.trigger( [element elem,] string eventType [, object data] ); elem A reference to the element on which the event will be triggered. If not specified, this.scope is used by default. eventType The event being triggered. data An object containing data relevant to the event. this.triggerOn Used to emit events directly on sub-controllers from a parent controller. this.triggerOn( string controllerName, string eventType [, object data] ); controllerName The controller name to find and trigger the event on. The wildcard character (*) is supported at the end of this parameter and the event will be triggered on all matching controllers. Examples: core.front.core.comment core.front.core.* core.* eventType The event being triggered. data An object containing data relevant to the event.
    1 point
  48. In IPS4, most javascript is split into self-contained, named modules. Modules and javascript files have a one-to-one relationship - each javascript file should contain one module only. Modules prevent variables leaking into the global scope (which must be avoided), and helps ensure code stays focused. All modules appear under the ips namespace. Types of Module A number of primary types of module exist within the software: Utility Modules Exist on the ips.utils namespace, and provide assorted functionality that other modules can make use of, including cookie handling and methods for handling responsive design. UI widget modules Exist on the ips.ui namespace, and define interface widgets to add interactivity to pages, and which can be reused using special data attributes. Controllers Controllers are modules that handle specific functionality for one particular page or part of a page. They respond to events from UI widgets and other controllers and update their scope accordingly. Mixins Mixins are used to extend controllers with additional functionality. Other types There are a number of other types of non-modularized file used too: Libraries/interfaces Libraries are 3rd party scripts that provide additional functionality. jQuery and Underscore are two examples. Templates Template files define special Mustache templates, that modules can use when rendering HTML to the browser. Languages Language files define strings which can be translated into other languages.
    1 point
×
×
  • Create New...