Skip to content

Commit 4300a80

Browse files
committed
Merge branch 'master' into cli
2 parents 0936551 + 4bb9c2a commit 4300a80

File tree

1 file changed

+0
-151
lines changed

1 file changed

+0
-151
lines changed

‎README.md‎

Lines changed: 0 additions & 151 deletions
Original file line numberDiff line numberDiff line change
@@ -80,157 +80,6 @@ Click on the video below to see how you can edit the program in Visual Studio Co
8080

8181
---
8282

83-
## Usage (without global installation)
84-
We recommend using the aframe-typescript-toolkit CLI for expediency and ease of use. However, if you'd like to create an `aframe-typescript-toolkit` project from scratch. This section is for you.
85-
The code discussed below is similar to the one component template generated by the CLI in the previous section.
86-
87-
An A-Frame typescript component is created in three steps:
88-
1. Setup your project
89-
2. Define and register a component or system class
90-
3. Use your custom component in a local A-Frame project using webpack
91-
4. Export your custom component via GitHub & RawGit to be shared and used in other A-Frame projects
92-
93-
### Project Setup
94-
We recommend creating a directory with the following structure:
95-
```
96-
new-component
97-
│ README.md
98-
│ package.json
99-
│ webpack.config.js
100-
│ tsconfig.json
101-
102-
└───src
103-
│ index.html
104-
│ index.ts
105-
```
106-
107-
We will discuss how to setup your webpack and other configurations below. You can refer to the [example projects](https://github.com/olioapps/aframe-typescript-toolkit/tree/master/examples/position_logger_component) for webpack, node scripts, and tsconfig boilerplate or use a custom setup depending on your needs.
108-
109-
Install A-Frame Typescript Toolkit into your project
110-
111-
`yarn add aframe-typescript-toolkit`
112-
113-
### Create and register your component (or system) class
114-
115-
#### 1. import `ComponentWrapper` and `EntityBuilder` into `index.ts`
116-
117-
```typescript
118-
import { ComponentWrapper, EntityBuilder } from "aframe-typescript-toolkit"
119-
```
120-
#### 2. Define a schema for your component's data
121-
```typescript
122-
interface NewComponentSchema {
123-
readonly color: string
124-
}
125-
```
126-
#### 3. Define your component class by extending ComponentWrapper
127-
```typescript
128-
export class NewComponent extends ComponentWrapper<NewComponentSchema> {
129-
130-
constructor() {
131-
super("new-component", {
132-
color: {
133-
type: "string",
134-
default: "colorless",
135-
},
136-
})
137-
}
138-
139-
init() {
140-
141-
}
142-
}
143-
```
144-
145-
#### 4. Define component behavior
146-
Now you can define the visual aspects or behavior of your component. We'll add an entity on init using `Entity Builder`.
147-
```typescript
148-
...
149-
init() {
150-
const entityColor = this.el.getAttribute("color")
151-
EntityBuilder.create("a-text", {
152-
id: "color-text",
153-
value: entityColor || this.data.color,
154-
color: entityColor || "black",
155-
position: "-1 1.25 0",
156-
}).attachTo(this.el)
157-
}
158-
159-
```
160-
161-
#### 5. Register your component
162-
at the bottom of your `index.ts` file, after defining your component register it so it can be used in your A-Frame scene.
163-
```typescript
164-
new NewComponent().register()
165-
```
166-
### Using your Custom Component Locally
167-
168-
#### 1. Compiling typescript with Webpack
169-
To use your custom component locally, your typescript file must be compiled into javascript. Webpack is a convenient tool to accomplish this. You can configure your 'webpack.config.js` to suit your needs. However, if you're new to webpack or don't require a custom setup, you can copy the [webpack config from one of our examples](https://github.com/olioapps/aframe-typescript-toolkit/blob/master/examples/position_logger_component/webpack.config.js), or use the webpack.config.js generated by the CLI.
170-
171-
See the [webpack](https://webpack.js.org/concepts/) documentation for more details.
172-
173-
#### 2. Include and Install all dependencies
174-
Like the webpack config, you might find it easier to copy the dependencies from one of our [examples](https://github.com/olioapps/aframe-typescript-toolkit/blob/master/examples/position_logger_component/package.json) into your `package.json` file.
175-
176-
Then run `npm install` to install all dependencies
177-
178-
#### 3. Add build scripts
179-
If you have copied the webpack config and dependencies, you can also copy the build scripts from the [example](https://github.com/olioapps/aframe-typescript-toolkit/blob/master/examples/position_logger_component/package.json) into your project's `package.json` file.
180-
```json
181-
...
182-
"scripts": {
183-
"build": "cross-env NODE_ENV=production webpack --config ./webpack.config.js --progress --profile --color --display-error-details --display-cached --bail",
184-
...
185-
```
186-
#### 4. Make a build
187-
In your command line, run `npm build` to create a production build using webpack.
188-
189-
You will see `./dist` directory has been created inside of your root directory (or otherwise if you used a custom webpack configuration).
190-
191-
#### 5. Create an index.html A-Frame Scene
192-
In your `index.html` file (in the root directory), include the scripts for A-Frame as well as your custom component (`/index.js`). The way we have configured our example projects creates a copy of index.html into the /dist folder which is ultimately served. So our index.html file points to `/index.js`. Yours might point to `/dist/index.js` depending on your setup.
193-
194-
In the A-Frame scene, create an entity using your component by including the component's name defined in the constructor. In this example, the component's name is `new-component`.
195-
196-
```html
197-
<html>
198-
<head>
199-
<!-- This is the A-Frame CDN -->
200-
<script src="https://aframe.io/releases/0.8.0/aframe.min.js"></script>
201-
202-
203-
<!-- This is the file you created in the previous step -->
204-
<script type="text/javascript" src="/index.js"></script>
205-
</head>
206-
<body>
207-
<a-scene embedded antialias="true">
208-
<a-sphere
209-
color="red"
210-
position="-1 2 -5"
211-
new-component
212-
>
213-
</a-sphere>
214-
<!-- 'new-component' is the name we gave our component in the constructor-->
215-
<a-box
216-
position="2 3 -10"
217-
new-component
218-
>
219-
</a-box>
220-
<a-sky color="#ECECEC"></a-sky>
221-
<a-light position="0 10 0" color="white" type="point"></a-light>
222-
</a-scene>
223-
</body>
224-
</html>
225-
```
226-
#### 6. View your A-Frame Scene
227-
228-
Locally serve your project to see what you've created. If you were following the examples, you can run the command `yarn start` to serve the project to localhost:3000. This server will listen to any changes you make to the /src directory
229-
230-
Alternatively, you can run a command like `python -m SimpleHTTPServer 3000` from your root directory and then visit your web browser at http://localhost:3000/src. Using this method , remember you'll have to rebuild your project using `npm build` to see any changes to `index.ts`.
231-
232-
<img src="./assets/new-component.png" alt="red ball and colorless box">
233-
23483
### Exporting Custom Components
23584
Seeing your component run locally is great. Now it is time to export it so it can be used by others. There are many ways to do this. One free and convenient way is through GitHub and RawGit
23685

0 commit comments

Comments
 (0)