Jump to content

Guides

Core Concepts

  1. Introduction to Pages

    Introduction Pages is our application that is designed to allow you to build custom areas of your community. These could range from custom reusable blocks to use in your sidebar, all the way up to complex applications built using our databases feature. Whereas our other applications provide a regimented (although customizable) front-end that's ready to use right after installation, Pages is a little different. Think of it more as a toolbox - it provides features that you use to build your own front-ends. Therefore, you need to put in some work once you start using it before you have anything to make live. This guide will cover the core concepts and features in Pages to help you get started.   Who is Pages for? Pages has features for everyone! It has easy-to-use features like drag'n'drop page building, but under the hood, the entire IPS4 framework is available for power users to take advantage of. The wider your knowledge of HTML & PHP, the more advanced solutions you'll be able to develop, although no experience of HTML & PHP is required to get started with Pages!
  2. 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's 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 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: 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 pages to the navigation menu 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.
  3. Blocks

    What's a block? In Pages, a block is simply a section of reusable content. These can come from the applications in your community, be custom ones based on other built-in blocks, or be entirely custom. If you're comfortable with code, custom blocks allow you to achieve some complex results since the full range of IPS4 template logic is available to them. If you aren't comfortable with code, you can still create blocks based on built-in blocks using a simple wizard.  Blocks can be inserted into your own custom pages, but also into any page generated by IPS4 (if the sidebar appears on the page, this can be done with drag and drop from the sidebar manager, or you can manually show the block by including its tag in IPS4's templates).   What can blocks be used for? There's a huge range of uses for blocks. Custom blocks based on built-in blocks are a great way of highlighting worthwhile content in your community. For example, you could create a block showing a feed of the most popular topics in a particular forum you specify, and use the block to cross-promote that forum in related areas of your community. Custom blocks are larger in scope by their nature. They can range from simple HTML that you want to use in multiple places to reduce repetition, all the way to custom PHP that can be used to dynamically generate content. Common uses for custom blocks include providing a convenient way to insert Javascript in your page, building page headers with dynamic elements based on the page in which they're used, and including site notices in your community pages in an easy-to-edit way.   Managing blocks Blocks are primarily managed in the AdminCP by going to Pages -> Blocks. Blocks can be organized into categories, although this has no impact on users - it's simply for ease of management via the AdminCP.   Creating blocks Blocks are created from the same screen. When you click the Create New Block, you're prompted to choose between Plugin and Custom. Plugin
    A plugin block is one based on an existing data source from the IPS Community Suite, such as members, forum topics, upcoming calendar events and so forth. Although the data source provides the data, the block configuration you set up allows you to define filters to customize what subset of the data is shown. For example, you could create a feed of topics, from a particular forum, with more than 10 replies. Plugin blocks use a default template, but you can choose to override or customize this template with another. Custom
    A custom block can be created using a rich text editor, HTML (including IPS4's template logic), or pure PHP.    Using blocks On pages built using the Page Builder, blocks can be dragged and dropped into position by using the sidebar manager (the available areas on the page to receive the block will depend on the layout you chose when the page was created). On pages built using custom HTML (or if you want to insert the block in an IPS4 template), a special tag is used to insert the block: {block="block_id"}   Block caching Custom blocks can optionally be cached, meaning the resources required to render the block are reduced. If your block is dynamic in any way (such as rendering differently based on the user viewing it, or the page it is being shown on), you should ensure that caching is not used. For plugin-based blocks, IPS4 handles the caching behind the scenes for you.
  4. Databases part I

    What's 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 of databases in Pages 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. Forums 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.  
  5. 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: 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 a database 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.
  6. Templates, CSS & JS

    Templates, CSS and JS files are the means by which coders can take the default output of the various parts of Pages, and customize them to build unique parts of their site. Note: only those familiar with HTML, CSS and some PHP should consider modifying their templates. Since they involve editing code, it's easy to break the output of your site unintentionally!   Type of template in Pages Templates are the key to customizing areas of your Pages website so that they're unique to your site and to your particular use of them. There's three primary types of template you can customize: Database templates
    Databases templates let you change the output of just about every part of your databases. There's four main types of template: Category Index
    The templates that render the category index of a database, and subcategories when browsing the record listing. Listing
    Templates that render the record listing Display
    Templates that render record view itself, including comments & reviews Form
    Templates for the add/edit form, allowing you to customize this form per-database Page templates
    By default, a page will use the suite wrapper, which includes the header, navigation, user bar etc. leaving your page content to control the actual content area. However, you can instead choose to use a custom page wrapper, allowing you to control the entire output of the page. Wrappers are created as page templates, and selected when you create your page. Block templates
    When you create a plugin block showing a feed of data, IPS4 uses a default template. You can however customize this template or create a new one, allowing each block to have a unique appearance.   What blocks can contain Blocks can contain the full range of IPS4 template syntax, which affords great flexibility. The data available to each template will depend on its type (for example, a database listing template will receive data from the database category, but a block template will receive data that matches the block's filters), but all templates can access the full underlying IPS4 PHP framework.   Creating & editing templates Database and page templates are managed in the Pages template editor, accessed by navigating to Pages -> Templates in the AdminCP and clicking the New button. Default block templates are also managed in the template editor as above, but can also be customized per-block within the block configuration themselves, by going to Pages -> Blocks in the AdminCP and then editing the block in question.    CSS & JS files To fully customize sections created with Pages, it's often desirable to add custom CSS and Javascript. Pages offers a built-in way to write and use these resources and then assign them to a page for use. CSS and JS resources within Pages are managed by navigating to Pages -> Templates in the AdminCP, and then clicking the CSS or JS tabs in the editor. New resources can be added by clicking the New button. To assign them to a page, simply select them on the Includes tab when creating or editing a page in the AdminCP.
×