diff --git a/src/asciidoc/customizations/buildCustomVcc.adoc b/src/asciidoc/customizations/buildCustomVcc.adoc new file mode 100644 index 000000000000..158b61c19092 --- /dev/null +++ b/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 <>. +* 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] +---- + + { + this.setState({ value: e.currentTarget.value }); + }} + value={this.state.value} + /> + +---- +. 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" +. 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] +---- + { + 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" + +For example: +[source,JavaScript] +"type": "custom" + +== 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] +---- + + + { + this.customVcc.change(e.currentTarget.value); + this.customVcc.save(); + }} + value={this.state.value} + /> +
{this.state.description}
+ +---- +. 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. diff --git a/src/asciidoc/gettingStarted/developer.adoc b/src/asciidoc/gettingStarted/developer.adoc index f31325025d93..7e80e1f29cb6 100644 --- a/src/asciidoc/gettingStarted/developer.adoc +++ b/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 diff --git a/src/asciidoc/videos/imageBestPractices.adoc b/src/asciidoc/videos/imageBestPractices.adoc new file mode 100644 index 000000000000..32fd3803a588 --- /dev/null +++ b/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] diff --git a/src/asciidoc/videos/kaiOS.adoc b/src/asciidoc/videos/kaiOS.adoc new file mode 100644 index 000000000000..ded771d61c81 --- /dev/null +++ b/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] diff --git a/src/asciidoc/videos/starterCourse.adoc b/src/asciidoc/videos/starterCourse.adoc new file mode 100644 index 000000000000..60a0ed6bef88 --- /dev/null +++ b/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]