Merge pull request dotnet#7 from madewithkoji/gatsby-ascii-doc

Gatsby ascii doc

src/asciidoc/customizations/buildCustomVcc.adoc

@@ -0,0 +1,353 @@
+= Building your first custom VCC
+:page-slug: /customizations/build-custom-VCC
+
+Visual Customization Controls (VCCs) enable users to quickly edit elements of your application on Koji.
+The Koji platform includes VCCs for standard elements, such as images, text, and sounds.
+In addition, you can build custom VCCs to provide new types of customizations that match closely with the application you are developing.
+For example, some Koji templates provide tile map editors, sound enhancers, or custom avatar creators to enhance the interactivity for remixers.
+
+In this tutorial, you will build and publish a custom VCC that recreates the standard text VCC on Koji.
+After completing the tutorial, you will be able to use your custom VCC interchangeably with a text VCC.
+
+== Prerequisites
+
+* Familiarity with the Koji editor and remix process.
+For an overview, see the <</getting-started/startGuide1.adoc,starter guide>>.
+* Familiarity with React and ES6 basics are a plus.
+
+== Setting up the consumer application
+
+To test and use your custom VCC, you need a Koji application to act as the "consumer" of it.
+
+. Remix the following scaffold:
++
+https://withkoji.com/~seane/simple-react-scaffold
+. After the editor has loaded, rename the project.
+For example: `Custom VCC Consumer`.
+. In *Customization*, open the `Strings` file.
++
+This file contains one option for `Page Title`, which uses a text VCC.
+You will replace this text VCC with custom VCC that you create in this tutorial.
+
+== Setting up the custom VCC application
+
+Custom VCCs are also applications on Koji.
+You can create them in the same way that you create any application or game -- by remixing a scaffold.
+
+. Remix the following scaffold:
++
+https://withkoji.com/~seane/react-project-no-vccs
+. After the editor has loaded, rename the project.
+For example: `My Custom Text VCC`.
+
+== Adding the custom-vcc-sdk package
+
+The koji-custom-vcc-sdk package enables you to extend Koji applications with custom VCCs.
+
+. At the bottom of the editor, click *New Tab* to open a new terminal tab.
+. Navigate to the frontend folder: `cd frontend`.
+. Install the package.
++
+[source,bash]
+npm install --save @withkoji/custom-vcc-sdk
+. Close the terminal tab.
++
+[source,bash]
+exit
+. In the `frontend` termimal tab, cancel the running process, and then restart it to reflect the change.
++
+[source,bash]
+npm start
+. Click the down arrow in the upper right to collapse the terminal pane.
+
+== Adding a text input and state management
+
+The VCC must provide an input to accept a value from the user and a way to manage the state of the input value.
+
+. Open `/frontend/common/App.js` from the file browser.
+. In the App class, add a state property to store the value.
++
+[source, JavaScript]
+----
+class App extends React.Component {
+  state = { value: '' };
+  ...}
+----
+. Replace the contents of the `Container` component.
++
+[source, JavaScript]
+----
+<Container>
+  <input
+    onChange={(e) => {
+      this.setState({ value: e.currentTarget.value });
+    }}
+    value={this.state.value}
+  />
+</Container>
+----
+. Save the file and refresh the live preview.
++
+You should see a text input in the preview window.
+
+== Import the VCC package and initialize the custom VCC
+
+Next, use the koji-custom-vcc-sdk package you installed earlier to initialize the custom VCC and register it, so that the consumer knows it's ready to use.
+
+. At the top of the `App.js` file, import the package.
++
+[source,JavaScript]
+import CustomVcc from '@withkoji/custom-vcc-sdk';
+. In the App class, initialize the custom VCC.
++
+[source,JavaScript]
+customVcc = new CustomVcc();
+. Add a `componentDidMount` method and register the VCC.
++
+[source,JavaScript]
+----
+componentDidMount() {
+  this.customVcc.register('300','300');
+}
+----
+
+== Testing the custom VCC
+
+To save development time, Koji provides an easy way to test a custom VCC before it is published.
+
+. In your custom VCC project, click the *Remote* tab in the right pane.
+. Click *Copy URL* to get the staging URL for your project.
+. Open your consumer project.
+. In your consumer project, open the `Strings` customization file, and click *Code* to view the raw JSON.
+. For the `title` field, change the `type` to match this format, using the URL you just copied as `YOURURL`:
++
+[source,JavaScript]
+"type": "custom<YOURURL>"
+. Save the file, and return to the *Visual* view of the customization file.
++
+You should see your custom VCC.
+
+== Connecting the custom VCC to the consumer
+
+If you type in your custom VCC in the consumer application, you will see that nothing happens yet.
+To support the dynamic customization updates of a Koji template, the custom VCC must be able to read and update the values in the JSON file of the consumer application.
+
+You can use methods exposed by the custom-sdk-vcc package to get the initial value from the JSON file and then to write a new value to the file when the user changes it in the VCC.
+
+=== Getting the value from the consumer
+
+In your custom VCC, use the `onUpdate` method to get the latest value from the JSON file in the consumer application.
+
+. In the `App.js` file of your custom VCC application, add the following code to the `componentDidMount` method, after the `register` call:
++
+[source,JavaScript]
+----
+this.customVcc.onUpdate(({ value }) => {
+  this.setState({ value });
+});
+----
++
+The `componentDidMount` method should now look like this example:
++
+[source,JavaScript]
+----
+componentDidMount() {
+  this.customVcc.register('300', '300');
+
+  this.customVcc.onUpdate(({ value }) => {
+    this.setState({ value });
+  });
+}
+----
++
+This code automatically updates the state of the VCC component when the value in the consumer application changes.
+. Save the file, and return to your consumer application.
+Switch to the *Code* view, and then back to the *Visual* view to trigger a reload of your custom VCC.
++
+You should now see the correct value in the input.
+
+=== Setting a new value using the custom VCC
+
+In your custom VCC, use the `change` and `save` methods to send changes from the custom VCC to the consumer application.
+
+. In the `App.js` file of your custom VCC application, update the `onChange` function for the input:
++
+[source,JavaScript]
+----
+<input
+  onChange={(e) => {
+    this.customVcc.change(e.currentTarget.value);
+    this.customVcc.save();
+  }}
+  value={this.state.value}
+/>
+----
++
+This code updates the value and triggers a save of the JSON file.
+. Save the file, and return to your consumer application.
+Switch to the *Code* view, and then back to the *Visual* view to trigger a reload of your custom VCC.
++
+You should now be able to update the title of the application using your own custom VCC.
+
+== Publishing your custom VCC
+
+The staging URL makes it easy to test a custom VCC while it is under development.
+However, it is temporary and changes each time you open a new instance of the project.
+Instead, you can publish your custom VCC so that you can use it in other projects and share it with other developers.
+
+. In the left pane, navigate to *Advanced > Custom domains*.
+. In the upper right, click *Add domain*.
+. Under *Choose a Koji root domain*, select `koji-vccs.com`.
+. In *Domain*, enter a unique name for your VCC.
+For example, `myname-custom-text-vcc`.
++
+You will use this name to implement your custom VCC in consumer applications.
+. Click *Add*.
+. In the left pane, click *Publish Now*.
+Give your VCC a descriptive name, and add a thumbnail if you would like.
++
+The name and thumbnail make it easier for other developers to find your custom VCC and understand what it does.
+For a VCC, a custom thumbnail might be a better representation of the functionality than the automatically generated screenshot.
+. Click *Publish App*.
+
+== Using a published custom VCC
+
+After your custom VCC has been published, you can use it by replacing the `type` in your VCC with the domain name you entered in the last step.
+
+[source,JavaScript]
+"type": "custom<YOURDOMAINNAME>"
+
+For example:
+[source,JavaScript]
+"type": "custom<myname-custom-text-vcc>"
+
+== Refining your custom VCC
+
+You can refine the custom VCC by styling it to look more like a standard text VCC.
+In this example, we'll define new styling and use additional information from the consumer application to provide context to our custom VCC input.
+
+. To be able to test your work in progress, open your consumer application and switch back to the staging URL of your custom VCC application.
+. In the `App.js` file of your custom VCC application, remove the unused styled component (`Image`).
+. Replace the `Container` styled component and add the following new styled components near the top of the file.
++
+[source,Javascript]
+----
+const InputContainer = styled.div`
+    display: flex;
+    flex-direction: column;
+    width: 100%;
+
+    input {
+        width: 100%;
+        background-color: rgb(255, 255, 255);
+        color: rgb(17, 17, 17);
+        border-width: 1px;
+        border-style: solid;
+        border-color: rgba(0, 0, 0, 0.1);
+        border-image: initial;
+        border-radius: 0px;
+        padding: 8px;
+        outline: none;
+    }
+
+    input:focus {
+        outline: none;
+        border-width: 1px;
+        border-style: solid;
+        border-color: rgb(21, 122, 251);
+        border-image: initial;
+    }
+
+    .description {
+        width: 100%;
+        opacity: 0.4;
+        font-size: 12px;
+        line-height: 1;
+        padding-top: 4px;
+    }
+`;
+
+const Container = styled.div`
+    background-color: #ffffff;
+    color: #000000;
+    padding: 16px;
+    display: flex;
+    align-items: start;
+    width: calc(100% - 40px);
+`;
+
+const Label = styled.label`
+    display: inline-flex;
+    flex-direction: column;
+    align-items: flex-end;
+    padding-right: 16px;
+
+    .name {
+        font-size: 14px;
+    }
+
+    .variable-name {
+        font-size: 10px;
+        line-height: 1.5;
+        color: rgb(102, 102, 102);
+        opacity: 0.9;
+        font-family: Menlo, Monaco, "Courier New", monospace;
+    }
+`;
+----
+. Update the state assignment to add the following properties.
++
+[source,JavaScript]
+----
+state = {
+  description: '',
+  name: '',
+  value: '',
+  variableName: '',
+};
+----
+. Update the `onUpdate` command to set the values of the additional
+properties with information from the consumer application.
++
+[source,JavaScript]
+----
+this.customVcc.onUpdate(({ value, name, variableName, description }) => {
+  this.setState({
+      description,
+      name,
+      value,
+      variableName,
+  });
+});
+----
+. Replace the contents of the `Container` component with the updated input.
++
+[source,JavaScript]
+----
+<Label>
+    <div className="name">{this.state.name}</div>
+    <div className="variable-name">{this.state.variableName}</div>
+</Label>
+<InputContainer>
+    <input
+        onChange={(e) => {
+            this.customVcc.change(e.currentTarget.value);
+            this.customVcc.save();
+        }}
+        value={this.state.value}
+    />
+    <div className="description">{this.state.description}</div>
+</InputContainer>
+----
+. Save the `App.js` file, return to your consumer application, and reload the VCC.
++
+You should see an updated VCC that looks just like the standard text VCC.
+. Publish your changes to update the presentation of your custom VCC.
+
+== Wrapping up
+
+You've now created a replacement for an existing text VCC and learned the basics of how a custom VCC "talks" to the consumer application.
+
+If you want to create more complex custom VCCs, you can find more information in the https://github.com/madewithkoji/koji-custom-vcc-sdk[package documentation].
+
+You can also find existing custom VCCs by searching for "vcc" on https://withkoji.com.

