Skip to content

Commit 037e8dd

Browse files
catmandocatmando
committed
Merge branch 'edge' of github.com:hyperstack-org/hyperstack into edge
2 parents 7795ff1 + bf2fa76 commit 037e8dd

2 files changed

Lines changed: 227 additions & 1 deletion

File tree

‎docs/readme.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,7 @@ As it gives a minimal understanding of the Hyperstack framework.
4242

4343
Hyperstack is supported by a friendly, helpful community, both for users, and contributors. We welcome new people, please reach out and say hello.
4444

45-
+ Reach us at: [Gitter chat](https://gitter.im/ruby-hyperloop/chat)
45+
+ Reach us at: [Slack chat](https://hyperstack.org/slack-invite)
4646

4747
## Roadmap
4848

‎upgrade-from-hyperloop.md‎

Lines changed: 226 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,226 @@
1+
## Upgrade Instructions - Part I
2+
3+
### 1. Update your gemfile
4+
5+
```ruby
6+
gem 'rails-hyperstack', '~> 1.0.alpha1.5'
7+
gem 'hyper-spec', '~> 1.0.alpha1.5' # if using hyper-spec
8+
```
9+
10+
remove any references to hotloader stuff from the gemfile, as well as opal-jquery, and hyper-react
11+
(these will all be brought in as needed by rails-hyperstack)
12+
13+
14+
### 2. Move `app/hyperloop` directory to `app/hyperstack`
15+
16+
the internal directories can remain (i.e. components, models, etc)
17+
18+
### 2. Rename `app/hyperstack/component.rb` file.
19+
20+
rename it to component.rbx it is no longer used, but you might want to keep it just in case instead of deleting.
21+
22+
Renaming it to .rbx will effectively remove it, without deleting it.
23+
24+
### 3. Double check `application_record.rb` files are correct.
25+
26+
Your main definition of `ApplicationRecord` should be in `app/hyperstack/models/application_record.rb`
27+
28+
Meanwhile the contents of `app/models/application_record.rb` should look like this:
29+
30+
```ruby
31+
# app/models/application_record.rb
32+
# the presence of this file prevents rails migrations from recreating application_record.rb
33+
# see https://github.com/rails/rails/issues/29407
34+
35+
require 'models/application_record.rb'
36+
```
37+
38+
### 4. Change the component base class from `Hyperloop::Component` to `HyperComponent`
39+
40+
Hyperstack now follows the Rails convention used by ApplicationRecord and ApplicationController
41+
of having an application defined base class.
42+
43+
Create a `app/hyperstack/components/hyper_component.rb` base class:
44+
45+
```ruby
46+
# app/hyperstack/components/hyper_component.rb
47+
class HyperComponent
48+
def self.inherited(child)
49+
child.include Hyperstack::Component
50+
child.param_accessor_style :legacy # use the hyperloop legacy style param accessors
51+
child.include Hyperstack::Legacy::Store # use the legacy state definitions, etc.
52+
end
53+
end
54+
```
55+
56+
Now global search and replace all references in the `app/hyperstack/components` directory from `Hyperloop::Component` to `HyperComponent`
57+
58+
### 5. Update app/assets/javascript/application.js
59+
60+
The last lines of `app/assets/javascripts/application.js` should look like this:
61+
62+
```javascript
63+
//= require hyperstack-loader
64+
//= require_tree .
65+
```
66+
67+
If you are not using require_tree, then the hyperstack-loader require should be towards the bottom, you might have to play with the position to get it right, but basically it should be the last thing required before you get into your application specific requires that are in the `app/assets/javascript` directory.
68+
69+
remove any references to react, react_ujs, hotloader, opal, opal-jquery, and hyperloop-loader, this is all now handled by hyperstack-loader
70+
71+
### 6. Update items related to Hotloader
72+
73+
If you are using the hot loader, and foreman (i.e you have a Procfile) then your procfile will look like this:
74+
```text
75+
# Procfile
76+
web: bundle exec rails s -p 3004 -b 0.0.0.0
77+
hot: bundle exec hyperstack-hotloader -p 25223 -d app/hyperstack/
78+
```
79+
80+
The hotloader gem itself should be removed from the gemfile.
81+
82+
In the hyperstack initializer there should be this line:
83+
```ruby
84+
Hyperstack.import 'hyperstack/hotloader', 'client_only: true if Rails.env.development?'
85+
```
86+
87+
remove any other references to hotloader in the initializer, and in `app/assets/javascripts/application.js`
88+
89+
### 7. Update the initializer
90+
91+
Rename `config/initializers/hyperloop.rb` to `config/initializers/hyperstack.rb`
92+
93+
The initializer will look like this... comment/uncomment as needed:
94+
95+
```ruby
96+
# comment next line out if NOT using webpacker
97+
Hyperstack.cancel_import 'react/react-source-browser' # bring your own React and ReactRouter via Yarn/Webpacker
98+
# uncomment next line if using hotloader
99+
# Hyperstack.import 'hyperstack/hotloader', client_only: true if Rails.env.development?
100+
# set the component base class
101+
102+
Hyperstack.component_base_class = 'HyperComponent' # i.e. 'ApplicationComponent'
103+
104+
# prerendering is default :off, you should wait until your
105+
# application is relatively well debugged before turning on.
106+
107+
Hyperstack.prerendering = :off # or :on
108+
109+
# transport controls how push (websocket) communications are
110+
# implemented. The default is :action_cable.
111+
# Other possibilities are :pusher (see www.pusher.com) or
112+
# :simple_poller which is sometimes handy during system debug.
113+
114+
Hyperstack.transport = :action_cable # or :none, :pusher, :simple_poller
115+
116+
# add this line if you need jQuery
117+
Hyperstack.import 'hyperstack/component/jquery', client_only: true
118+
119+
# change definition of on_error to control how errors such as validation
120+
# exceptions are reported on the server
121+
module Hyperstack
122+
def self.on_error(operation, err, params, formatted_error_message)
123+
::Rails.logger.debug(
124+
"#{formatted_error_message}\n\n" +
125+
Pastel.new.red(
126+
'To further investigate you may want to add a debugging '\
127+
'breakpoint to the on_error method in config/initializers/hyperstack.rb'
128+
)
129+
)
130+
end
131+
end if Rails.env.development?
132+
```
133+
134+
### 8. Change Element to jQ
135+
136+
If you are using jQuery, you will have things like `Element['#some-id'].focus()` etc.
137+
These need to change to `jQ[...].focus()` etc.
138+
139+
Use CASE SENSITIVE global search and replace.
140+
141+
142+
### 9. `IsomorphicHelpers` changes to `Hyperstack::Component::IsomorphicHelpers`
143+
144+
search and replace...
145+
146+
### 10. Stores
147+
148+
To use legacy store behavior you can include the `Hyperstack::Legacy::Store` mixin, in your stores.
149+
150+
You do not need to subclass the stores. However if you have a lot of stores, you could create a base class like this:
151+
152+
```ruby
153+
# app/hyperstack/stores/hyper_store.rb
154+
class HyperStore
155+
include Hyperstack::Legacy::Store
156+
end
157+
```
158+
159+
and then subclass off of Hyperstore.
160+
161+
You will also need to add this to your Gemfile:
162+
163+
```ruby
164+
gem 'hyper-store`, '~> 1.0.alpha1.5'
165+
```
166+
167+
### xx. Change hyperloop to hyperstack in your routes file.
168+
169+
`mount Hyperstack::Engine => '/hyperstack'`
170+
171+
### xx. Hyperstack::ApplicationPolicy
172+
173+
### 10. Change name of Hyperloop::... to Hyperstack::
174+
175+
Hyperloop::Operation -> Hyperstack::Operation
176+
Hyperloop::Store ->
177+
178+
179+
180+
181+
If at this point you have other classes and methods under the `Hyperloop` namespace, you will have to find
182+
the equivilent class or method under Hyperstack. Its going to be a case by case basis. Let us know if you need help, and we can
183+
add each case to this document.
184+
185+
### 11. Remove any patches
186+
187+
If you have any patches to Hyperloop modules or classes, you probably don't need (or want them any more)
188+
189+
## Upgrade Instructions Part II
190+
191+
Once your app is working on the latest Hyperstack, you will want to upgrade to the latest Hyperstack syntax. This can be done gradually
192+
193+
### 1. Tag names
194+
195+
Tag names should all be upcased. i.e. `DIV`, `UL`, `LI`, `SPAN` etc. The lower case syntax is deprecated so this should be updated.
196+
197+
### 2. Param accessors
198+
199+
The legacy syntax to access params was `params.foo`. The standard approach now is to just to use `foo`.
200+
201+
To change this you will need to change `param_accessor_style :legacy` to `param_accessor_style :accessor` in your `HyperComponent` definition.
202+
203+
Then you should be able to do a global search and delete in the component directory of `params.`.
204+
205+
### 3. State definition mutators, and accessors.
206+
207+
State is now represented by instance variables. No special syntax is needed to declare a state variable.
208+
209+
To access a state variable local to a component all you need to do is read the instance variable in the usual way.
210+
211+
To update the state variable (or its contents) you prefix the operation with the mutate method.
212+
213+
For example `mutate @foo[:bar] = 12` would mutate a hash named @foo.
214+
215+
Once all your state accessors are updated you can remove the
216+
217+
```ruby
218+
child.include Hyperstack::Legacy::Store # use the legacy state definitions, etc.
219+
```
220+
221+
from your `HyperComponent` base class.
222+
223+
### 4. Other legacy behaviors
224+
225+
Should be flagged by warnings in console.log. Update as instructed.
226+

0 commit comments

Comments
 (0)