Learn Forge

To view tutorials, please visit learnforge.autodesk.io.

This repository is for creating the tutorials.

Adding a new language

View Models sample (2-legged)

Create a project in the programming language that supports the UI described on Viewer front-end. In summary, the back should implement:

GET /api/forge/oauth/token: return a valid viewables:read access token in the form of {'access_token':value, 'expires_in':value}
POST /api/forge/oss/buckets: create a new bucket, receive input in the form of {'bucketKey': 'theKey'} and return 200.
GET /api/forge/oss/buckets: return all buckets or objects in form of list of nodes:

[
  {
   "id": "bucketKey | objectNameAsURNBase64",
   "text": "bucketKey | objectName",
   "type": "bucket | object",
   "children": "true | false"
  }
]

It receives a querystring with id: if # return all buckets, if a bucketKey all objects for the bucket.

POST /api/forge/oss/objects: receive a file with key fileToUpload and bucketKey as a multipart/form-data. For simplicity, non-resumable.
POST /api/forge/modelderivative/jobs: translate the file, receive input in the form of {'bucketKey': 'theKey', 'objectName': 'theName'}

For reference, when adding a new language, replicate all net.md for the new language. The Viewer section should be the same for all languages.

View Hub Models sample (3-legged)

GET /api/forge/datamanagement receives # to return list of hubs, or href of projects/folders/items to return topfolders, folder contents or versions (respectively). The response should be an array with:

[
 {
  "id": "href id of the hub/project/folder/item or base64 urn for versions (Viewable)",
  "text": "name",
  "type": "hubs/projects/folders/items/versions",
  "children": "false for versions, true for others"
 }
]

GET /api/forge/callback/oauth as the OAuth callback, receives code from Autodesk and redirect to /
GET /api/forge/oauth/url return the sign-in URL (text) so the UI can redirect
GET /api/forge/oauth/signout to finish current session and redirect to /
GET /api/forge/oauth/token return a valid viewables:read access token in the form of {'access_token':value, 'expires_in':value}
GET /api/forge/user/profile returns the user information in the form of {'name':'user name', 'picture': 'http://profilepictureurl'}

For reference, when adding a new language, replicate all nodejs.md/net.md for the new language. The Viewer section should be the same for all languages.

Creating a project

FORK from /autodesk-forge/learn.forge.viewmodels (or viewhubmodels) and rename: learn.forge.TUTORIAL.LANGUAGE, for example: learn.forge.viewmodels.net or learn.forge.viewmodels.nodejs. According to each language standards, move files to appropriate folders.

If the UI changes, first add remote upstream:

git remote add upstream https://github.com/autodesk.forge/learn.forge.viewmodels  (or viewhubmodels)

Then, sync fork:

git fetch upstream
git checkout master
git merge upstream/master

Now sync all changes.

When sample is ready, create a pull request for the branch of the language (e.g. net, node.js).

Variables

Use convention:

PORT: 3000
FORGE_CLIENT_ID
FROGE_CLIENT_SECRET
FORGE_CALLBACK_URL: default http://localhost:3000/api/forge/callback/oauth

This is importat so developers can reuse this with other samples on Autodesk-Forge Github.

Animated GIFs

Whenwhere applicable, use animaged GIF to demonstrate a complex setup. Good results with EZGIF in 5FPS (smaller).

Readme

Tutorial project should be ready to use and include a readme with instructions to setup & run.

Running locally

Install docsify:

npm i docsify-cli -g

Clone this project.

Now serve the /docs folder:

docsify serve ./docs

Open http://localhost:3000

I18n

In order to add a new localization to the project, follow these steps:

Create a new folder under docs, and name it based on the corresponding language code, for example, zh-CN
Add all the localized content to the new folder; the file naming and folder structure of the new content should copy the structure of the docs folder itself, for example:

docs/
    account/
        README.md
    datamanagement/
    ...
    zh-CN/
        account/
            README.md
        datamanagement/
        ...

Use the update-locale-links script to prefix all links in the markdown with the corresponding language code; for example, the following command will go through all files under docs/zh-CN, and replace links like [Viewer](viewer/2legged/) (note that Docsify considers this to be an absolute path!) with [Viewer](/zh-CN/viewer/2legged/):

# from within the project's root folder
./update-locale-links zh-CN

Update the alias property in docs/index.html to make sure that localized pages use the corresponding localized sidebar; map /<lang-code>/.*_sidebar.md to /<lang-code>/_sidebar.md, for example, like so:

    // ...
    alias: {
+         '/zh-CN/.*_sidebar.md': '/zh-CN/_sidebar.md',
        '/.*/_sidebar.md': '/_sidebar.md'
    },
    // ...

Add a link to the new localized content to _docs/navbar.md; for example:

* [EN](/)
+ * [ZH-CN](/zh-CN/)

License

This sample is licensed under the terms of the MIT License. Please see the LICENSE file for full details.

ToshiakiIsezaki/forge.learning