You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
<p>The Typecode-JS Javascript library consists of a variety of utilities, modules, and small frameworks that can be used to build rich UIs in web applications. All the code uses <ahref="http://jquery.com" target="_blank">jQuery</a> internally. All the individual components also expect the seed file (<code>tc.seed.js</code>) to be loaded first. A few components depend on other parts of the library to be loaded first, which isx noted on a case by case basis, in a comment at the top of a given component file.</p>
18
+
</section>
19
+
20
+
<sectionid="seed">
21
+
<header>
22
+
<h2>Seed</h2>
23
+
<divclass="meta">
24
+
<h3>Files</h3>
25
+
<ul>
26
+
<li>tc.seed.js</li>
27
+
</ul>
28
+
</div>
29
+
</header>
30
+
31
+
<p>The seed file defines one global object, <code>NI</code>, that serves as the namespace for all the subsequently loaded components in the library. For example, the Overlay module that's defined in <code>tc.overlay.js</code> adds itself to the <code>NI</code> object, and can subsequently be accessed at <code>NI.Overlay</code>.</p>
32
+
33
+
<aside>
34
+
<h3>Why NI?</h3>
35
+
36
+
<p>NI seems like a random name for the namespace object. The intention behind it was merely to have a likely-to-be-unique name that was also very short, since it gets typed a lot. It orginially stood for <em>New Instruments</em>, but that does not have any significant meaning.</p>
37
+
</aside>
38
+
39
+
<h3>Other Things in Seed</h3>
40
+
41
+
<p>The seed file also populates <code>NI</code> with some very general purpose utils, which are further grouped into namespaces. They're here just so they are available to the components throughout the library.</p>
42
+
43
+
<p>The object <code>NI.ex</code> contains a handful of functions for examining and verifying variables.</p>
44
+
45
+
<p><code>NI.app</code> houses some functions that were originally designed to help bootstrap an application, but most of these facilities are actually now provided by a newer and seperate module, <ahref=""><code>NI.App</code></a>. One exception is the function <code>NI.app.getConsole</code>, which can be called to setup a dummy <code>console</code> object to deal with environments (like old versions of Internet Explorer) that don't necessarily have a global <code>console</code> available. This is discussed in further detail in the <ahref=""><code>NI.App</code> section</a>.</p>
46
+
47
+
<p>A handful of miscelaneous functions can be found in <code>NI.fn</code>. These were originally pretty experimental and aren't being used a lot throughout the library components right now.</p>
48
+
49
+
<p><code>NI.co</code> is used for storing constants. Although there's no mechanism in place to actually enforce this, variables in <code>NI.co</code> should be treated as read-only, and by convention have names in all capital letters. Throughout the library, some other modules (fox example, <ahref=""><code>NI.field</code></a>) define their own <code>co</code> namespaces to hold constants specific to themselves.</p>
<p>The majority of the components in Typecode-JS are constructor functions that take one argument when they are instantiated. The convention we use is to call this argument <code>options</code>. It's an object that the user passes in that defines configuration parameters for the given component. It is typically merged with a set of defaults that the component defines. Sometimes certain config params are required to be passed in, and sometimes they really are optional. Internally, a given component usually has a private variable named <code>o</code>, which is the result of merging the passed in <code>options</code> with the defaults.</p>
60
+
61
+
<p>A lot of the instantiable components in the library manipulate, create, and/or refer to HTML elements that are either already in or eventually get added to the <abbr>DOM</abbr>. For example, an <ahref=""><code>NI.Carousel</code></a><q>carousel</q> refers to an HTML container element (such as a <code>div</code>) that has elements inside of it representing its individual panels. Typically, components of this nature keep a variable named <code>$e</code>, which is a jQuery object representing the outermost element that the component affects. (The dollar sign in variable names is just a convention we use to signify that the variable is a jQuery object). Many of the components that have an <code>$e</code> element allow that element to be explicitly passed in through the <code>options</code> object. In some cases, you can alternatively pass in an option named <code>selector</code>, which is a jQuery selector that the component will use to find and define its <code>$e</code> variable. This pattern is currently not fully consistent throughout the library, but it's what we've generaly been moving to.</p>
62
+
63
+
<p>We're generally good about <em>not</em> defining the visual styling of elements used throughout the library. Occasionally, you will see some javascript code in Typecode-JS that does explicitly set css properties on certain elements. We only do this when the elements require those properties to do what they're supposed to. These properties tend to be things like <code>display</code> or <code>position</code> and never affect the visual appearance of anything.</p>
64
+
</section>
65
+
66
+
<sectionid="overlay">
67
+
<header>
68
+
<h2>Overlay</h2>
69
+
<divclass="meta">
70
+
<h3>Files</h3>
71
+
<ul>
72
+
<li>tc.overlay.js</li>
73
+
</ul>
74
+
</div>
75
+
</header>
76
+
77
+
<p>An <code>NI.Overlay</code> instance is used to show and hide content in a modal overlay. We typically use it for things like confirm/cancel dialogs and lightbox-esque slideshows, but it can be used to render arbitrary content in a container on top of the HTML page.</p>
78
+
<p><code>NI.Overlay</code> creates its own <code>$e</code> element (with <code>display: none;</code> by default) and automatically appends it to the <abbr>DOM</abbr>. By default, overlays are just appended to the <code><body></code>, but if you want to append it to some more specific element you can pass in a <code>context</code> option, which is a selector to the element where the overlay will be inserted. For example, let's say we have a <code><div id="page-wrapper"></code> and we want to create an overlay whose elements live inside it.</p>
79
+
80
+
<pre><code>var overlay = new NI.Overlay({
81
+
context: "#page-wrapper"
82
+
});</code></pre>
83
+
84
+
<p>You can get a jQuery object representing the entire overlay container element by calling <code>getOverlay()</code> on the instance.</p>
85
+
86
+
<p>Once you have an <code>NI.Overlay</code> instance, you can specify what HTML content it contains. The overlay lets you set three distinct regions of content: a header, a body, and a footer. It is never required to set all three, they're just there to help break down the overlay content into independent pieces if you want. To set the body content of the overlay, call <code>setBody()</code> on the instance and pass in either a jQuery object representing the content, or a string of HTML.</p>
87
+
88
+
<pre><code>overlay.setBody("<p>Welcome to my app!<p>");</code></pre>
89
+
90
+
<p>There are analogous functions for setting the header and footer content: <code>setHeader()</code>, <code>setFooter()</code>. You can change a given region of content at any later point just by calling the corresponding setter function again. The content you set will always replace any content that was already there. If you need, you can get a jQuery object representing a given region of the overlay's current content by calling <code>getHeader()</code>, <code>getBody()</code>, or <code>getFooter()</code> on the instance.</p>
91
+
92
+
<p>The overlay starts out in a closed state, which means it's hidden. To actually cause it be shown, you open it by calling <code>open()</code> on the instance…</p>
93
+
94
+
<pre><code>overlay.open();</code></pre>
95
+
96
+
<p>…and once it's in an opened state, you can call <code>close()</code> to close it.</p>
0 commit comments