Introduction

Invitecast is an online invite platform which can support any kind of invite imaginable, and arguably stretches the definition of what an "online invite" is. The Invitecast approach to online invites can be compared to the insanely successful way that WordPress created a community around blogging sites.

How do we do this?

First, at it's core, Invitecast is a delivery and management platform for HTML-based invites. Invites can be any HTML document or HTML fragment (as is the case in email invites). That means that any sort of web page--including a full HTML5 application--can be an Invitecast invite. The Invitecast product delivers only the HTML document in the template to the browser with a few string substitutions (to get necessary server data), and does not include ads, or iframes, or anything from the invite thw developer and end-user did not place there.

Second, Invitecast takes the same "three tier" approach to development as Wordpress:

• Invitecast provides the system software and online platform (tier one).
• Invite developers provide templates with advanced programming and specific customization hooks; (tier two).
• End-users customize those templates to make them into their own online invites using the Invitecast Invite Builder (tier three).

Of course, like Wordpress development, you can simply use the Invitecast platform for yourself or your company to create unique advanced online invites with any degree of customization available to the Builder or even none at all. (In other words, if you are just creating a one-off for yourself, you don't need to bother with creating a lot of customization hooks for the Builder since you will be doing your work directly in HTML code).

Another valid use of the platform is to create a template for yourself, your friends, your clients, or your company with only the customization hooks (if any) that you need.

Getting Started

To get started as a Invitecast developer (or just to create an interesting invite for yourself), navigate to the Invitecast site and create a new Invite by selecting an existing template and going into the Invite Builder, which is the part of the product that allows you to customize the Invite Template you have selected.

Within this tool you will find the Custom HTML link, which will allow you to edit or replace the HTML of the Invite.

The code you see there will be a good example of an Invitecast invite. Steal it! Copy the code you see there into your favorite HTML editor or IDE, and modify it to your heart's content. When you are finished with your changes, copy and paste the HTML back into the box where you started and Save your changes. Then you are ready to use the Invitecast platform to manage and deliver your invite.

From here you can also assign your event to a Template (a Template is just an Invite which has been marked as being a Template--be careful, it works like a real invite!).

Convenient Offline Development

The Invitecast platform was specifically designed to allow seamless offline development of custom invites and templates. The idea is to minimize your need to use the Invitecast online platform in order to test the functionality of your invite code.

This seamlessness is accomplished by:

• Making server-provided string substitutions that are realistic and/or contain useful example data.
• Making use of AJAX API calls to make use of Invitecast platform features (and again, making them work in an offline mode with useful example data so you can see it work).
• Using MetaThemeJS as a customization substitution system, which allows substitutions while maintaining a fully working HTML document even when substitutions are not "executed".

Hence the workflow of Invite development will be mostly accomplished using your own tools in your own local environment and you don't need your own special server to do development and you will only need the Invitecast server for final testing. You can use a local HTML server or even just your local file system to host your code, and just test it with a browser.

Covering Your Assets

Besides HTML, some templates may need to provide their own image or video assets (i.e. JPEGs and GIFs and PNGs and MP4s etc.). You can use the Invitecast platform to provide hosting of your template's assets, which gives you the high performance of a CDN, and a convenient place to manage these assets.

To access this functionality, find the My Media section in the Invitecast product when you are logged in. From there you can upload media and view it (which will give you the permanent URL which you may then use for your tempalate).

Invite Architecture

Invite HTML

An Invitecast invite is an HTML document, containing the Invite HTML.

Within this HTML document are MetaTheme variables, which are used by the Invitecast Invite Builder (i.e. the Invitecast end-user product) to present the desired customization options to the end-user. Although customization variables are desirable, especially for widely-used Invite templates, the only the following variables are required to be implemented: "Event Name", "Event Description", "Event Time", "Event Location Name", "Event Location Address".

Invitecast JavaScript Library

Every invite document should make use of the Invitecast JavaScript library, which provides access to the Invitecast Server API as well as other useful things for the creation of Invites. This library is located at https://invitecast.com/ici/v1/ici.js . This library will be revved only in backward compatible ways, and only when compatibility is broken will it be moved to a v2, v3, and so on. (∂ƒNOTE: cut and paste the URL of an Invitecast invite library or component module in order to see the uncompressed version).

Invitecast Invite Components

Invitecast provides a set of commonly-used "components" or "widgets" for Invites, such as a Response (i.e. a UI panel to allow an end-user to respond to the invite), Comments, Invitees, Pictures, and Gift Registry. These can be customized by the template HTML to fit in with the rest of the invite.

Invitecast Server API

The InvitecastJS Library provides a client layer for the Invitecast Server API, which is a Rest API into the Invitecast service. The Invitecast APIs can be used to access all functionality within the Invitecast service (the Invitecast product is written on top of the Invitecast Server API for instance).

Web Browser Platform

Invitecast Invites should be made to work with the present-day "99%" of web browsers, and should be useable in reasonable mobile and well as desktop clients. Note that this platform can include any number of third-party APIs and basically any sort of code that any normal web page may include.

Web and Email Invite Document Files

An Invitecast invitation template must cover both aspects of an invite's communications, including the web page invitation and the invite email.

• Web Invite -- An HTML page, displayed as a typical full browser page (viz. 1000 x 800 pixels but designs should be viable for the "typical" range of web page sizes).

  A web invite template must include:

  • The title and event time and date (see the section below titled, "Require MetaTheme Vars" for details).
  • A way to respond to the Invite, and for a user to update their response as necessary.

  It may also include:

  • The list of invitees and their responses.
  • The "social" invite functions e.g. comments and pictures from invitees.

  More advanced invites can also include:

  • A gift registry for the party or wedding.
  • Music, including the music that might be played at your party.
  • Video, including YouTube or other videos available to you or on the Internet.
  • Animation and games.
  • Multiple "pages", or sections--an invite can be an entire web site if desired!
• Email Invite -- An HTML page formatted for email, containing a link to the web invite. This email is sent for both initial, reminder and confirmation communications.

MetathemeJS

Metatheme is an open source project that enables your HTML, JavaScript and CSS code to be customized by a user. Invitecast uses Metatheme to interface between the HTML invite template and the Invitecast Builder UI.

Using Metatheme With Invitecast Invites

All HTML invites entered into the Invitecast platform must be valid HTML documents, which all Metatheme templates are.

The key advantage of MetaTheme is that it allows you to develop your templates using only your favorite HTML editor and a web browser. The Invitecast server is not required during your development. Only in the final intregration testing phase of development do you need to involve the Invitecast platform itself. This is by design, as it allows developers much greater flexibility and speed during development.

Common Var Parameters

An invite may have many Metatheme vars. Metatheme vars must include, as per the Metatheme standard, a parameter called "name". In addition, Invitecast allows the following optional parameters on all Metatheme vars in invites:

Parameter Name	Valid Values	Description
mustchange	true | false	Specified a var that must be changed before the user can save the invite for the first time. Usually used on required metadata vars.
order	Any number	Specifies the order the var will be displayed in the Builder to the user. Vars without order numbers will be displayed in unspecified order after all vars with numbers of any kind.
altName	Any word string	Specifies the "internal" name for the var, for use by the Builder to identify required metadata vars (see below).
objectid	Any ID string of an HTML object within the invite.	Specifies the HTML object to "highlight" (i.e. turning on the .objectHighlight style) when the var is selected in the Builder UI, and also will make the given HTML object clickable and will bring up the Builder UI to edit the given var when clicked.
mpage	A string containing the name of an MPage which should be selected when the given variable is being edited. This allows vars to affect content on different pages and the page to be automatically displayed to the user.	Specifies the HTML object to "highlight" (i.e. turning on the .objectHighlight style) when the var is selected in the Builder UI, and also will make the given HTML object clickable and will bring up the Builder UI to edit the given var when clicked.

Required Var Names

Since the invite itself is used as the interface to gather basic metadata for the event or party, every invite template must include the var names below. You can make the type "internal" if you want to hard-code these, but they must be included. You can use the altName functionality (described above) in order to show the user a more friendly name in the Builder.

Note: the vars below are not required for Email templates. However, if the name/altName is specified in the template, the values from the Event metadata will be subtituted into the template in the Builder. Hence you typically want to include some of these (viz. the eventName and timeDuration at a minimum) as "Internal" vars so these will be included in the email template.

Parameter Name (name or altName)	Type	Description
eventName	String	The name or title of the event.
timeDuration	TimeDuration	The time and duration of the event.

Invitecast Invite Builder Controls

The Invitecast Product includes a way to customize invite templates: the Builder. The Builder scans your invite code for Metatheme variables and based on their types, presents the user with an interface to manipulate the value of that variable. Here are the types along with the Builder controls and their behavior.

Var Type	Options	Builder Control Behavior	Output
String	maxlen -- the maximum length of the string allowed.	Allows the user to specify a string. Depending on the length, either a single line entry or a multi-line entry will be presented.	A simple text string.
TextStyle	None	Allows the user to select font family, font size, font style (bold, italic) and letter spacing. Note: the behavior of this control will change depending on whether the invite being modified is an email or the main web invite (a subset of email-safe fonts will be presented in the case of email).	A CSS string of the corresponding styles representing the user choices made.
Background	None	Allows the user to specify a background style for an HTML div tag.	A CSS string with the corresponding CSS styles based on the background the user has selected. May include color, transparency, images, and image sizing, location, etc.
TimeDuration	None	Allows the user to specify a calendar date, clock time, and a duration. Typically used with the timeDuration required parameter.	A TimeDuration string: see the detailed documentation below on TimeDuration.
MapAddress	None	Allows the user to enter an street address, or geological location.	An HTML string providing an anchor linked (<a href=...>) string with the address specified by the user. Thus the invite viewer will be able to click on the link and be presented with a map (Google Maps, at this time) to the location address the user has entered.
AudioFile	None	Allow the user to choose an audio file from their desktop or the Internet.	The URL to the audio file. Note: the string returned will be the URL only and thus the MetaThemeJS var will make use of the MetaTheme "subTagName" functionality to substitute an HTML parameter value. For example: <!--[--><audio src="https://uimg.invitecast.com/RDbech.wav" autoplay></audio><!-- {"name": "Background Music", "type": "AudioFile", "subTagName":"src" }-->
MetaPong	None	Allow the user to specify a MetaPong animation.	A string with the MetaPong parameter list, i.e. the JavaScript object that is placed in the "var mp = new MetaPong( ... )" call. See below for details on MetaPong.
TagList	title -- optional title for the dialog box	Allow the user to specify a list of name/value pairs, wherein the name is the "friendly name" of the tag, and the value is the tag. A "tag" here is a lowercase single-word string of at least 1 character. The "friendly name" is any string of at least 1 character.	A JSON string representing an object containing the name/value pairs, e.g. {"Friendly Name":"tagname1",...}.
Internal	None	Ignored by Builder	N/A

The TimeDuration Type and Builder Control

The TimeDuration var is specifically meant to specify the time, date and duration of the event or party. The TimeDuration control does two things at once:

• Specifies the time and duration of the Event or Party.
• Specifies the formatting of the time/date/duration on the invite.

The value of the a TimeDuration type var (which is usually named, "timeDuration") usually looks something like this:

12:30pm to 3:30pm<br>Friday, May 8th, 2020
<!--* {
"time": "2016-05-08 19:30:00",
"format": "h:mma [to] ~~h:mma~~[<br>]dddd, MMMM Do, YYYY",
"timezone": "America/Los_Angeles",
"duration":"180"}
-->
				

There are two things going on here. First, the HTML outside of the comment block is displayed to the user as normal HTML would be. Second, the JSON string within the HTML comment block is defining the TimeDuration object, which contains the following fields:

Name	Description
time	The time string for the event.
timezone	The timezone for the event.
duration	The duration for the event in minutes.
format	The format for the time and duration on the page. The format string is a MomentJS date format string with the following exception: the string found between a set of "~~" markers will be interpreted as a separate complete format string and the end time/date of the event will be substituted there. This is important when you want to display the beginning and the end time on the invite.

Hence when the Builder interface for TimeDuration types is invoked, the contents of TimeDuration typed var are given as input, and the new contents are returned as the output.

The MetaPong Type and Builder Control

MetaPong is an animation library developed by Invitecast and released into open source. With MetaPong you can create animations that fly objects around the page.

The Invitecast Invite Builder product provides an easy to use and fun user interface for end-users to create a custom animation.

If you want to specify a MetaPong var type in your invite template, make sure you include the MetaPong library include like so, and then a JavaScript var for it like so:

<script src="//metapong.com/dl/0.9.4/metapong.js"></script>

var mpParams  = /*[*/ null /*{"name": "Animation", "type": "MetaPong"}*/;

if(mpParams != null){
	var mp = new MetaPong(mpParams);
	mp.start();
}
					

(NOTE: This example shows the MetaPong value as "null" which will be no animation by default but allow the user to create an animation from scratch. You could also put an object in the value area to have an animation running by default. Use the results from the Builder or MetaPong.com to build a MetaPong Object to place in the value area.).

Making Invites for Email

Because of both security concerns--and the fact that emails are displayed inside of another product's web page, email HTML functionality is very limited as compared to its full-page browser counterpart.

Invitecast does not filter HTML Email templates in any way, but all email providers definitely do. In particular, you should only use inline CSS, and its best to use "basic" HTML such as tables. Obviously any sort of Javascript (including a simple button onClick) will not work. Here is a great article on constructing HTML emails.

The Anatomy of an Invite

Web invites are complete, valid HTML documents. Email invites are HTML fragments.

Background

The Invitecast platform, with it's use of MetaTheme, has a central goal of allowing invite code to be developed and tested offline, without use of the Invitecast platform.

Besides MetaTheme, other features described here support that goal--that you should be able to see a working version of your invite offline, without use of the Invitecast platform.

As is typical of a system like this, your code is run through a string substitution processor before it is presented to the user so it can be customized to their context (i.e. their name is entered, their token allowing them to respond on their own behalf, etc.).

This presents a problem, however: if an invite must be customized for an invitee for it to fully work, how do you make it work offline, where there is no user and no invitee?

The solution is to use a combination of working substitutions and APIs which automatically render testing data.

Working Substitutions

Most server-side templates like Invitecast invites include "markers" which tell the server to insert a certain string in a certain location in the document. In other words, something like this:

Greetings, {{UserFullName}},
You have won a new car.
Click {{OfferLink}} to see your prize.
				

The problem with this approach is that, unless you use the server platform during development, your development code will not look right, and ultimately will be very hard to test.

Because of this, Invitecast uses working substitutions along with the MetaTheme approach. Working substitutions implement a usable bit of sample code as their substitution marker, meaning that without the server subtitution, your document looks like an example of the final document.

So below you will notice in the available substitution strings that they don't look like normal substitution strings. This is by design.

Substitution String List

Here is the list of valid system substitution strings:

Substitution String	What Will Be Substituted
The Third Annual Jones Chili Cook-Off	The Event Title for the invitation.
http://invitecast.com/inv?1	The link to the full web invite Event/User combination. Usually used for HTML email. Note that this link works for testing.
[{"name":"John Q. Partygoer", "email":"johnqpg555@gmail.com", "type":"primary", "status":"status_yes"}, {"name":"Jane Q. Partygoer", "email":"janeqpg777@gmail.com", "type":"coinvitee", "status":"status_none"}, {"name":"John Junior", "type":"guest", "status":"status_maybe"}]	A JSON string with a list of objects for the invitees associated with current viewing user. This usually (but not always, in the case of non-invited invitees) contains the status of the primary invitee (the viewing user), the co-invitee if present, and one or more guest invitees if present.

Invitecast API Calls

Besides basic HTML/CSS layout, Invitecast web invites can rely on the Invitecast API. This API is readily called using the Invitecast Invite JS library (see below for more details).

In the spirit of offline development, several key Invitecast API calls can be called without a valid user token and in that case will return example data. This again is meant to support offline invite development. If the Invitecast JavaScript library is used to call your Invitecast APIs, then this should be seamless to you (i.e. when a token is present, it is used, otherwise no token is sent and you get example data back, and/or calls safely perform no action).

The Invitecast Standard Invite

Invitecast provides many invites for users by default, which may be based on several different invite templates. One invite, which we'll call the "standard invite", is an example of an invite that excercises all of the major components of the Invitecast Invite platform. It can be found at: http://invitecast.com/ici/v1/example-invite.html * , provides an example of an invite that excercises all of the features of the Invitecast system, and serves as a complete example which can be customized and changed by developers as necessary.

(*NOTE: the above URL is intentionally not linked because, in order to get the non-minified version, the URL must be accessed directly without a referrer--copy and paste the URL into your browser to get the file).

Standard Invite Features

The standard invite includes the following top-level features and design:

• Multi-panel Single Web Page. The invite is made up of multiple "virtual pages" which are used like separate pages from the user's persective, but is served as a single HTML file from the server (i.e a "single-page application").
• Invitecast Standard Components. The Invite includes all of the provided Standard Components (see below) provided by Invitecast, and makes use of them as an example.
• jQuery. Invitecast standard invites use jQuery, which is the most popular and widely used JavaScript library on the Internet. jQuery allows invites to be easily cross-browser and provides a basic set of tools that most front-end JavaScript applications need.
• The Invitecast Invite JS Library. The Invitecast Invite JavaScript library is a standard include for all invites and enables all of the features discussed here. It can be found at (present stable version): https://invitecast.com/ici/1.0.4/ici.js. Standard components are found in this directory as well.
• Offline Development. Staying true to the Invitecast goal to allow offline development, the example can be modified and tested without use of the Invitecast online service (at least directly).

Required MetaTheme Vars

Although an invite may include as many MetaTheme variables as you like, the following are required for every invite to function in the Invitecast system:

1. TemplateName This is an internal MetaTheme variable denoting the name and version of the current template code. This var is typically used for code version management, and usually includes a version number of some kind.
2. DesignName This is an internal MetaTheme variable denoting what this variant (or design) of the template will be called. This will be displayed to the user as the name of the design in the Builder and in the design chooser.
3. altname: "eventName" This variable, which can be given whatever Name you wish to be displayed to the end-user, is of type String and must be modified by the end-user before an invite is completed.
4. altname: "timeDuration" This variable, which can be given whatever Name you wish to be displayed to the end-user, is of type TimeDuration and must be modified by the end-user before an invite is completed.

Multi-Page Framework

// ^^^ Up here there would be div tags with the ID "title",
// "details", "response", and "registry"
//
ICI.MPage.register("title");    // first one is default home
ICI.MPage.register("details");
ICI.MPage.register("response");
ICI.MPage.register("comments", {
	showFunc: function(callback){
		// code to load the Comments widget here
		// so we don't load it until the user navigates
		// to it.
		callback(); // do this when we're done.
	}
});

// now that our pages are registered, MPage
// will vector to the registered pages via the URL hash, if
// present. If not, the default (first registered) MPage is shown.
// This will also setup the listener for #hash changes,
// and turn the MPage for your for hyperlinks, etc."

Standard Components

Invitecast provides standard components which, while not mandatory, may be used to create many of the standard ingredients of an invite. Developers may wish to either customize these components, or use them as example code from which they can develop their own UI to perform the same function.

Examples

// Load the Photos component into a DIV called, "myPhotosDiv"
var photosComp = new ICI.Component("Photos", "myPhotosDiv");
photosComp.load();


// Load the Response component into an HTML DIV called,
// "myResponseDiv" and include some extra parameters which are (1)
// filled in by the Server on the fly and (2) a MetaTheme
// var)
var responseComp = new ICI.Component("Response", "myResponseDiv", {
	userList: [{name:'John Q. Partygoer', email:'johnqpg555@gmail.com', type:'primary', status:'yes', tags:'adult male beef'},{name:'Jane Q. Partygoer', email:'janeqpg777@gmail.com', type:'coinvitee', status:'none', tags:'adult female'},{name:'John Junior', type:'guest', status:'mayb', tags:'child male vegetarian'}];
	selectTags:
		/*[*/
		{
			"Select Meal Preference":"",
			"Chicken Poulet":"chicken",
			"Beef Under Glasse":"beef",
			"Vegetarian Melody":"vegetarian"
		}
		/*{"name": "Meal Preferences", "type": "TagList"} */
});

// Now that we've defined it, we can load it into the DIV, which will
// cause the Component to be loaded from the server and initialized...
responseComp.load();
				

Customization

As shown above, Components may have customizations and parameters. In some cases there are end-users customizations that should be exposed as MetaTheme vars (viz. selectTags in the example above). In other cases the component may need a Server substitution value (viz. userList in the example above).

Component List

Here is the current list of components:

• Response -- Provides a UI to allow the user to respond to the invitation.
• Invitees -- Provides a UI to display who has been invited and their status.
• Comments -- Provides a UI to allow the user to view and add comments (including pictures).
• Photos -- Provides a UI for a photo album based on photos gleaned from the comment stream.
• Registry -- Provides a UI for the end-user portion of the Gift Registry.

Using MPage and ICI Components Together

MPage and Components were made for each other! You can create an MPage for given Component (and let the Component deal with all of the parameters, load/unload, etc.) by using the setMPage() method on the Component object. This will register an MPage based on the object ID (div ID) you gave it and will load that Component into that div when it's called upon for the first time.

For example:

var responseComp = new ICI.Component("Response", "response", {
	userList: [{name:'John Q. Partygoer', email:'johnqpg555@gmail.com', type:'primary', status:'yes', tags:'adult male beef'},{name:'Jane Q. Partygoer', email:'janeqpg777@gmail.com', type:'coinvitee', status:'none', tags:'adult female'},{name:'John Junior', type:'guest', status:'mayb', tags:'child male vegetarian'}];
	selectTags:
		/*[*/
		{
			"Select Meal Preference":"",
			"Chicken Poulet":"chicken",
			"Beef Under Glasse":"beef",
			"Vegetarian Melody":"vegetarian"
		}
		/*{"name": "Meal Preferences", "type": "TagList"} */
},
true	// when true, will automatically make this component's
	// DIV an MPage referenced by #response
);
				

Nav-o-Matic Tool

Included in the ICI MPage module is a handy function to glue an HTML navigation objects to MPage functionality. This API call will turn a specially attributed HMTL tags into a navigation menu that selects the specific MPage the user wants. This API will turn the page when the user clicks and highlight the appropriate items depending on the URL hash. It will also add the "nav_current" CSS class on the current item (i.e. the item that matches the MPage currently being shown).

For example:

<style>
	nav {
		/* use this to specify style for the navigation area */
	}

	nav>div {
		/* use this to specify style for individual items */

	}

	.nav_current {
		/* this will be applied to the currently selected page item */
	}
</style>

<nav>
	<div data-nav="somePage">Some Page</div>
	<div data-nav="otherPage">Some Other Page</div>
	<div data-nav="somethingElse">Something Else</div>
</nav>

<script>

	ICI.MPage.enableNav("nav");	// enable the nav-o-matic system for MPage within the nav tag
								// if this was a DIV you'd probably say, "#myNavDiv" for example

</script>

				

NOTE: The above example uses DIV tags for items but any sort of tag will work as long as items include the "data-nav" tag).

Styling Your Components (CSS)

Invitecast standard Invite Components try, the best they can, to use as few styles as possible, allowing the main Invite to dictate their look and feel. Invites should set the styles of key HTML tags such as input, select, textarea, button, etc.

Invitecast standard Invite Components also may make use of a relatively new--but now widely supported--CSS feature called CSS Custom Properties or (aka "CSS Vars").

CSS Vars allow Components to happily use their own styles as they see fit (their "fallback value" in CSS var parlance), but allow Invite developers to override (and also optionally expose as an end-user MetaTheme var) various styles if they wish to do so.

Note: You can view the available CSS vars for each component by viewing the source of each Component. (Remember to cut/paste the Component URL into your browser to see the non-minified version).

Steal These Components

Remember, it is not mandatory you use Invitecast Standard Invite Components for your invite template, and you are also welcome to use the source code of the standard ones to make your own version.

Template Introduction Screen / Help

Since every template can be used differently by end-users, it can be important to provide some information to the user of the template so they can better fill out necessary fields and make use of advanced features.

The Invitecast platform provides a mechanism for the template to provide HTML content that will be presented to any user of the template for a new invite.

The mechanism is as follows: the template HTML will contain a DIV tag with the ID, "templateIntro". If present, the Builder will place the contents of that DIV tag inside a help screen formatted similar to other help screens the Builder presents to the user.

The contents of this DIV tag should be fairly non-styled HTML so as to let the Builder decide it's styles which in turn will allow the template's Introduction/Help material to fit in better.

Here is a "hello world" example of this functionality:

<div id="templateIntro" style="display: none">
	<h1>Welcome to My Template</h1>
	<p>
		This is my Template. There are many others like it but this one is mine.
	</p>
</div>