Getting Started

Setting Up

Like any other web application, a Socks applications needs an HTML document that loads Socks and the application source itself. You can create this HTML document manually or more preferably, you could use the “socks-template.html” that you can download here. You also have to download Socks JavaScript file here and place it in the same directory where you have placed the HTML document file.

Now, open up the HTML document in your favorite text editor, and look for the following line

<script src="socks-0.7-full.js" type="text/javascript" charset="utf-8"></script>

and check that the name of the Socks file (`socks-0.7-full.js` in this case), is the same as the one you have downloaded. Make modifications if necessary. Say if you are using `socks-0.7-compressed.js`, then change `` to ``. Also, don’t forget to include the path if you have placed Socks JavaScript file in a different directory.

Now look for the following code in the file:

<script type="application/javascript-socks" charset="utf-8">

  myApp = Socks.app() {
    // your code goes here
    para('Hello World'); // you can remove this
  };

  myApp.run("app");

</script>

This `` block is where you will actually write your application code. A “Hello World” application has been written for you. Open the HTML document in your web browser and check if “Hello World” appears. If you see “JavaScript must be enabled to view this application” instead, then check whether you have placed and loaded the Socks JavaScript file properly and enable JavaScript if it is disabled in your web browser.

If everything is properly set up and you see “Hello World”, then you are ready to write your application. Place your code inside `Socks.app() { … }` block.

Creating Texts

`para` method is used to create a text block which has a font size of 12 pixels by default. `para` stands for “paragraph.” The following shows how `para` and any other text block methods such as `title`, `banner` and `tagline` can be used.

para("Hello World") ;	→	Hello World
para("Hello ", strong("World"));	→	Hello World
para(em("Hello "), ins("World "), br, del("Bye"));	→	Hello world Bye
para("Go to ", link("Wikipedia","http://wikipedia.org/"));	→	Go to Wikipedia

The `strong`, `em`, `ins`, `br`, `del` and `link` are text fragment methods and they have to be inside text fields in order to be displayed.

A complete list of text blocks and text fragments can be found in Text.

Creating Controls

Controls such as buttons, editlines (textfields) and checkboxes can also be created easily. To create a button, do the following:

button("Click me")

Refresh the page, and you will see that a button with the text “Click me” is created.

To make the button actually do something, add a closure using braces ({ }) like the following example:

button("Click me") {
  alert("Ouch");
};

Refresh the page and click the button. You will see that a message box containing the text “Ouch!” is displayed.

Now let’s create a text field where the user can enter a text. Socks has two types of text fields, a single-line text field called `editLine` and a multi-line text field called `editBox`. Try the following:

para("Type your name: ");
var nameField = editLine();

Refresh the page and you will see this:

In Socks, every method that creates an element returns the element as an object, and in the code above, the EditLine object returned is assigned to a variable called `nameField`. This reference to the object can then be used to invoke methods associated to it, which allows you to access the attributes or manipulate the object. In order to read from the text field, you can use `getText` method. Add the following code and try it.

button("Your name is...") {
  alert(nameField.getText());
};

A complete reference to Socks controls can be found in Controls.

Designing Layout Using Slots

`stack` and `flow` blocks are used to design the layout of the application and in Socks, these are called slots.

Stacks

In a `stack` slot, elements are placed in a vertical stack, meaning an element is placed below the preceding element.

stack {
  button("first");
  para("second");
  editLine("third");
};

Flows

In a `flow` slot, elements are placed horizontally, meaning an element is placed on the right side of the preceding element.

flow {
  button("first");
  para("second");
  editLine("third");
};

Stacks and Flows can also be nested and placed inside each other to create a more complex layout.

var firstName, lastName,
    age, sex, location, married;

stack {
  flow {
    para("First Name:");
    firstName = editLine();
  };

  flow {
    para("Last Name:");
    lastName = editLine();
  };

  flow {
    para("Sex:");
    sex = listBox(["Male", "Female"]);
  };

  flow {
    para("Location:");
    location = editLine();
  };

  flow {
    married = check();
    para("Married");
  };
};

`Socks.app` and `canvas` are slots as well, and they behave like flows. Slot methods, just like element methods, return objects and these can be used to manipulate or insert more elements.

A complete reference to Socks slots can be found in Slots.

Setting Styles

You can set styles to alter the look and feel of the slots and elements. You can either define the style in the slot/element creation methods or you could use `setStyle` method.

The following example shows how styles can be attached to make the form we have created earlier in Slots section prettier.

var firstName, lastName,
    age, sex, location, married;

stack({ margin: 20, padding: 20, 
        border: { width: 1, color: '#888' },
        backgroundColor: '#ddf' }) {

  flow({ marginBottom: 10 }) {
    para({ width: 80, marginRight: 10,
           fontWeight: 'bold', textColor: 'red' }, "First Name:");
    firstName = editLine();
  };

  flow({ margin: { top: 10, bottom: 10 } }) {
    para({ width: 80, marginRight: 10,
           fontWeight: 'bold', textColor: 'red' }, "Last Name:");
    lastName = editLine();
  };

  flow({ margin: { top: 10, bottom: 10 } }) {
    para({ width: 80, marginRight: 10 }, "Sex:");
    sex = listBox(["Male", "Female"]);
  };

  flow({ margin: { top: 10, bottom: 10 } }) {
    para({ width: 80, marginRight: 10 }, "Location:");
    location = editLine();
  };

  flow({ margin: { top: 10, left: 90 } }) {
    married = check({ marginRight: 5 });
    para("Married");
  };
};

Drawing Graphics

You can draw graphics using Canvas. A canvas can be created using `canvas` method, which creates a flow-like slot which has canvas graphics methods. The following is an example:

canvas({ width: 200, height: 200 }) {
  var drawS = function() {
    beginPath();
      moveTo(0, 0);
      lineTo(100, 0).lineTo(100, 20).lineTo(20, 20);
      lineTo(20, 40).lineTo(100, 40).lineTo(100, 100);
      lineTo(0, 100).lineTo(0, 80).lineTo(80, 80);
      lineTo(80, 60).lineTo(0, 60).lineTo(0, 0);
    fill();
  };

  save();
    translate(10, 40);
    rotate(-20 * Math.PI / 180);
    setLineWidth(5);

    save();
      setStrokeStyle('#88f');
      var gradient = createLinearGradient(0, 0, 0, 100);
      gradient.addColorStop(0, '#eef');
      gradient.addColorStop(1, '#aaf');
      setFillStyle(gradient);
      setLineCap('square');
      drawS();
      stroke();
    restore();

    save()
      setGlobalAlpha(0.2);
      setGlobalCompositeOperation('destination-over');
      setFillStyle('#000');
      translate(10, 10);
      drawS();
    restore();
  restore();
};

Please note that canvas graphics requires a browser that supports HTML5 canvas element. There are slight differences between HTML5 standard canvas API and Socks canvas API, that are easy to remember. For more information, refer to Canvas.