Documentation

This section contains documentation and guides for how to start using and customise Marbl within your environment, CMS or project.

Marbl Guides

Customising the look of Marbl

Marbl in PD9Soft MegaBBS 2.2

 

Marbl JavaScript API

Quick Start

The following examples can be used to get started with Marbl.

 

Install Marbl

Download the current version of Marbl.

Extract the zip file to a location on your web server e.g. /marbl.
Note: It is important that you preserve the file and folder structure found in the zip file.

 

Include Marbl

Enter the following into the <head> tag of your web page:

<script type="text/javascript" src="/marbl/js/Marbl.js?ver=0.9.15"></script>

It is suggested that you use a query string parameter such as ?ver=x.x.x to improve end-user experience when performing upgrades. The modifiable value of the ver parameter can be used to ensure that the client cache can be bypassed easily if there is a code update.

To achieve the same protection, you can alternatively store your Marbl source code in a version number folder. e.g.

<script type="text/javascript" src="/marbl/0.9.15/js/Marbl.js"></script>

 

Amazon

<script type="text/javascript">
var marblAmazon = new MarblLink('amazon');
    // Enable regions by inserting your Associate IDs
    marblAmazon.addAssociateId('CA', 'hpcfactor0e-20');
    marblAmazon.addAssociateId('UK', 'hpcfactor-21');
    marblAmazon.addAssociateId('US', 'hpcfactor-20');
    marblAmazon.DisplayFlags = true;
    marblAmazon.OpenInNewWindow = true;
    marblAmazon.createLink("ALL", "", "Intel NUC", "", "", 48, marblAmazon.IMAGE);
</script>

The code snippet above will produce:

 

eBay

<script type="text/javascript">
var marblEbay = new MarblLink('ebay');
    marblEbay.PartnerId = '1234567890';
    marblEbay.CampaignId = '9876543210';
    // Insert valid regions [you can also use "marblEbay.addRegions('GB,BE,US');" to perform the task in-line]
    marblEbay.addRegion('GB');
    marblEbay.addRegion('BE');
    marblEbay.addRegion('US');
    marblEbay.DisplayFlags = true;
    marblEbay.OpenInNewWindow = true;
    marblEbay.createLink("ALL", "", "Intel NUC", "", "", 48, marblEbay.IMAGE);
</script>

The code snippet above will produce:

 

Creating Links

You can create links via the MarblLink generator class or directly using the constructor for each link type

MarblLink Generator

<script type="text/javascript">
var marblAmazon = new MarblLink('<link type>', '<path>');
</script>
link type {required} amazon|ebay
path {optional} Root relative or absolute URL to the Marbl repository path. If not specified, the generator will derive the path to the Marbl.js include as the repository path.

e.g. “/api/import/Marbl/js/Marbl.js” will derive “/api/import/Marbl/” as the repository path.

MarblAmazonLink

<script type="text/javascript">
var marblAmazon = new MarblAmazonLink('/api/import/marbl/');
    marblAmazon.addAssociateId('CA', 'hpcfactor0e-20');
    marblAmazon.addAssociateId('UK', 'hpcfactor-21');
    marblAmazon.addAssociateId('US', 'hpcfactor-20');
    marblAmazon.DisplayFlags = true;
    marblAmazon.OpenInNewWindow = true;
    marblAmazon.createLink("ALL", "Buy Intel NUC on Amazon", "Intel NUC", "", "", 48, marblAmazon.IMAGE);
</script>
Constructor

new MarblAmazonLink('<path>')

path Root relative or absolute URL to the Marbl repository path If you do not want to use one of the provided square Amazon logos, you can specify an image to use here. The value is the absolute/relative path to the GIF/JPG/PNG that you wish to use. Set to null to use the defaults.

 

Adding Affiliate Codes

addAssociateId('<Country Code>', '<your Affiliate ID>')

Valid country codes are:

  • AU
  • BR
  • CA
  • CN
  • DE
  • ES
  • FR
  • IN
  • IT
  • JP
  • MX
  • UK [Note: It is UK for Amazon, not GB]
  • US
