Documentation : echPCBuilder - Helping build your next PC

echPCBuilder Documentation

Requirements for using echPCBuilder

Access to a web server to host the script and support files. echPCBuilder cannot be run directly from your computer due to a security feature of certain browsers preventing direct access to computer files (reading the XML files)
Knowledge of HTML, CSS, Javascript, XML, time, patience (because you'll probably be using a text editor to edit the components/prices) and a good imagination (=

Web Browser Requirements

Latest browser versions as of 2012 Feb
Although the script may work with earlier browser versions, display relies on CSS and it will be the main issue when supporting earlier browser versions.

Known Issues & Limitations:

IE9: Sorting could be slow depending on the total number of items
IE9: Image sometimes doesn't scale properly if only one dimension is specified
iPad 1 iOS5 Safari: Sorting is a little slow too but less obvious compared to IE9
No search
No pagination

What's included in the package:

echPCBuilder.zip

prod/ - directory contains all the product images described in parte.xml
echPCBuilder.css - most basic css needed for the script to work properly
echPCBuilder.js - main script
order.php - a simple php script that parses the echPCBuilder().getSpecsString()
parte.xml - sample items list. Over 300 components listed
presyo-US.xml - sample item prices
settings.xml - contains the default settings and categories
Other support files

To view the included demos, make a new directory in your web server and copy all the files while maintaining their file structure to your webserver and access: http://yourwebserver.com/newDirectory/index.html

Getting Started

Copy the following files to the target directory: echPCBuilder.js, settings.xml, parte.xml, presyo-US.xml and the prod/ directory. The file list should look something like:

target directory/

prod/
echPCBuilder.css
echPCBuilder.js
parte.xml
presyo-US.xml
settings.xml

Add the following to the external <script> section of your page:

<script src="echPCBuilder.js"></script>

Add the following external CSS to the <link> section of your page:

<link rel="stylesheet" type="text/css" media="screen, handheld, print" href="echPCBuilder.css">

Add the following HTML code somewhere in the content of your page:

<div id="echPCViewer"></div>
<div id="echPCSpec"></div>
<div id="echPCList"></div>

Optional HTML codes:

<div id="echPCPriceTotal"></div>
<div id="echPCPorts"></div>
<div id="echPCLastUpdate"></div>

To start echPCBuilder(), add the following onload event in the <body> of your page:

<body onload="var myShopPCBuilder = new echPCBuilder({});">
<-- the "{}" is required. Otherwise, use myShopPCBuilder.init() to start the script -->

or add var myShopPCBuilder = new echPCBuilder({}); in your window.onload function.

And that's it! Access YourOwnPage.html from your browser and see echPCBuilder in action.

Optional Settings

The following is for your reference to customize certain settings in the script before it is run:

echPCBuilder({
p: { settings: 'settings.xml', /* script settings. Contains the categories and any settings the script might use in the future. this parameter is required if settings.xml is not in the same directory as the calling page */ itemList: '', // user-defined item list. This value overrides the value defined in the settings.xml priceList: '', // user-defined price list. This value overrides the value defined in the settings.xml ignoreList: 'id,tag,req_tag,disable_tag,IDIQ,MQ,disable', /* item@attributes to ignore when getting the build ports/sockets/slots/etc. Case-sensitive. Setting the property here will *override* the default */ /* item@tag to look for when when displaying the pc build. The values below shouldn't be altered unless you're absolutely sure you know what you're doing. */ monitorTags: 'mon', caseTags: 'case_miniTower|case_midTower|case_fullTower', kbTags: 'kb', mouseTags: 'mouse', kbMouseTags: 'kbmouse', portSortKeys: 'cpu,ddr3,ddr2,ddr1,pcie16,pcie4,pcie1,pci,sata,esata,msata,ieee1394,usb,bt,ps2,ide,floppy,lpt,com,dp,hdmi,dvi,vga', // sort order in the port list display imageURLPrefix: '', // text prefix for the item image. Only added if the current URL is a relative path productURLPrefix: '', // text prefix to the item product link. Only added if the current URL is a relative path sepGroup: ',', /* thousand separator. '.' for euro. The prices in the XML must reflect this separator or the script may not format the numbers correctly */ sepDecimal: '.', /* decimal separator. ',' for euro. The prices in the XML must reflect this separator or the script may not format the numbers correctly */ sepItem: ';', // item separator for the getSpecsString() sepQty: '|', // item quantity separator for the getSpecsString() skipCheck: 0 /* used when checking if the item can be added. Setting to 1 will defers the normal checking procedure. Should only be used when loading a build. */ },
// these are the classnames (or classname prefix) used on the generated elements s: { catList: 'echPCCatList', // applies to the UL listing the categories catName: 'echPCCatName', // applies to the H3 holding the category name catDesc: 'echPCCatDesc', // applies to the DIV holding the category description itemCount: 'echPCItemCount', // applies to the SPAN specifying the number of selected items for a particular category itemList: 'echPCItemList', // applies to the UL for the item list numberInputControl: 'echInpUpDown', // applies to the DIV holding the INPUT and 2x SPAN's to control the input@type==number viewMonitors: 'echPCVMonitors', // applies to the DIV holding all the monitors in the PC build viewer viewMonitor: 'echPCVMonitor', // applies to the DIV (used as a row) containing the monitor IMG(s) viewComponents: 'echPCVComponents', // applies to the DIV holding the other components in the PC build viewer (case, kb, mouse, kbmouse) viewCase: 'echPCVCase', // img.class for the selected chasis viewKB: 'echPCVKB', // img.class for the selected keyboard (if present) viewMouse: 'echPCVMouse', // img.class for the selected mouse (if present) viewKBMouse: 'echPCVKBMouse', // img.class for the selected keyboard & mouse combo (if present) productName: 'echPCPName', // applies to the SPAN holding the product name under the item and specification list productImage: 'echPCPImage', // applies to the DIV holding the item IMG productDesc: 'echPCPDesc', // applies to the DIV holding the item description under the item and specification list productLink: 'echPCPLink', // applies to the DIV holding the product link under the item list price: 'echPCPrice', // applies to the DIV holding the item price under the item list or the SPAN under the specification list priceTotal: 'echPCPriceTotal', // applies to the SPAN holding the TEXT label for the price priceSymbol: 'echPCPSymbol', // applies to the SPAN holding the price symbol portPfx: 'echPCPort_', // class prefix for the port list display tags added: 'echPCAdded', // applied to the LI (containing the item info) under the item list specifying that the item has been added delete: 'echDelete', // applies to the delete and clear BUTTON under the specification list err: 'echErr', /* applies to the SPAN under the port list display indicating that the number of ports used is greater than the number of ports available */ add: 'echAdd', // applies to the (add/remove) BUTTON for an item under the item list on: 'echOn', /* added to the LI containing the item info under the item list indicating that the item has been clicked on or has focus. */ off: 'echOff', /* Generic class *added* to several objects to indicate that it's in the off state. These include the ff: DIV.productImage DIV.description DIV.link DIV.price LI.category - if the category is set to be hidden LI.item - if the maximum quantity for the category has been reached port list container if there are no ports to display PC build viewer if there are no monitor, case, mouse and kb selected */ disabled: 'echDisabled' /* Generic class *added* to several objects. These include: LI.category - if there are no items listed under this category DIV.numberInputControl - if only a fixed quantity is allowed for an item LI.item - if the selected item has a disable_tag that matches a tag for this item */ },
// container element id's id: { viewer: 'echPCViewer', // Container to display the look of the PC. The components displayed are the monitors, case, keyboard and mouse. spec: 'echPCSpec', // Container to display the list of selected components, their corresponding prices and the total. ports: 'echPCPorts', // Container to list the available ports for the current pc build item: 'echPCList', // (REQUIRED) This is required by the script in order to display the categories and their items. priceUpdate: 'echPCLastUpdate', // container for the last price updated date priceTotal: 'echPCPriceTotal' // container to hold the total price },
setLang: '(en|languageCode)', // language to use. Default is 'en'
// text labels lang: { (en|languageCode): { spec_empty: 'There are no selected items.', // text to display if there are no selections spec_clear: 'Clear Parts', // text on the button to clear the selected components total: 'Total', // text label for the total in the selected components list add: 'Add', // text on the button to add an item remove: 'Remove', // text on the button to remove an item. Affects buttons in the item list and specifications label_product_link: 'Product page', // text on the product page link label_product_photo:'[Product photo]', // image.alt on the product thumbnail label_unknown: 'No label', // generic text to display if (category|item)/name is not available /* the following properties prefixed with 'label_' are used on the port list display and are the [itemProperty]'s (ie: cpu, sata, esata) used in the items file (parte.xml) */ label_cpu: 'CPU', label_ddr3: 'DDR3 Slots', label_pcie16: 'PCIe x16', label_pcie4: 'PCIe x4', label_pcie1: 'PCIe x1', label_pci: 'PCI', label_ps2: 'PS/2', label_floppy: 'Floppy', label_ide: 'IDE|PATA', label_lpt: 'Parallel Port', label_com: 'Serial Port', label_usb: 'USB', label_ieee1394: 'Firewire', label_bt: 'BlueTooth', label_sata: 'SATA', label_esata: 'eSATA', label_msata: 'miniSATA', label_dp: 'Display Port', label_hdmi: 'HDMI', label_dvi: 'DVI', label_vga: 'VGA', err_req_param_missing: 'echPCBuilder() is unable to run due to missing required parameters.', // displayed if the minimum required parameters are missing (settings and item list container) err_add_item: 'Unable to add "%item%" at this time.\n\nPlease check if your build meets the requirements of the item.', // text to display if the item cannot be added to the current pc build where %item% is replaced by the item name err_inc_item: 'Unable to add another "%item%" at this time.\n\nPlease check if your build meets the requirements of the item.', // text to display if the current build cannot handle the increase of quantity of the selected item err_category_blank: 'There are no categories to list.\nTry reloading or if the problem persists, please contact the site owner.', // text to display if the settings.xml has been loaded successfully however there are no categories to list. err_loading_settings: 'An error occured while loading the settings. Try reloading or if the problem persists, please contact the site owner.', // text to display if the settings file is missing err_missing_items_list: 'The items list is not defined.\nUnable to list the components.', // text to display if the item list is not defined (from the settings.xml) err_loading_items_list: 'An error occured while loading the items list.\nTry reloading or if the problem persists, please contact the site owner.' // text to display if an error occured while loading the items list // to suppress alert() messages, set these variables to blank '' } },
// custom events onsettingsloadstart: function() { /* do something */ }, // called before the settings.xml is downloaded onsettingsload: function() { /* do something */ }, // called after rendering the categories list or after an error occurs while downloading the settings.xml onitemlistloadstart: function() { /* do something */ }, // called before the parte.xml is downloaded onitemlistload: function() { /* do something */ }, // called after listing the items or after an error occurs while downloading parte.xml onpricelistloadstart: function() { /* do something */ }, // called before the presyo.xml is downloaded onpricelistload: function() { /* do something */ }, // called after the item prices have been added or after an error occurs while d/l presyo.xml onitemclick: function() { /* do something */ }, // called when an item name is clicked on onitemadd: function() { /* do something */ }, // called when an item has been added to the specifications onitemremove: function() { /* do something */ }, // called after an item has been successfully removed from the specifications onsortstart: function() { /* do something */ }, // called before sorting starts onsortend: function() { /* do something */ }, // called after sorting onalert: function() { /* do something */ } // replaces the alert() function in the script. The alert text is passed to the custom function
});

echPCBuilder() Methods

echPCBuilder().init()

Runs and returns an instance of the script. See the Optional settings to see the parameters that can be passed to the method.
echPCBuilder().loadPrices(priceListURL)

Loads the price list (priceListURL). This will replace the prices currently displayed. See: presyo.xml for the XML structure.
echPCBuilder().addLang()

Updates a label.
- echPCBuilder().addLang( { en: { spec_empty: 'You have yet to select a component.', total: 'Total Price' } } );
echPCBuilder().addItem(itemID [, itemQty] )

Adds an item to the specifications. itemID is the @id from the parte.xml/item.

(optional) itemQty represents the quantity of the item to be added. Default is 1.
echPCBuilder().delItem(itemID[, force])

Removes one quantity of the item from the specifications. itemID is the @id from the parte.xml/item

(optional) force = 1 removes the item from the specification regardless of quantity
echPCBuilder().getItemInfo(itemID)

Returns the item XML node from parte.xml whos item@id == itemID
echPCBuilder().getItemPrice(itemID)

Returns the price(nodeValue) from presyo.xml which can be a number or a string
echPCBuilder().getObject(objectName)

Returns the HTML node for objectName where objectName can be any of the following:
- 'category' - The script generated UL node containing the category list
- 'viewer' - The HTML node with id="echPCViewer"
- 'spec' - The HTML node with id="echPCSpec"
- 'ports' - The HTML node with id="echPCPorts"
- 'total' - The HTML node with id="echPCPriceTotal"
- 'selected' - The selected script-generated LI node containing the item info/price in the items list.
echPCBuilder().getSpec()

Returns an array of structure containing the item id, name and item xml node (from parte.xml)

Element structure:
- { id: item@id, name: item/name, xml: (parte.xml)/item, qty: x }
echPCBuilder().getSpecsString()

Returns a ";"-delimited list of selected components where the item@id and quantity (>1) is separated by "|".

ie: BX80623I72600K;GA-Z68MA-D2H-B3;F3-10666CL9D-16GBXL|2

The item and quantity separators can be modified by setting the p.sepItem & p.sepQty (see Optional Settings)
echPCBuilder().clearSpec()

Clears the selected components
echPCBuilder().toggleProperty(propertyType [, showProperty] )

Adds/Removes the 'off' class name to the specified propertyType. Where propertyType can be any of the following:
- 'name' - item name
- 'image' - item thumbnail in the item list. No thumbnail is generated under the specifications. This will not affect the images in the pc build viewer
- 'description' - item description
- 'link' - item product link
- 'price' - item price.
Unless specified, it affects the item properties under the item list and the specifications.

showProperty = 1|0 Default for showProperty is 0 (add 'off' class).

The 'off' class name will be added to the DIV or SPAN container containing the specified propertyType.
echPCBuilder().toggleCategories(showCategories)

Adds/Removes the 'off' class name for ALL the categories.

showCategories = 1|0 1 to display the category. Default is 0

See the Optional Settings for the actual class name
echPCBuilder().setProperty('propertName', propertyValue)

Sets the variables in (optional settings) p.{name}

The only useful property to set is the 'skipCheck' where it will defer checking if adding an item is valid in the current build. Useful when loading a previous build and the items may not be in order.
echPCBuilder().getProperty('propertyName')

Returns the values defined in (optional settings) p: { propertyName: '' }
echPCBuilder().sort(sortKey [, sortDir])

Sorts all the items based on sortKey &l; sortDir

sortKey = 'name|price' Sorts the item list based on sortKey

sortDir = 'asc|des' Default sort direction is ascending
echPCBuilder().clear()

Clears the entire generated HTML. You can then call echPCBuilder().init() again.

Improving Performance

To improve performance: limit the number of items to list, resample and optimize the product images and re-use images whenever possible. As of this writing, the demo pages from the Demos Section currently displays >300 items. And the demo in the main page only lists >10 items. All of them use the same price list file.

Adding Items & Prices

To add an item, edit parte.xml with your XML editor and add the item information there. The presyo.xml will also need to be edited to add the price for the item.

Checking of item requirements depends on how well you define the related items but keep in mind the more complex the information the harder it would be to maintain the item list.

See the parte.xml and presyo.xml description below for more information.

Consult with your preferred web developer on how to automate the creation of the items and price list.

Editing the Price List with MS Excel 2010

Before editing the price list, make a backup of the file first.

Included in the package is the XML schema for the price list (presyo.xsd). To edit the price list using Excel first add the Developer Tab. To add the Developer Tab, refer to: http://msdn.microsoft.com/en-us/library/bb608625.aspx or search for "Excel Adding Developer Tab to Ribbon".

Click on the Developer Tab and click on the Source button in the XML group.

On the XML Source pane that will appear, click on the XML Maps and click on the Add button and look for presyo.xsd.

In the Multiple Roots dialog that will appear, select the "price_list" as the root and click OK to close the dialog.

From the XML Source pane, drag the "item" node to cell A2.

Drag the "currency" attribute to A1 and the "symbol" and "lastUpdate" attribute in B1 and C1.

In the Developer Tab and under the XML group, click on Import option and look for presyo.xml

You can now edit the prices of the item.

To save your updated price list, click on the Export option and save it as presyo.xml or whatever file is set by the script to use.

Due to the free-form nature of the items list (parte.xml), no schema is available for it.

Other XML Editors

The following programs can be used to edit XML files: Notepad, Vim, or XML Copy Editor ( http://xml-copy-editor.sourceforge.net/ )

Other applications of echPCBuilder

Although echPCBuilder was designed to handle PC components, the script can also be applied to any objects with defined connectors. One limitation however are the images displayed in the viewer. Without access to the source, your creativity in displaying the items might be tested ;)

It can also be used as a simple shopping cart but there are already a lot of simple shopping cart out there (=

Generated HTML

The following is a sample HTML generated by the script and its potential values/classes

With regards to CSS: Except for one instance, echPCBuilder() doesn't directly access the style of individual elements. Styling is done by adding/removing classes. The only instance that echPCBuilder() directly accesses element.style is when displaying multiple monitors where it specifies the image.style.maxWidth in percentage.

Categories & Items List
- <div id="echPCList">
- <ul class="echPCCatList">
-  <li data-mq="1" data-tag="cpu_intel,cpu_amd" data-type="cat"> <h3 class="echPCCatName echOff">CPU<span class="echPCItemCount">1</span></h3>  <ul class="echPCItemList"> <li data-tag="cpu_amd,cpu_amd_fm1" data-id="AD3650WNGXBOX" class="echDisabled echPCAdded echOff"> <button title="Add" class="echAdd">Add</button>  <div class="echPCPImage echOff"><img alt="[Product photo]" src="prod/AMD_A63650_thumb.jpg"></div> <span class="echPCPName echOff">AMD® A6-3650 APU (4M Cache, 2.6 GHz)</span> <div class="echPCPDesc echOff">Socket FM1, 2.6 GHz, 4MB Cache, 4 cores, 100W TDP, Radeon HD 6530D</div> <div class="echPCPLink echOff"><a target="_blank" href="http://www.amd.com/us/products/desktop/processors/a-series/Pages/a-series-model-number-comparison.aspx">Product page</a></div> <div class="echPCPrice echOff"><span class="echPCPSymbol">PhP</span>5,250.00</div> </li> </ul>  </li> 
- </ul>
- </div>
Specifications List
- <div id="echPCSpec">
- <ul>
- <li data-qty="1" data-id="BX80623I72600K"> <button title="Remove" class="echDelete">Remove</button> <div class="echInpUpDown echDisabled">  <input maxlength="1" type="text"> <span></span> <span></span> </div> <span class="echPCPName echOff">Intel® Core™ i7-2600K Processor (8M Cache, 3.40 GHz)</span> <div class="echPCPDesc echOff">LGA 1155, 3.4 - 3.8 GHz, 8MB Cache, 4 Cores/8 Threads, 95W TDP, Intel® HD Graphics 3000</div> <div class="echPCPrice echOff"> <span class="echPCPSymbol">PhP</span>13,950.00 </div> </li>
- <li data-qty="2" data-id="F3-10666CL9D-16GBXL"> <button title="Remove" class="echDelete">Remove</button> <div class="echInpUpDown"> <input maxlength="1" type="text"> <span></span> <span></span> </div> <span class="echPCPName echOff">G.Skill Ripjaws 16GB (2x8GB) DDR3 1333Mhz</span> <div class="echPCPDesc echOff"></div> <div class="echPCPrice echOff"> <span class="echPCPSymbol">PhP</span>11,920.00 </div> </li>
- <li> <span class="echPCPriceTotal">Total</span> <span class="echPCPrice echOff"><span class="echPCPSymbol">PhP</span>31,770.00</span> </li>
- </ul>
- <button class="echDelete">Clear Parts</button>
- </div>
PC Build Viewer
- <div id="echPCViewer">
- <div class="echPCVMonitors"> <div class="echPCVMonitor"> <img style="max-width: 50%;" src="prod/Dell_U2412M_multi_pcb.png">  <img style="max-width: 50%;" src="prod/Dell_U2412M_multi_pcb.png"> </div> <div class="echPCVMonitor"> <img style="max-width: 50%;" src="prod/Dell_U2412M_multi_pcb.png"> <img style="max-width: 50%;" src="prod/Dell_U2412M_multi_pcb.png"> </div> </div>
- <div class="echPCVComponents"> <img src="prod/Fractal_DefineMini_pcb.png" class="echPCVCase"> <img src="prod/Logitech_MK710_pcb.png" class="echPCVKBMouse"> </div>
- </div>
Ports List Display
- <div id="echPCPorts">
- <ul>
- <li class="echPCPort_cpu"> <span title="CPU">CPU</span> <span> <span>1</span> <span>1</span> </span> </li> <li class="echPCPort_ddr3"> <span title="DDR3 Slots">DDR3 Slots</span> <span> <span>4</span> <span>4</span> </span> </li>
- </ul>
- </div>

Description Of XML Files

settings.xml

Contains the category list, default item and price list.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<settings itemList="parte.xml" priceList="s/presyo-PH.xml" >
<categories>
<category tag="cpu_intel,cpu_amd" hide="1" MQ="1" IDIQ="1" > <name><![CDATA[CPU]]></name>  <description<![CDATA[cpu description]]></description>  </category>
<category ...> ... </category>
</categories>
</settings>

parte.xml

Contains the item and relevant information to be listed.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<items_list>
<item id="ProductId" tag="cpu_amd,cpu_amd_am3" req_tag="mb_amd_am3,ram_ddr3" disable_tag="cpu_intel,mb_intel" cpu="1" > <name><![CDATA[AMD® Phenom II X4 960T Processor (6M Cache, 3 GHz)]]></name>  <description><![CDATA[Product name]]></description>  <url><![CDATA[relative or full url to product page]]></url>  <image><![CDATA[relative or full path to image]]></image>  <image type="build"><![CDATA[relative or full path to image]]></image>  <image type="multi"><![CDATA[relative or full path to image]]></image>   </item>
<item ...> ... </item>
</items_list>

A word about req_[itemProperty], [itemProperty]_in, match_[itemProperty] & [itemProperty]_check

echPCBuilder first builds a list of [itemProperties] before performing a check against req_, _in, match_, & _check. What this means is that if you want the users to follow a particular sequence in building the PC, use the prefix|suffix [itemProperty] for later items. An example would be if you want to check if a graphics card would fit in a particular case but you want the user to select a case first. The case would have an [itemProperty] like: maxPCILength="290" and the graphics card would have an [itemProperty] like: maxPCILength_check="181".

presyo-x.xml

Contains the prices for the item.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<price_list currency="Philippine Peso" symbol="PhP" lastUpdate="2012 Feb 23 - 08:31 PM" >
<item id="HD96ZTWFGRBOX"> <name><![CDATA[AMD® Phenom II X4 960T Processor (6M Cache, 3 GHz)]]></name>  <price>5925.00</price>  </item>
<item ... > ... </item>
</price_list>

One of the most common error if the browser is not displaying the content of the XML and the XML validates, is the file encoding.

If this happens, try encloding the value in <[CDATA[Some value here]]> or save the file in Unicode format.

How to check if your XML is well-formed

To check if your XML is valid, refer to this site: http://validator.w3.org/

echPCBuilder Documentation

Contents

Requirements for using echPCBuilder

Web Browser Requirements

Known Issues & Limitations:

What's included in the package:

Getting Started

Optional Settings

echPCBuilder() Methods

echPCBuilder().init()

echPCBuilder().loadPrices(priceListURL)

echPCBuilder().addLang()

echPCBuilder().addItem(itemID [, itemQty] )

echPCBuilder().delItem(itemID[, force])

echPCBuilder().getItemInfo(itemID)

echPCBuilder().getItemPrice(itemID)

echPCBuilder().getObject(objectName)

echPCBuilder().getSpec()

echPCBuilder().getSpecsString()

echPCBuilder().clearSpec()

echPCBuilder().toggleProperty(propertyType [, showProperty] )

echPCBuilder().toggleCategories(showCategories)

echPCBuilder().setProperty('propertName', propertyValue)

echPCBuilder().getProperty('propertyName')

echPCBuilder().sort(sortKey [, sortDir])

echPCBuilder().clear()