Tramway::Core
If you need translation of this Readme, please message us [email protected]. We'll translate for you and post to this page
tramway-core - это ядро проекта tramway
Этот гем предоставляет базовые классы и реализации для других шаблонов Tramway. Как правило, каждый шаблон Tramway должен иметь в зависимостях последнюю версию гема tramway-core
.
Installation
Gemfile
gem 'tramway-core'
gem 'audited'
gem 'clipboard-rails'
rails g tramway:core:install
config/initializers/tramway.rb
# Initialize application with name
Tramway::Core.initialize_application name: :your_application_name
# Initialize application name with model_class. Model class must be a singlethon
Tramway::Core.initialize_application model_class: ::Tramway::Conference::Unity # example was taken from tramway-conference gem
config/initializers/assets.rb
Rails.application.config.assets.precompile += %w( *.jpg *.png *.js )
Every Tramway application need initialized @application object (or if you create Tramway plugin, it should be @application_engine object).
You don't need to initialize this object yourself, just configurate application with Tramway. You have 2 options of this:
Option 1. If you want to change @application object just in the code base.
rails g tramway:core:install
config/initializers/tramway.rb
Tramway::Core.initialize_application name: :your_application_name
Option 2. If you want to change @application object from admin panel. How to create model that will be an Application Model for the Tramway
1. Generate model that you to use. We create Organization, for example
rails g tramway:core:application
rails db:migrate
2. Add model_class to Initializer
Tramway::Core.initialize_application model_class: Organization
3. Create 1 instance of Organization model
rails c
Organization.create! public_name: 'Tramway', name: :organization, tagline: 'Tramway is not buggy, LOL!', main_image: 'https://raw.githubusercontent.com/ulmic/tramway-dev/develop/logo.png'
4. Add model to singleton to the tramway-admin
admin panel to be able to change its data
Tramway::Admin.set_singleton_models Organization, project: :organization # now you should use organization.name here
5. Then continue configuration of your model in admin panel with tramway-admin gem instruction, starting from point 8
6. Now you are able to change your application main info in admin panel
How-to
add favicon to your application
config/initializers/tramway.rb
::Tramway::Core.initialize_application attribute1: value, another_attribute: another_value, favicon: `/icon.ico` # icon should be in public folder
Usage
Tramway::Core::ApplicationRecord
uploader
Tramway use carrierwave for file uploading by default. To mount uploader you should use uploader
method
Interface: uploader(attribute_name, uploader_name, **options)
- attribute_name - ActiveRecord attribute to mount uploader
- uploader_name - short uploader name. You need to connect uploaders which are compatible with Tramway. Available uploaders:
- options - you are available to set options for uploaders exactly for this model. Available options:
- versions - only for :photo. Set needed versions for file to be cropped. If empty - 0 zero versions will be used. All versions you can see here
- extensions - whitelist of file extensions. If empty will be used default whitelist from the uploaders (links above)
Example:
class User < Tramway::Core::ApplicationRecord
uploader :avatar, :photo, version: [ :small, :medium ], extensions: [ :jpg, :jpeg ]
end
Tramway::Core::ApplicationDecorator
Associations
Your can decorate association models. Supporting all types of association
app/decorators/your_model_decorator.rb
class YourModelDecorator < Tramway::Core::ApplicationDecorator
decorate_association :some_model
decorate_association :another_model, decorator: SpecificDecoratorForThisCase
decorate_association :another_one_model, as: :repeat_here_as_parameter_from_model
decorate_association :something_else_model, state_machines: [ :here_array_of_state_machines_you_want_to_see_in_YourModel_show_page ] # support from tramway-admin gem
end
You can decorate a lot of models in one line
app/decorators/your_model_decorator.rb
class YourModelDecorator < Tramway::Core::ApplicationDecorator
decorate_associations :some_model, :another_model, :another_one_model, :something_else_model
end
Also, you can configurate what associations you want to see in YourModel page in admin panel support only for tramway-admin gem
app/decorators/your_model_decorator.rb
class YourModelDecorator < Tramway::Core::ApplicationDecorator
class << self
def show_associations
[ :some_model, :another_model, :another_one_model ]
end
end
end
Delegating attributes
app/decorators/your_model_decorator.rb
class YourModelDecorator < Tramway::Core::ApplicationDecorator
delegate_attributes :title, :something_else, :another_atttribute
end
Helper methods
date_view
Returns a date in the format depending on localization
app/decorators/*_decorator.rb
def created_at
date_view object.created_at
end
datetime_view
Returns a date and time in the format depending on localization
app/decorators/_decorator.rb*
def created_at
datetime_view object.created_at
end
state_machine_view
Returns the state of an object according to a state machine
app/decorators/_decorator.rb*
def state
state_machine_view object, :state
end
image_view
Returns an image in a particular format depending on the parameters of the original image file
app/decorators/*_decorator.rb
def avatar
image_view object.avatar
end
enumerize_view
Returns object enumerations as text
app/decorators/*_decorator.rb
def field_type
enumerize_view object.field_type
end
Other helpers
CopyToClipboardHelper
app/helpers/tramway/core/copy_to_clipboard_helper.rb
Install
include ::Tramway::Core::CopyToClipboardHelper
How to use it
It will show you in the view in bootstrap styles with font-awesome copy
icon.
Something like this:
copy_to_clipboard "some_id" # some_id is HTML id of element. Content of this element will be copied to the clipboard after pressing the button
In Russian
Базовые классы
- ApplicationDecorator - Базовый класс декоратора. В него по умолчанию включены
ActionView::Helpers
иActionView::Context
иFontAwesome5
(версия гема FontAwesome, которая поддерживает 5 версию шрифта).FontAwesome
считается вTramway
основным шрифтом для иконок. - ApplicationForm - наследованный от Reform::Form класс форм.
- ApplicationRecord - базовый класс для AR моделей
- ApplicationUploader - базовый класс для Carrierwave аплоадеров.
- FileUploader - базовый класс для загрузки файлов
- PhotoUploader - базовый класс для загрузки фотографий
- Вьюха
_messages
- предоставляет отображение ошибок в форме. Совместима с AR и Reform
Локализация
- dates - правила локализации даты
- helpers - часто используемые в формах слова
- models - часто используемые в моделях слова
- state_machines - локализация состояний
Contribution
Contributors
Run tests
make test
Deployment workflow
If you don't have access to push gem to rubygems then
Just create PR to develop branch
If you have access to push gem to rubygems then
- Create PR to develop branch
- After merging PR you should create new release via git-flow this way
git release start (version which you upgraded in lib/tramway-core/version.rb file)
git release finish (version which you upgraded in lib/tramway-core/version.rb file)
git push origin develop
git push origin master
- Then push new version of the gem
rm -rf *.gem && gem build $(basename "$PWD").gemspec && gem push *.gem
License
The gem is available as open source under the terms of the MIT License.