General Configuration Options

The following options are available as properties.

DisplayFlags [true]/false Displays national flag icons on the dropdown.
OpenInNewWindow [true]/false When a link is clicked, if true the link will open in a new tab/window. If false, the user will be redirected from the current page directly to Amazon, closing your page.
LinksNoFollow [true]/false {recommended} Adds the nofollow attribute to all hyperlinks generated on the page. Your site may be penalised by search engines if you intentionally redirect its crawler to known sponsor and affiliate material. Search engines deem such a practices as representing intentional index spamming.
Rendering Links

To perform the actual render, use the createLink() function.

Once a MarblAmazonLink has been created, you can call createLink() as many times as is required, using different parameters. It is not necessary to instantiate a new instance for each and every link on the page.

For example:

<script type="text/javascript">
var marblAmazon = new MarblLink('amazon');
    marblAmazon.addAssociateId('UK', 'hpcfactor-21');
    marblAmazon.createLink("ALL", "", "Intel NUC", "", "", 16, marblAmazon.IMAGE);
</script>
<!-- other HTML -->
<script type="text/javascript">marblAmazon.createLink("ALL", "Buy Intel NUC on Amazon", "Intel NUC", "", "", 16, marblAmazon.TEXT);</script>
<!-- other HTML -->
[0] Regions [ALL]|<CSV List>

string

{Required} A comma separated list of country codes that you would like to display for this link. If set to ‘ALL’, Marbl will use any valid Associate ID provided.

You can use the CSV list to force Marbl to display a link to an Amazon store, even if you have not provided it with an Associate ID.

The order of country codes in the CSV is important and will reflect the order shown to the user. You can therefore use the order to prioritise the dispay.

