ClipCC is a powerful scratch-project editor based on scratch-gui which was created by MIT. And it migrates a lot of function from ClipCC 1.x. ClipCC's
This requires you to have Git and Node.js installed.
In your own node environment/application:
yarn install https://github.com/Clipteam/clipcc-gui.git
If you want to edit/play yourself:
git clone https://github.com/Clipteam/clipcc-gui.git
cd clipcc-gui
yarn
Running the project requires Node.js to be installed.
Open a Command Prompt or Terminal in the repository and run:
yarn start
Then go to http://localhost:8601/ - the playground outputs the default GUI component
If you wish to develop clipcc-gui
alongside other scratch repositories that depend on it, you may wish
to have the other repositories use your local clipcc-gui
build instead of fetching the current production
version of the clipcc-gui that is found by default using yarn install
.
Here's how to link your local clipcc-gui
code to another project's node_modules/clipcc-gui
.
-
In your local
clipcc-gui
repository's top level:- Make sure you have run
yarn install
- Build the
dist
directory by runningBUILD_MODE=dist yarn run build
- Establish a link to this repository by running
yarn link
- Make sure you have run
-
From the top level of each repository (such as
scratch-www
) that depends onclipcc-gui
:- Make sure you have run
yarn install
- Run
yarn link clipcc-gui
- Build or run the repositoriy
- Make sure you have run
Instead of BUILD_MODE=dist yarn run build
, you can use BUILD_MODE=dist yarn run watch
instead. This will watch for changes to your clipcc-gui
code, and automatically rebuild when there are changes. Sometimes this has been unreliable; if you are having problems, try going back to BUILD_MODE=dist yarn run build
until you resolve them.
If you can't get linking to work right, try:
- Follow the recipe above step by step and don't change the order. It is especially important to run
yarn install
beforeyarn link
, because installing after the linking will reset the linking. - Make sure the repositories are siblings on your machine's file tree, like
.../.../MY_SCRATCH_DEV_DIRECTORY/clipcc-gui/
and.../.../MY_SCRATCH_DEV_DIRECTORY/scratch-www/
. - Consistent node.js version: If you have multiple Terminal tabs or windows open for the different Scratch repositories, make sure to use the same node version in all of them.
- If nothing else works, unlink the repositories by running
yarn unlink
in both, and start over.
You may want to review the documentation for Jest and Enzyme as you write your tests.
See jest cli docs for more options.
NOTE: If you're a Windows user, please run these scripts in Windows cmd.exe
instead of Git Bash/MINGW64.
Before running any test, make sure you have run yarn install
from this (clipcc-gui) repository's top level.
To run linter, unit tests, build, and integration tests, all at once:
yarn test
To run unit tests in isolation:
yarn run test:unit
To run unit tests in watch mode (watches for code changes and continuously runs tests):
yarn run test:unit -- --watch
You can run a single file of integration tests (in this example, the button
tests):
$(yarn bin)/jest --runInBand test/unit/components/button.test.jsx
Integration tests use a headless browser to manipulate the actual HTML and javascript that the repo produces. You will not see this activity (though you can hear it when sounds are played!).
Note that integration tests require you to first create a build that can be loaded in a browser:
yarn run build
Then, you can run all integration tests:
yarn run test:integration
Or, you can run a single file of integration tests (in this example, the backpack
tests):
$(yarn bin)/jest --runInBand test/integration/backpack.test.js
If you want to watch the browser as it runs the test, rather than running headless, use:
USE_HEADLESS=no $(yarn bin)/jest --runInBand test/integration/backpack.test.js
When running yarn install
, you can get warnings about optionsl dependencies:
npm WARN optional Skipping failed optional dependency /chokidar/fsevents:
npm WARN notsup Not compatible with your operating system or architecture: [email protected]
You can suppress them by adding the no-optional
switch:
yarn install --no-optional
Further reading: Stack Overflow
When installing for the first time, you can get warnings that need to be resolved:
npm WARN [email protected] requires a peer of babel-eslint@^8.0.1 but none was installed.
npm WARN [email protected] requires a peer of eslint@^4.0 but none was installed.
npm WARN [email protected] requires a peer of react-intl-redux@^0.7 but none was installed.
npm WARN [email protected] requires a peer of react-responsive@^4 but none was installed.
You can check which versions are available:
yarn view react-intl-redux@0.* version
You will need to install the required version:
yarn install --no-optional --save-dev react-intl-redux@^0.7
The dependency itself might have more missing dependencies, which will show up like this:
user@machine:~/sources/scratch/clipcc-gui (491-translatable-library-objects)$ yarn install --no-optional --save-dev react-intl-redux@^0.7
[email protected] /media/cuideigin/Linux/sources/scratch/clipcc-gui
├── [email protected]
└── UNMET PEER DEPENDENCY [email protected]
You will need to install those as well:
yarn install --no-optional --save-dev react-responsive@^5.0.0
Further reading: Stack Overflow
If you run into npm install errors, try these steps:
- run
npm cache clean --force
- Delete the node_modules directory
- Delete package-lock.json
- run
npm install
again
You can publish the GUI to github.io so that others on the Internet can view it. Read the wiki for a step-by-step guide.
If you want us to add more function in clipcc3, you can add a issue to tell us what kind of function do you like.
Since so much code throughout scratch-gui depends on the state of the project, which goes through many different phases of loading, displaying and saving, we created a "finite state machine" to make it clear which state it is in at any moment. This is contained in the file src/reducers/project-state.js .
It can be hard to understand the code in src/reducers/project-state.js . There are several types of data and functions used, which relate to each other:
These include state constant strings like:
NOT_LOADED
(the default state),ERROR
,FETCHING_WITH_ID
,LOADING_VM_WITH_ID
,REMIXING
,SHOWING_WITH_ID
,SHOWING_WITHOUT_ID
,- etc.
These are names for the action which causes a state change. Some examples are:
START_FETCHING_NEW
,DONE_FETCHING_WITH_ID
,DONE_LOADING_VM_WITH_ID
,SET_PROJECT_ID
,START_AUTO_UPDATING
,
Like this diagram of the project state machine shows, various transition actions can move us from one loading state to another:
Note: for clarity, the diagram above excludes states and transitions relating to error handling.
Here's an example of how states transition.
Suppose a user clicks on a project, and the page starts to load with URL https://scratch.mit.edu/projects/123456 .
Here's what will happen in the project state machine:
- When the app first mounts, the project state is
NOT_LOADED
. - The
SET_PROJECT_ID
redux action is dispatched (from src/lib/project-fetcher-hoc.jsx), withprojectId
set to123456
. This transitions the state fromNOT_LOADED
toFETCHING_WITH_ID
. - The
FETCHING_WITH_ID
state. In src/lib/project-fetcher-hoc.jsx, theprojectId
value123456
is used to request the data for that project from the server. - When the server responds with the data, src/lib/project-fetcher-hoc.jsx dispatches the
DONE_FETCHING_WITH_ID
action, withprojectData
set. This transitions the state fromFETCHING_WITH_ID
toLOADING_VM_WITH_ID
. - The
LOADING_VM_WITH_ID
state. In src/lib/vm-manager-hoc.jsx, we load theprojectData
into Scratch's virtual machine ("the vm"). - When loading is done, src/lib/vm-manager-hoc.jsx dispatches the
DONE_LOADING_VM_WITH_ID
action. This transitions the state fromLOADING_VM_WITH_ID
toSHOWING_WITH_ID
- The
SHOWING_WITH_ID
state. Now the project appears normally and is playable and editable.
You can contact us by sending an email to [email protected]. We are looking forward to you feedback.
Not now