Customizing events

Customizing Events

With basic knowledge of HTML, CSS, Jade and JavaScript event organizers can customize the way their event look like.

What can you change?

Currently only non-administrative views are customizable because administrative views are build with JSF instead of Jade templates and because usually event organizers do not wish to change them (for obvious reasons).

Beyond that most of the UI is customizable because templates can affect content markup, styles and add JavaScript to the pages.

What are those Jade templates your are talking about?

Jade is a templating language that can be used to create event markup, styles and scripts.

Jade tutorial can be found from: http://jade-lang.com/tutorial/ and language reference from http://jade-lang.com/reference/

Template model

Templates have access to data provided by the server. If your event needs something that is not available in the default model, feel free to open a feature request about it (see Contributing for details).

Common data

All templates share following data

{
  "eventUrl" : "http://event.url", // url of †he event
  "eventName" : "Test Event", // name of the event
  "currentPageId" : "12345",  // id of current page
  "eventDescription" : "description", // event description
  "siteUrl" : "http://www.forgeandillusion.net", // site url (always http://www.forgeandillusion.net in production)
  "contextPath" : "/", // context path (always / in production)
  "user": { // logged user info (available only when user is logged in)
    "id": 123, // id of user
    "displayName": "Display Name", // Display name of user (First and last names or <email address>)
    "firstName": "First", // User's first name
    "lastName": "Last", // User's last name
    "participant": { // Information about participant or null if user has not joined event
      "id": 234, // User participant id
      "role": "PARTICIPANT", // User role in event (one of INVITED, ORGANIZER, PARTICIPANT, BANNED, PENDING_APPROVAL or WAITING_PAYMENT)
    }  
  },
  "pages" : [{ // List of currently visible pages
    "id" : "12345", // id of page
    "urlName" : "testpage", // page url name
    "url" : "http://event.url/pages/testpage", // page url
    "title" : "Test Page", // page title
    "type" : "PAGE", // type of page (one of INDEX, PAGE or MATERIALS)
  }],
  "breadcrumbs" : [ { // current page breadcrumbs
    "type" : "ENVIRONMENT", // breadcrumb type (either ENVIRONMENT or EVENT depending on whether breadcrumb is inside event or not)
    "url" : "http://www.forgeandillusion.net", // breadcrumb url
    "text" : "Forge & Illusion" // breadcrumb text
  }],
  "adminPages" : [{ // admin pages (only when user with permissions to administrate event is logged in)
    "id" : "PAGEID", // id of page
    "path" : "/pagepage", // path to the page 
    "title" : "Page Title" // title of the page
  }]
}

Index

Index page has following data besides the common data

{
  "hasSignUpFee" : false, // whether page has signup fee or not
  "signUpFee" : null, // event signUpFee or null if the event is free
  "joinMode" : "OPEN", // event join mode (one of OPEN, APPROVE or INVITE_ONLY)
  "ref" : null, // "inv" if user has ended up to the page from invitation email,
  "indexText": "[CONTENT]", // contents for index page (does not exist when INDEX_INCLUDE_ALL_PAGES is set to 1 in event settings)
  "pageContents" : { // contents for all pages (only when INDEX_INCLUDE_ALL_PAGES is set to 1 in event settings)
    "PAGEID" : "[CONTENT]"
  }
}

Materials

{
  "materials" : [ { // list of materials
    "id" : 1234, // id of material
    "icon" : "document", // material's icon  
    "title" : "Example", // material's title
    "viewable" : true, // whether material is viewable on Illusion or should be downloaded
    "path" : "example", // path to the material
    "urlName" : "example", // url name of the material
    "downloadUrl" : "/materials/1234/illusion/testevent/example?download=true", // download url for material
    "publicity" : "PUBLIC", // material's publicity
    "type" : "DOCUMENT" // type of material
  }]
}

Material

{
  "materialTitle" : "Example", // material title
  "materialUrl" : "/materials/1234/illusion/testevent/example", // material url
  "materialEmbedType" : "IFRAME" // material embed type (IFRAME, SVG or IMG)
}

Page

{
  "pageTitle" : "Example", // title of the page
  "pageContent" : "[CONTENTS]" // contents of the page
}

Template naming

By default Illusion views use default templates for constructing views (see default templates above). Organizers can override some or all of those defaults simply by creating template with same name to the event.

Default template names are

• common (commonly used mixins)
• common-header (generic header mixin)
• common-navigation (generic navigation mixin)
• index-contents (contents for index page)
• index-head (styles and scripts for index page)
• material-contents (contents for material pages)
• material-head (styles and scripts for material pages)
• materials-contents (contents for materials view)
• materials-head (styles and scripts for materials view)
• page-contents (contents for custom pages)
• page-head (styles and scripts for custom pages)

Otherwise templates can be named freely.

Default templates

Default templates keep constantly evolving so it would be pointless to include them here but you can easily see them in the git repository:

https://github.com/foyt/fni/tree/master/webapp/src/main/resources/jade/illusion

Changing styles

CSS styles can be modified in the xxx-head -templates. just add new style(type="text/css") row and add the styles under the tag (indented by normal Jade rules) and they should appear on the page as inline styles.

see Styling example

Adding scripts

You can add script into your events. Scripts can be added by adding script(type="text/javascript") tag into xxx-head -templates (e.g. index-head).

Both inline and external scripts can be added. Note that external scripts must be publicly available and the source should be stable and fast so it would not make the event unstable and/or slow (consider using public cdn services). You also should note that events contain some scripts (e.g. jquery) by default.

see Scripting example

Locales

All templates receive a helper function 'locale'. Helper contains couple of different locale related methods:

• locale.text for outputting localized strings
• locale.unformatted for outputting locale strings as unformatted
• locale.locale for outputting current locale
• locale.language for outputting current language

locale.text allows template developers to use locales defined in https://github.com/foyt/fni/tree/master/webapp/src/main/resources/fi/foyt/fni/external bundles by calling

locale.text('key') 

e.g.

p
  = locale.text('illusion.login'))  

Examples

Hello world

First navigate into your event's "Admin / Manage Templates" -view create a page with name index-contents

Then change the template contents to:

p
  |Hello World  

... Save and open event's index page in another tab and you should only see the main menu, text 'Hello World' and the footer.

To revert event's index back to default just delete the index-contents template from Manage Templates -view

Navigation example

Navigation is handled by common-navigation -template. Default template may change over time so you should grab the latest version of the template directly from the GitHub repository (https://raw.githubusercontent.com/foyt/fni/master/webapp/src/main/resources/jade/illusion/common-navigation.jade) and copy that into new template named 'common-navigation'.

After that to just change the navigation mixin, e.g. add ,style="background: yellow" into the div(class="grid_16 tight") and voilà your navigation has hideous yellow background. Enjoy!

mixin navigation()
  div(class="grid_16 tight", style="background: yellow")

Styling example

Styling is handled by adding style element into xxx-head -template (e.g. index-head).

For example if you'd like to change index page's text color to red you could do that by creating new template index-head into your event's templates with following content:

style(type="text/css")
  .illusion-event-index-text {
    color: red;
  }

Scripting example

Scripting is handled by adding script element into xxx-head -template (just like styling).

For example if you'd like that your event would greet visitors by saying 'hello' in a alert box, you can achieve this by adding following script into your head-index -template:

script(type="text/javascript")
  $(document).ready(function() {
    alert('hello');
  });

Will there be support for any other templates?

Sure, why not, just add a feature request for your favorite template language and i just might add it some day or better yet, add the support your by your self and create a pull request so i can be pulled to the application it self. (see Contributing for details)