createCustomBuyLinks(“ALL”…

createCustomBuyLinks(“UK,US”…

createCustomBuyLinks(“MX,IT,AU,CN,US”…

[1] Label <freetext>

string

{Optional} If set, will convert the link from an image link into a text label. This is useful for in-line/mid flow where you want the name of the product to trigger the Marbl link as well as or instead of image to appear where positioned.

If set, the value will be added to the image ALT text for accessibility

See the Label Only option below for further control.

createCustomBuyLinks(“ALL”, “Kindle Fire 9 HD”…

createCustomBuyLinks(“ALL”, “”…

[2] Freetext <freetext>

string

{Optional} If set, the link will generate a referral link to Amazon product search. This is often useful for internationalised links where different regions may not share the same ASIN or ISBN, but are more likely to share the same branding or base model number.

If not set, Marbl will look for an ASIN or ISBN value.

createCustomBuyLinks(“ALL”, “”, “Microsoft Surface Pro”…

createCustomBuyLinks(“ALL”, “”, “”…

[3] ASIN <freetext>

string

{Optional} If set, Marbl will create a referral link using the ASIN. This allows you to directly link into the product page.

If not set, Marbl will look for an ISBN.

createCustomBuyLinks(“ALL”, “”, “”, “B076KRJG3C”…

createCustomBuyLinks(“ALL”, “”, “”, “”…

[4] ISBN <freetext>

string

{Optional} If set, Marbl will create a referral link using the ISBN. This allows you to directly link into the product page.

If not set, and if search or ASIN have not been set, no link will be displayed.

createCustomBuyLinks(“ALL”, “”, “”, “”, “0857501003”…

createCustomBuyLinks(“ALL”, “”, “”, “”, “”…

[5] Size [16]|24|32|48|null

int

{Optional} If using one of the built-in icons, the size value will select the icon to be used.

createCustomBuyLinks(“ALL”, “”, “Microsoft Surface Pro”, “”, “”, 16…

[6] DisplayMode [1]|2|3
{enum} [.IMAGE]|.TEXT|.BOTHint
{Optional} Defines whether this is an image only, text only or text + image link.

createCustomBuyLinks(“ALL”, “”, “Microsoft Surface Pro”, “”, “”, 32, marblAmazon.IMAGE);

createCustomBuyLinks(“ALL”, “”, “Microsoft Surface Pro”, “”, “”, null, marblAmazon.TEXT);

createCustomBuyLinks(“ALL”, “”, “Microsoft Surface Pro”, “”, “”, 32, marblAmazon.BOTH);

createCustomBuyLinks(“ALL”, “”, “Microsoft Surface Pro”, “”, “”, 32, 1);

createCustomBuyLinks(“ALL”, “”, “Microsoft Surface Pro”, “”, “”, null, 2);

createCustomBuyLinks(“ALL”, “”, “Microsoft Surface Pro”, “”, “”, 32, 3);

Enum’s are available in the class and are the recommended way of mapping the style.

marblAmazon.IMAGE = 1

marblAmazon.TEXT = 2

marblAmazon.BOTH = 3

[7] CutomImagePath <freetext>

string

{Optional} If specified, a relative or absolute URL should be provided to a custom image which will be used to trigger the region selection list.

The DisplayMode should be set to IMAGE or BOTH for the graphic to be visible.

If used, the value of the Size parameter is ignored. If not provided, null, undefined or an empty string, Marbl will fall-back to a 16×16 graphic.

 

MarblEbayLink

<script type="text/javascript">
var marblEbay = new MarblLink('ebay');
    marblEbay.PartnerId = '1234567890';
    marblEbay.CampaignId = '9876543210';
    // Insert valid regions [you can also use "marblEbay.addRegions('GB,BE,US');" to perform the task in-line]
    marblEbay.addRegion('GB');
    marblEbay.addRegion('BE');
    marblEbay.addRegion('US');
    marblEbay.DisplayFlags = true;
    marblEbay.OpenInNewWindow = true;
    marblEbay.createLink("ALL", "", "Intel NUC", "", "", 48, marblEbay.IMAGE);
</script>
Constructor

new MarblEbayLink('<path>')

path Root relative or absolute URL to the Marbl repository path If you do not want to use one of the provided square Amazon logos, you can specify an image to use here. The value is the absolute/relative path to the GIF/JPG/PNG that you wish to use. Set to null to use the defaults.
Setting Your EPN Identity

In order to set your eBay Partner Network (EPN) identity you must set both the PartnerId and CampaignId. If you fail to supply Marbl with both, the eBay click-through will work, however you will not receive compensation for the referral.

marblEbay.PartnerId = '<Your numeric EPN ID>'

marblEbay.CampaignId = '<The Campaign ID that any transaction will be recorded against>'

Adding National Store Support

addRegion('<Country Code>')

Valid country codes are:

  • AT
  • AU
  • BE
  • CA
  • CH
  • DE
  • ES
  • FR
  • IE
  • GB [Note: It is GB for eBay, not UK]
  • IT
  • NL
  • PL
  • US
General Configuration Options

The following options are available as properties.

DisplayFlags [true]/false Displays national flag icons on the dropdown.
OpenInNewWindow [true]/false When a link is clicked, if true the link will open in a new tab/window. If false, the user will be redirected from the current page directly to Amazon, closing your page.
LinksNoFollow [true]/false {recommended} Adds the nofollow attribute to all hyperlinks generated on the page. Your site may be penalised by search engines if you intentionally redirect its crawler to known sponsor and affiliate material. Search engines deem such a practices as representing intentional index spamming.

 

Rendering Links

To perform the actual render, use the createLink() function.

Once a MarblAmazonLink has been created, you can call createLink() as many times as is required, using different parameters. It is not necessary to instantiate a new instance for each and every link on the page.

For example:

<script type="text/javascript">
var marblEbay = new MarblLink('ebay');
    marblEbay.PartnerId = '1234567890';
    marblEbay.CampaignId = '9876543210';
    marblEbay.addRegion('GB');
</script>
<!-- other HTML -->
<script type="text/javascript">marblEbay.createLink("ALL", "Buy Intel NUC on Amazon", "Intel NUC", "", "", 16, marblEbay.BOTH);</script>
<!-- other HTML -->
[0] Regions [ALL]|<CSV List>

string

{Required} A comma separated list of country codes that you would like to display for this link. If set to ‘ALL’, Marbl will use any valid EPN country code provided.

The order of country codes in the CSV is important and will reflect the order shown to the user. You can therefore use the order to prioritise the dispay.

createCustomBuyLinks(“ALL”…

createCustomBuyLinks(“GB,US”…

createCustomBuyLinks(“BE,IT,CA,US”…

[1] Label <freetext>

string

{Optional} If set, will convert the link from an image link into a text label. This is useful for in-line/mid flow where you want the name of the product to trigger the Marbl link as well as or instead of image to appear where positioned.

If set, the value will be added to the image ALT text for accessibility

See the Label Only option below for further control.

createCustomBuyLinks(“ALL”, “Kindle Fire 9 HD”…

createCustomBuyLinks(“ALL”, “”…

[2] Freetext <freetext>

string

{Optional} If set, the link will generate a referral link to Amazon product search. This is often useful for internationalised links where different regions may not share the same ASIN or ISBN, but are more likely to share the same branding or base model number.

If not set, Marbl will look for an ASIN or ISBN value.

createCustomBuyLinks(“ALL”, “”, “Microsoft Surface Pro”…

createCustomBuyLinks(“ALL”, “”, “”…

[3] Item ID <freetext>

string

{Optional} If set, Marbl will create a referral link using the numeric eBay Item ID. This allows you to directly link into the product page.

If not set, Marbl will look for an Item ID in the Freetext field as part of its evaluation.

createCustomBuyLinks(“ALL”, “”, “”, “0123456789”…

createCustomBuyLinks(“ALL”, “”, “”, “”…

[4] Store ID <freetext>

string

{Optional} If set, Marbl will create a referral link using the eBay Store ID. This allows you to directly link into a sellers store.

If not set, and if search or Item ID have not been set, no link will be displayed.

createCustomBuyLinks(“ALL”, “”, “”, “”, “147258369”…

createCustomBuyLinks(“ALL”, “”, “”, “”, “”…

[5] Size [16]|24|32|48|null

int

{Optional} If using one of the built-in icons, the size value will select the icon to be used.

createCustomBuyLinks(“ALL”, “”, “Microsoft Surface Pro”, “”, “”, 16…

[6] DisplayMode [1]|2|3
{enum} [.IMAGE]|.TEXT|.BOTHint
{Optional} Defines whether this is an image only, text only or text + image link.

createCustomBuyLinks(“ALL”, “”, “Microsoft Surface Pro”, “”, “”, 32, marblAmazon.IMAGE);

createCustomBuyLinks(“ALL”, “”, “Microsoft Surface Pro”, “”, “”, null, marblAmazon.TEXT);

createCustomBuyLinks(“ALL”, “”, “Microsoft Surface Pro”, “”, “”, 32, marblAmazon.BOTH);

createCustomBuyLinks(“ALL”, “”, “Microsoft Surface Pro”, “”, “”, 32, 1);

createCustomBuyLinks(“ALL”, “”, “Microsoft Surface Pro”, “”, “”, null, 2);

createCustomBuyLinks(“ALL”, “”, “Microsoft Surface Pro”, “”, “”, 32, 3);

Enum’s are available in the class and are the recommended way of mapping the style.

marblAmazon.IMAGE = 1

marblAmazon.TEXT = 2

marblAmazon.BOTH = 3

[7] CutomImagePath <freetext>

string

{Optional} If specified, a relative or absolute URL should be provided to a custom image which will be used to trigger the region selection list.

The DisplayMode should be set to IMAGE or BOTH for the graphic to be visible.

If used, the value of the Size parameter is ignored. If not provided, null, undefined or an empty string, Marbl will fall-back to a 16×16 graphic.