How to load amber

To load Amber, you should add these <script> tags into your page (placement to head or at the end of body at your own discretion):

    <!-- 1 -->
    <script src="path_to_amber/support/requirejs/require.min.js"></script>
    <!-- 2 -->
    <script src="path_to_amber/support/amber.js"></script>
    <!-- 3 -->
    <script>
        require.config({paths:{
            <!-- 4 -->
            'biz_corp_clientlib': 'path_to_corp_clientlib/js',
            'gh_author_foolib': 'path_to_foolib/js',
            'biz_corp_app': 'code/js',
            <!-- 5 -->
            'biz_corp_app/_source': 'code/st'
        }});
        require([
            <!-- 6 -->
            "amber/devel",
            <!-- 7 -->
            "gh_author_foolib/FooLib-Backend",
            "gh_author_foolib/FooLib-Frontend",
            "biz_corp_clientlib/CorpClient-Bar",
            "biz_corp_clientlib/CorpClient-Baz",
            "biz_corp_app/CorpApp-Model",
            "biz_corp_app/CorpApp-Client"
        ], function (smalltalk) {
            <!-- 8 -->
            smalltalk.defaultAMDNamespace = 'biz_corp_app';
            <!-- 9 -->
            smalltalk.initialize();

            <!-- 10 -->
            smalltalk.Browser._open();
            smalltalk.AppLogic._start();
        });
    </script>

Notes:

1. Loading AMD loader

• path_to_amber can be anything - relative path, absolute path or full URL.
• You need not to load require.js AMD loader from amber, you can load it from any other place you want.
• Not tested, but amber should play just fine with any conforming AMD loader.

2. Loading amber.js script that configures AMD loader

• path_to_amber can be anything - relative path, absolute path or full URL, it depends how you deploy / decide to load amber from.
• amber.js is built so that it can appear after require.js but also before it - it the former case it properly configures require.js, it the latter case it prepares the configuration into require global, using the feature of require.js that uses contents of require global, if it exists, as the configuration upon loading itself.

3. Hand-written script that actually loads Amber including your packages

• it is only required that things described later happen, in that order, sometimes after (1) and (2), but you can structure them as you wish; using <script> tag with presented structure is just a convention.

4. Configuring namespace-to-path mappings for loading packages

• Each package in amber must have a namespace, the part before '/'. There should be exactly one slash in the loader name of package.
• Each namespace represents one physical location to load from, and optionally, to save to; IOW, it represent one URL path; again, it can be relative path (relative to page being loaded), absolute path or full URL path.
• You should point 'namespace' to the location of compiled amber files, which have .js extension. The convention in lot of projects is to put source (Smalltalk) files into .../st and compiled files into .../js where ... is same path. This is why in this example, all three namespaces are mappped into paths that end with /js.
• Namespaces are selected for the library / app (a group of amber packages at the same location) by its developer and are hardcoded into it. For this reason, care must be taken when selecting namespace, so it does not clash with other namespaces. One technique, used in this example as well, is to take the 'path' where the project resides ('corp.biz/clientlib', 'github.com/author/foolib' etc.), revert the domain name ('biz.corp/clientlib', 'com.github/author/foolib' etc.) and replace all separators ('.', '/') with underscores ('biz_corp_clientlib', 'com_github_author_foolib'). One can do some simplifyings if they seem to be safe enough; like shortening github_com_ into gh_.
• This example represents complex application that resides at corp.biz domain. This page loads the app, which has its own code (namespace biz_corp_app), uses some internal library (namespace biz_corp_clientlib) and also uses (contrived) third-party library foolib created by author and developed in github (namespace gh_author_foolib).
• As in previous cases, path_to_corp_clientlib and path_to_foolib can be any URL paths - relative to page being loaded, absolure or full URL paths with protocal, machine etc.
• You can see the namespace biz_corp_app is mapped to relative path code/ja, that is, if this page is http://foo/bar/index.html, the mapped path of biz_corp_app would be http://foo/bar/code/js.

5. Configuring namespace-to-path mappings for saving package sources

• If you map 'namespace/_source' (the special ending /_source), you are mapping the URL path into which the page will try to save sources (file with .st extension) of amber packages in namespace 'namespace'.
• When saving, compiled .js files are saved as well; these are saved into the same path which is used for loading them.
• In this example, if you save any package from namespace corp_biz_app, its .st file is tried to save into code/st/PackageName.st and the compiled file is saved into code/js/PackageName.js.