README.md in binda-0.1.3 vs README.md in binda-0.1.4

- old
+ new

@@ -136,31 +136,36 @@ Once the _structure_ has been created it's possible to add field groups. By default there is one field group called *General Details* which is empty. You can customize that or add new ones. In order to add _field settings_ that will let you add content to your _component_ (or _board_) you need to enter on of the _structure's field groups_. -## Retrieve a structure +## Retrieve structure elements Once you create a _structure_ you can call it from your controller like so: ```ruby @my_structure = Binda::Structure.find_by(slug: 'my-structure') ``` From that you can do all sorts of things. ```ruby -# get all field groups +# get all field groups: @field_groups = @my_structure.field_groups -# get all field settings +# get all field settings: +# (loop method) (returns an Array object) @field_settings = [] @field_groups.each do |group| group.field_settings.each do |setting| @field_settings << setting end end +# (single query method) (returns an ActiveRelation object) +@field_settings = Binda::FieldSetting + .includes(field_group: [:structure]) + .where(binda_field_groups: {structure_id: @my_structure.id}) ``` Depending on the structure type, to retrieve all related _components_ or the related _board_ you can use the Binda helper (which is suggested if you care about performance, see [component](#Components) or [board](#Boards)) or do it the usual Ruby on Rails way like so: ```ruby @@ -169,10 +174,24 @@ # if structure is a board type @board = @my_structure.board ``` +To retrieve _field groups_ or a _structure_ from a _field setting_ you can do the following: + +```Ruby +@field_setting = Binda::FieldSetting.find_by(slug: 'my-field') + +# Get the field group +@field_setting.field_group + +# Get the structure +@field_setting.structure +``` + +Note that `@field_setting.structure` is a convenient method Binda offers to get the structure, but don't over think: this doesn't mean there is a association `Binda::Structure --has_many--> Binda::FieldSetting`! The association is always mediated by `Binda::FieldGroup`. + --- # Components @@ -256,13 +275,13 @@ .includes( :strings, :texts, :assets, :selections ) ``` ## Enable preview -When you created the component structure you might have enabled the **preview mode**. The easiest way to integrate the preview with yor application is to update the `config/routes.rb` file with a redirect that binds the component preview url to the controller that is in chardge of showing that component in your application. +When you created the _component structure_ you might want to enable the **preview mode**. The easiest way to integrate the preview with yor application is to update the `config/routes.rb` file with a redirect that binds the _component_ preview url to the controller that is in chardge of showing that _component_ in your application. -For example let's say you have a *animal* structure with slug `animal`: +For example let's say you have a *animal* _structure_ with `slug = animal`: ```ruby # your application single animal route get 'animals/:slug', to: 'animals#show', as: animal @@ -276,15 +295,15 @@ # Boards _Boards_ give you the possibility to have a panel where to list some specific settings. -A great example of a _board_ is the _Dashboard_. This board is useful to store the generic data which can be used throughout the application, like the website name and description. +A great example of a _board_ is the _Dashboard_. This _board_ is useful to store the generic data which can be used throughout the application, like the website name and description. -You can create as many _boards_ you like and add any field you want. To set up a _board_ go to _Structures_ and create a new _structure_ with type "_board_". The name of the structure will determine also the name of the board. Once created a new tab will appear on the main sidebar. The newly created structure is already populated with the _General Details_ field group which is initially empty. To add new field settings you can decide to edit this field group or create a new field group. +You can create as many _boards_ you like and add any field you want. To set up a _board_ go to _Structures_ and create a new _structure_ with type "_board_". The name of the _structure_ will determine also the name of the _board_. Once created a new tab will appear on the main sidebar. The newly created _structure_ is already populated with the _General Details_ _field group_ which is initially empty. To add new _field settings_ you can decide to edit this _field group_ or create a new _field group_. -Once ready you can head to the _board_ page by clicking the tab on the main sidebar and populate the fields with your content. +Once ready you can head to the _board_ page by clicking the tab on the main sidebar and populate the _fields_ with your content. To retrieve _board_ content you can use one of those methods: ```ruby @board = Binda::Board.find_by(slug: 'my_board') @@ -331,23 +350,48 @@ Every _field setting_ is based on a field type. You can create several field settings based on a single field type. Here below a list of field types available and their use: -| Field setting | Use details | -|---|---| -| String | Store a string. No formatting options available. | -| Text | Store a text. TinyMCE let's you format the text as you like. | -| Image | Store image. | -| Video | Store video. | -| Date | Store a date. | -| Radio | Select one choice amongst a custom set. | -| Selection | Select one or more choices amongst a custom set. | -| Check Box | Select one or more choices amongst a custom set. | -| Repeater | Store multiple instances of a field or a collection of fields. | -| Relation | Connect multiple instances of a _component_ or _board_ to each other. | +| Field type | Usage | | +|---|---|---| +| string | Store a string. No formatting options available. | [source](http://www.rubydoc.info/gems/binda/Binda/String) | +| text | Store a text. TinyMCE let's you format the text as you like. | [source](http://www.rubydoc.info/gems/binda/Binda/Text) | +| image | Store image. | [source](http://www.rubydoc.info/gems/binda/Binda/Image) | +| video | Store video. | [source](http://www.rubydoc.info/gems/binda/Binda/Video) | +| date | Store a date. | [source](http://www.rubydoc.info/gems/binda/Binda/Date) | +| radio | Select one choice amongst a custom set. | [source](http://www.rubydoc.info/gems/binda/Binda/Radio) | +| selection | Select one or more choices amongst a custom set. | [source](http://www.rubydoc.info/gems/binda/Binda/Selection) | +| checkbox | Select one or more choices amongst a custom set. | [source](http://www.rubydoc.info/gems/binda/Binda/Checkbox) | +| repeater | Store multiple instances of a field or a collection of fields. | [source](http://www.rubydoc.info/gems/binda/Binda/Repeater) | +| relation | Connect multiple instances of a _component_ or _board_ to each other. | [source](http://www.rubydoc.info/gems/binda/Binda/Relation) | +## Available setting and customization + +Sometime you might want to specify a behaviour or a restriction for a specific _field_. +To konw more about a specific _field_ click on the **source** link where you can find a more comprehensive documentation. + +## Reload! + +In order to keep consistency between _fields_ and their own _settings_ Binda use **callbacks**. + +For example the following line will create a _field setting_, but under the hood it provide each _component_ with the relative _field_: + +```ruby +# Create a field setting +@structure.field_groups_first.field_settings.create(name: 'my text', field_type: 'text') +# => <Binda::FieldSetting id: 1, ...> + +# You don't have to create a text field for each component, it's alreay been done for you +@structure.components.first.texts.first +# => <Binda::Text id: 1, field_setting_id: 1, ...> +``` + +IMPORTANT: Sometimes callbacks run and the `ActiveRecord` object stored in your variable might get outdated. Use `reload` to make sure the `ActiveRecord` in your variable correspond to the real database record. (run `mycomponent.reload`) + +Some callbacks can a bit sneaky. For example _field settings_ with `field_type='radio'` cannot have `allow_null=true` so no matter how many times you try to update `allow_null=true` it will never change. + ## How to get field content Every field setting has a unique `slug`. The default `slug` is made of the `structure name + field group name + field setting name`. If it's a child of a _repeater_ the slug will include the _repeater_ slug as well. You can customise the `slug` as you like keeping in mind that there every `slug` can be attach to only one field setting. In order to retrieve a field content you can use one of the following helpers. @@ -369,11 +413,11 @@ Here below a list of helpers. You can retrieve field content from a instance of `Binda::Component`, `Binda::Board` or `Binda::Repeater`. See [How to get field content](#How_to_get_field_content). -**NOTE: source links are based on the latest public version.** If you are using an older version or a specific branch please refer to the [source](https://github.com/lacolonia/binda/blob/master/app/models/concerns/binda/fieldable_associations.rb) switching to the branch/tag you are looking for. +**NOTE: source links are based on the latest public version.** If you are using an older version or a specific branch please refer to the [source on github](https://github.com/lacolonia/binda/blob/master/app/models/concerns/binda/fieldable_associations.rb) and switch to the branch/tag you are looking for. | Helper ||| |---|---|---| | `has_text`| Returns `true/false` | [source](http://www.rubydoc.info/gems/binda/Binda/FieldableAssociations:has_text) | | `get_text`| Returns the text. Use [`simple_format`](https://apidock.com/rails/ActionView/Helpers/TextHelper/simple_format) to maintain HTML tags. | [source](http://www.rubydoc.info/gems/binda/Binda/FieldableAssociations:get_text) | @@ -516,11 +560,27 @@ To change appereance and behaviour of the page add your styles to `app/assets/stylesheets/maintenance.scss` and your scripts to `app/assets/javascript/maintenance.js`. These are manifest files so if you need jQuery for example, you just need to add `//= jquery` at the top of `maintenance.js` file. --- +# Field settings and field groups +--- + +## Orphans + +Sometime playing with Rails console you might end up creating orphans, which basically are components without a field setting parent. They might cause errors in some queries and they hard to track down. + +To avoid the problem run the following command from your shell: + +```bash +rails binda:remove_orphan_fields +``` + +--- + + # Plugins Here a list of useful plugins: - [Binda Multilanguage](https://github.com/lacolonia/binda_multilanguage) @@ -529,15 +589,12 @@ # Upgrade -Here some upgrade instruction. +If you are going to upgrade from a previous version please check the guidelines attached to the version release which can be found on this [Github page](https://github.com/lacolonia/binda/releases). - -To upgrade from 0.0.6 to 0.0.7 please refer to the [release documentation](https://github.com/lacolonia/binda/releases/tag/0.0.7) - --- # Create a Binda plugin @@ -753,9 +810,10 @@ - comment your code following [Yard guidelines](http://www.rubydoc.info/gems/yard/file/docs/GettingStarted.md) principles (use `yard server -r` to see the HTML version at `http://localhost:8808`, if you make any change to the doc just refresh the page and the documentaion page gets updated automagically) - update the README.rb file, use Github markdown - if you are not adding a core feature consider writing a plugin instead - improve and/or add new I18n translations - when fixing a bug, provide a failing test case that your patch solves +- write deprecation warning for methods instead of deleting them (`app/models/concerns/binda/deprecations.rb`) ## How to work locally Ensure you have installed Binda dependencies. ```bash