src/asciidoc/gettingStarted/developer.adoc

@@ -21,7 +21,7 @@ image:Koji-developer.svg[Overview of the Koji development process,title="Koji de
 For some great resources to help you start developing templates on Koji, see:
 
 * link:../gettingStarted/startGuide1.adoc[Starter guide] – Step-by-step instructions on how to create a remixable web application and publish it as a template on Koji.
-* https://withkoji.com/developer/getting-started-course[Starter course] – Video tutorial of how to start developing applications on Koji.
+* link:../videos/starterCourse.adoc[Starter course] – Video tutorial of how to start developing applications on Koji.
 
 == Staying in Touch
 

src/asciidoc/videos/imageBestPractices.adoc

@@ -0,0 +1,8 @@
+= Image resizing and scaling
+:page-slug: /videos/image-best-practices
+
+Watch the following video to learn how to optimize image sizes in your template.
+
+== Video tutorial
+
+video::4KDoYrSK0VE[youtube,560,361]

src/asciidoc/videos/kaiOS.adoc

@@ -0,0 +1,8 @@
+= Develop KaiOS apps with Koji
+:page-slug: /videos/kai-OS
+
+Watch the following video to learn how to develop KaiOS apps with Koji.
+
+== Video tutorial
+
+video::BppAed1R1XM[youtube,560,361]

src/asciidoc/videos/starterCourse.adoc

@@ -0,0 +1,14 @@
+= Developer starter course
+:page-slug: /videos/starter-course
+
+If you are ready to start creating your own remixable templates, we recommend the video below.
+In under an hour, you will learn:
+
+* How to find and remix a scaffold as a starting point for your template.
+* How to import code from a GitHub repository.
+* How to use Koji's packages and tools to make your template remixable.
+* How to publish your template.
+
+== Video tutorial
+
+video::XRWM4w8rwT0[youtube,560,361]